Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/omnigent-ai/omnigent/llms.txt

Use this file to discover all available pages before exploring further.

Docker Compose is the most flexible deployment target — it runs on any host where docker compose works: your laptop, a VPS, an EC2 instance, a home server, or on-premises infrastructure. The stack ships a Postgres container alongside the server, so there is nothing external to provision. For Cloud Run, Kubernetes, or any other container platform, use the same docker/Dockerfile image and adapt the platform-specific glue.
The server image contains no harness SDKs and no LLM API keys. Runners (the agent execution layer) still run on user machines. Deploying the server does not move agent execution into the container.

​
Quickstart

1

Clone the deploy directory or copy the compose stack

git clone https://github.com/omnigent-ai/omnigent
cd omnigent/deploy/docker
The compose stack lives in deploy/docker/. You only need this directory on your target host — not the full repo source — if you are running against the pre-built image from GHCR.
2

Generate .env secrets with bootstrap.sh

./bootstrap.sh
bootstrap.sh is idempotent — re-running it leaves already-set secrets alone. It mints three random secrets into .env: POSTGRES_PASSWORD, OMNIGENT_ACCOUNTS_COOKIE_SECRET, and OMNIGENT_OIDC_COOKIE_SECRET (pre-minted so switching to OIDC later is a one-line edit). If you prefer to manage .env yourself, copy the example instead:
cp .env.example .env
# then edit POSTGRES_PASSWORD at minimum
3

Start the stack

docker compose up -d
docker compose logs -f omnigent   # ctrl-c when boot is clean
The server starts on http://localhost:8000. The Postgres container must pass its healthcheck before the server starts; this takes a few seconds on first boot.
4

Open the web UI, create the admin account, invite your team

On first boot the server auto-creates an admin account and prints the generated password to the container logs:
docker compose logs omnigent | grep -A4 "Created initial admin"
The password is also written to /data/admin-credentials on the artifact-data volume — it survives docker compose restart and is deleted by docker compose down -v.Open http://localhost:8000, log in as the admin, then go to your username → Members → Invite member to share single-use invite links with teammates.To pre-seed the admin password (useful for headless or CI deploys where you cannot read logs), set it before first boot:
# Add to .env:
OMNIGENT_ACCOUNTS_INIT_ADMIN_PASSWORD=your-strong-password
5

Connect your laptop as a runner host

Once the server is up, register your machine so sessions created in the web UI run on it:
omnigent login http://localhost:8000
omnigent host http://localhost:8000
Or point a single run directly at the server:
omnigent run path/to/agent.yaml --server http://localhost:8000

​
Key environment variables

The .env file (generated by bootstrap.sh from .env.example) controls the full server configuration. Secrets live in .env; non-secret settings can go in the optional config.yaml file.
VariableDefaultPurpose
POSTGRES_PASSWORDrequiredPassword for the bundled Postgres container. Set by bootstrap.sh.
POSTGRES_USER / POSTGRES_DBomnigentDB user and database name.
OMNIGENT_PORT8000Host port the server is published on.
OMNIGENT_AUTH_ENABLED1 (in compose)Master auth switch. 1 → accounts or OIDC; 0 → single-user local mode.
OMNIGENT_AUTH_PROVIDERunsetExplicit mode override: accounts, oidc, or header.
OMNIGENT_ACCOUNTS_COOKIE_SECRETminted by bootstrap.sh32-byte hex cookie secret for built-in accounts mode.
OMNIGENT_ACCOUNTS_BASE_URLauto-detectedPublic URL of the server. Required for any deploy reachable through a domain.
OMNIGENT_ACCOUNTS_INIT_ADMIN_PASSWORDunsetPre-seed the admin password instead of auto-generating it.
OMNIGENT_OIDC_ISSUERunsetOIDC provider base URL. Its presence (with auth on) switches the mode to OIDC.
OMNIGENT_OIDC_CLIENT_IDunsetOAuth client ID from your IdP.
OMNIGENT_OIDC_CLIENT_SECRETunsetOAuth client secret from your IdP.
OMNIGENT_OIDC_COOKIE_SECRETminted by bootstrap.sh32-byte hex cookie secret for OIDC mode.
OMNIGENT_OIDC_ALLOWED_DOMAINSunsetComma-separated domain allowlist (critical for Google OAuth on external consent screens).
OMNIGENT_DOMAINunsetYour server’s public domain. Used to derive the OIDC redirect URI and by the Caddy HTTPS overlay.
DATABASE_URL and ARTIFACT_DIR are computed by compose and injected automatically — do not set them manually in the default stack.

​
Database options

Postgres (default). The compose stack provisions a postgres:16-alpine container and wires DATABASE_URL automatically. This is the recommended option for any shared deploy. The database lives on a named Docker volume (postgres-data) and survives container restarts. SQLite (lite tier). For a single-user or demo deploy with no external database, drop the postgres service from docker-compose.yaml and set: 
# In .env:
DATABASE_URL=sqlite:////data/artifacts/chat.db
The .db file lives on the artifact-data volume and survives docker compose restart. Tradeoff: single instance only, no managed backups. Bring your own Postgres (Neon or external). Set DATABASE_URL to any postgres:// or postgresql:// connection string in .env. The entrypoint normalizes it to the psycopg3 dialect automatically. Neon is the fastest external option — create a free database and paste the connection string. Reset everything (drops the DB and artifact store): 
docker compose down -v

​
HTTPS overlay (Caddy)

For any deploy reachable through a public domain, use the bundled Caddy overlay to get automatic Let’s Encrypt TLS: 
# In .env:
OMNIGENT_DOMAIN=omnigent.example.com
OMNIGENT_ACME_EMAIL=you@example.com    # optional, for Let's Encrypt notices

# Point DNS A/AAAA records at the host, then:
docker compose -f docker-compose.yaml -f docker-compose.https.yaml up -d
Caddy auto-provisions and renews the certificate. The omnigent container stops being directly exposed; only ports 80 and 443 are published. Requires Docker Compose 2.24+ for the overlay’s !reset directive.

​
Managed hosts (cloud sandboxes)

Instead of a laptop acting as the runner host, you can have the server provision disposable cloud sandboxes automatically on each session. Add a sandbox: section to the server config (/data/config.yaml): 
sandbox:
  provider: modal
  server_url: https://your-host     # public URL sandboxes dial back to
Sessions created with "host_type": "managed" trigger automatic sandbox provisioning. Modal credentials (MODAL_TOKEN_ID / MODAL_TOKEN_SECRET) must be available in the server’s environment. See the deploy README for the full managed-host walkthrough, including LLM credential injection and custom images.

​
Auth configuration

By default, docker compose up starts the server with built-in accounts auth (OMNIGENT_AUTH_ENABLED=1). To switch to OIDC SSO or header-proxy mode after deploying, update .env and restart: 
docker compose up -d
For the full auth walkthrough — including GitHub OAuth, Google Workspace, and generic OIDC — see the Auth page.

Build docs developers (and LLMs) love

Get started for freeTalk to us