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.

Omnigent supports three authentication modes, selected at server start via environment variables. The framework default — a bare local omnigent server — leaves auth off: single-user header mode, no login, every request is the shared local user. The containerized deploys (Docker Compose, Render, Railway, Fly.io, Modal, HF Spaces) set OMNIGENT_AUTH_ENABLED=1 by default in their entrypoints, since a network-exposed instance should always be authenticated. With auth on, the mode is determined by your configuration: supply OMNIGENT_OIDC_ISSUER and you get oidc; supply nothing extra and you get the built-in accounts flow. OMNIGENT_AUTH_PROVIDER is an explicit escape hatch that pins the mode and overrides this auto-selection.
A local server running without OMNIGENT_AUTH_ENABLED=1 has no access control — every request is treated as the single local user. Never expose such a server publicly. All deploy targets in this documentation set OMNIGENT_AUTH_ENABLED=1 by default.

​
Auth modes

ModeWhen to useWhat’s needed
accountsStandalone deploy, no external IdP. Built-in username/password with first-user-is-admin bootstrap and UI-based invites. Default when OMNIGENT_AUTH_ENABLED=1 and no OIDC vars are set.OMNIGENT_AUTH_ENABLED=1. OMNIGENT_ACCOUNTS_COOKIE_SECRET (minted by bootstrap.sh). OMNIGENT_ACCOUNTS_BASE_URL for any deploy behind a public domain.
oidcStandalone deploy with your own IdP: server handles the full login flow.OMNIGENT_AUTH_ENABLED=1 + OMNIGENT_OIDC_ISSUER (presence of the issuer selects this mode automatically). Requires HTTPS (session cookie uses the __Host- prefix).
headerBehind an existing SSO proxy (oauth2-proxy, AWS ALB OIDC, Tailscale Funnel, Databricks Apps) that injects X-Forwarded-Email.OMNIGENT_AUTH_PROVIDER=header. The proxy must strip any inbound copy of the header from clients.

​
Built-in accounts

Built-in accounts mode requires no external identity provider. It is the default for all deploy targets when OMNIGENT_AUTH_ENABLED=1 and no OIDC issuer is configured. First boot auto-creates an admin user (named after the operator’s OS user, falling back to admin in headless containers) with a randomly generated password. The password is printed to the container logs and saved to /data/admin-credentials on the persistent volume: 
# Docker Compose
docker compose logs omnigent | grep -A4 "Created initial admin"

# Fly.io
fly logs -a <your-app>

# Modal
modal app logs omnigent
To pre-seed a known password instead of auto-generating one, set this before first boot: 
OMNIGENT_ACCOUNTS_INIT_ADMIN_PASSWORD=your-strong-password
Inviting teammates. Sign in as the admin, then go to your username → Members → Invite member. The server generates a single-use invite link; share it with the teammate. They pick their own username and password when they redeem it. Sign-out is in the same account menu. Key variables for accounts mode: 
OMNIGENT_AUTH_ENABLED=1
OMNIGENT_ACCOUNTS_COOKIE_SECRET=<64-hex-chars>          # minted by bootstrap.sh
OMNIGENT_ACCOUNTS_BASE_URL=https://omnigent.example.com  # public URL; required for domain deploys
OMNIGENT_ACCOUNTS_INIT_ADMIN_PASSWORD=                   # optional: pre-seed admin password
OMNIGENT_ACCOUNTS_SESSION_TTL_HOURS=8                    # optional
OMNIGENT_ACCOUNTS_INVITE_TTL_HOURS=72                    # optional

​
OIDC SSO

OIDC mode lets your team sign in with the accounts they already have — Google, GitHub, Okta, Microsoft Entra, or any identity provider that publishes /.well-known/openid-configuration. The server handles the full login flow itself (/auth/login, /auth/callback, /auth/logout) with a signed session cookie. No separate auth proxy or container is needed. Setting OMNIGENT_OIDC_ISSUER while OMNIGENT_AUTH_ENABLED=1 automatically selects OIDC mode — no separate provider flag is needed. Alternatively, pin OMNIGENT_AUTH_PROVIDER=oidc explicitly. Supported providers:

GitHub

Register at github.com/settings/developers → New OAuth App. Callback: https://<your-domain>/auth/callback. Issuer: https://github.com.

Google Workspace

Create OAuth credentials at console.cloud.google.com → APIs & Services → Credentials. Issuer: https://accounts.google.com. Set OMNIGENT_OIDC_ALLOWED_DOMAINS.

Okta / Auth0 / Keycloak

Set OMNIGENT_OIDC_ISSUER to your tenant’s base URL. The server fetches /.well-known/openid-configuration at startup.

Microsoft Entra ID

Set OMNIGENT_OIDC_ISSUER to your Entra tenant URL. The server fetches /.well-known/openid-configuration at startup.
Required environment variables for OIDC mode: 
OMNIGENT_AUTH_ENABLED=1
OMNIGENT_OIDC_ISSUER=https://accounts.google.com     # or your provider's base URL
OMNIGENT_OIDC_CLIENT_ID=…
OMNIGENT_OIDC_CLIENT_SECRET=…
OMNIGENT_OIDC_COOKIE_SECRET=<64-hex-chars>           # openssl rand -hex 32
OMNIGENT_DOMAIN=omnigent.example.com                 # server derives redirect URI from this
The server derives the OIDC redirect URI as https://<OMNIGENT_DOMAIN>/auth/callback. Register that exact URL as the callback in your IdP app. Domain allowlists. For Google with an external consent screen, any Google account can log in unless you restrict it: 
OMNIGENT_OIDC_ALLOWED_DOMAINS=example.com,subsidiary.example.com
The allowed_domains list in the server’s config.yaml, the OMNIGENT_OIDC_ALLOWED_DOMAINS env var, and a <data_dir>/allowed_domains file are all unioned. Admin-listed and invited identities bypass the domain check. Invite links for external collaborators. To let one person outside your allowed domains in without opening the allowlist: 
OMNIGENT_OIDC_ALLOW_INVITES=1
An admin can then mint a single-use invite link (POST /auth/invite). Admins. Admins are declared in the server config.yaml (or the <data_dir>/admins file) by email address. Promotion is additive — removing an entry never demotes; demote from the Members page: 
# /data/config.yaml
admins: [you@yourcompany.com]
allowed_domains: [yourcompany.com]
Migrating from accounts to OIDC. If you already have a team on built-in accounts and want to switch, remap identities first so admin rights and sessions carry over: 
omnigent debug migrate-accounts-to-oidc <DB_URL> --domain example.com           # dry run
omnigent debug migrate-accounts-to-oidc <DB_URL> --domain example.com --commit  # apply
Then add your email to the admins: list in config and set OMNIGENT_AUTH_PROVIDER=oidc.

​
Header proxy auth

Header mode takes the caller’s identity from the X-Forwarded-Email request header. It is designed for deployments that sit behind an SSO proxy — oauth2-proxy, Cloudflare Access, an AWS ALB OIDC listener, Databricks Apps, or Tailscale Funnel — that authenticates the user and injects the header on every request. 
OMNIGENT_AUTH_PROVIDER=header
In header mode the server trusts whatever the header says. Requests without the header are rejected with 401. A misconfigured proxy that does not strip client-supplied X-Forwarded-Email before forwarding allows any caller to impersonate any user by sending the header themselves.
For almost everyone, use built-in accounts (the default in these deploys) or oidc. Only choose header when you already operate a trusted proxy that sets and sanitizes the identity header. A misconfigured proxy exposes every user’s sessions, conversation history, tool output, and files to every other caller.
The full OIDC walkthrough (provider-specific steps for GitHub, Google Workspace, and generic OIDC) and the header-proxy security notes are in the deploy READMEs: deploy/docker/README.md and deploy/README.md.

​
CLI login

Once the server is up, sign in from any machine with: 
omnigent login https://your-host
login detects the server’s auth mode automatically — built-in accounts, OIDC, and header-auth proxies all work with the same command. The token is stored locally and reused by omnigent run, omnigent attach, and omnigent host: 
# Register your machine as a runner host after login
omnigent host https://your-host

# Or point a single run at the server directly
omnigent run path/to/agent.yaml --server https://your-host

Build docs developers (and LLMs) love

Get started for freeTalk to us