Auth & SSO

Omnigent supports three ways to authenticate users. Pick the one that fits your setup:

Built-in accounts

If you deployed with Docker or a cloud platform, auth is already enabled by default with built-in accounts.

Non-Docker deploys

For non-Docker deploys, enable built-in accounts manually:

OMNIGENT_AUTH_ENABLED=1 omni server start

1. Create the first admin.
   • For better security, the server never auto-generates a password. When no admin is configured, the server will report needs_setup.
   • To configure, open the web UI and create an admin account or run omni server in a terminal and answer the username and password prompt.
   • For headless deploys, preset the password with --admin-password or OMNIGENT_ACCOUNTS_INIT_ADMIN_PASSWORD.
2. Invite teammates.
   • Go to Admin > Members > Invite to create a single-use invite link.
   • No email server needed; just send the link directly. Signup is invite-only.

Single sign-on (OIDC)

Let your team sign in with Google, GitHub, Okta, or Microsoft. Adding an OIDC issuer flips the mode to SSO. No extra flag needed.

Set the following in deploy/docker/.env:

OMNIGENT_OIDC_ISSUER=https://accounts.google.com
OMNIGENT_DOMAIN=agents.yourcompany.com
OMNIGENT_OIDC_CLIENT_ID=...
OMNIGENT_OIDC_CLIENT_SECRET=...

docker compose up -d    # restart to apply

The only outside step is creating an app with your provider (e.g. Google Cloud Console, or GitHub > Settings > Developer settings) to get the client ID and secret. Set its callback URL to https://<your-domain>/auth/callback.

Custom email claim

Omnigent reads the user's identity from the email claim of the IdP's id_token by default. Some providers omit that claim — Microsoft Entra ID commonly issues only preferred_username (the UPN) — which fails login with Could not determine user email. Point Omnigent at the claim that carries the identity instead:

OMNIGENT_OIDC_EMAIL_CLAIM=preferred_username
OMNIGENT_OIDC_SKIP_EMAIL_VERIFICATION=1

email_verified describes the email claim only, so a custom claim carries no verified marker. Logins are rejected unless you also set OMNIGENT_OIDC_SKIP_EMAIL_VERIFICATION=1 to waive that gate — only enable this for an IdP you trust to vouch for the claim. When set, the claim value is trimmed and normalized like an email address. This applies to the generic-OIDC path only; GitHub always requires a verified primary email.

Header-based auth

If your server sits behind an existing SSO proxy (e.g. OAuth2 Proxy, Cloudflare Access) that injects a trusted header, Omnigent can read the user identity directly from X-Forwarded-Email. No additional auth configuration is needed on the Omnigent side.

Access control

Once auth is enabled, control who can sign in and what they can access.

Scope depends on the auth mode. allowed_domains applies to OIDC sign-ins only; leaving it empty means no domain restriction. Built-in accounts are invite-only, so domain allowlists do not apply there, and header-based auth delegates identity entirely to your proxy. The admins list works in both built-in accounts and OIDC modes.

Admins and the management surface

Admins are the identities in the admins list (above), plus anyone you add to the runtime-editable <data_dir>/admins file (reloaded without a restart). Listed identities are promoted to admin on their next sign-in.

Admins get three management sections in the web UI under Settings, in both built-in accounts and OIDC modes:

• Settings > Members — the user roster (username, role, last login).
• Settings > Policies — server-wide contextual policies.
• Settings > Sharing — the server-wide session-sharing policy (see Session sharing below).

In built-in accounts mode, Members also carries the management actions (Invite member, per-user Reset password, and Remove); under OIDC it is a read-only roster, since identities are owned by your IdP and provisioned on first sign-in. Separately, every signed-in account (built-in or OIDC) gets a Settings > Account section showing who they're signed in as, with a sign-out control and, in built-in accounts mode only, Change password.

Session sharing

Admins set a server-wide sharing policy that governs how users can share sessions with each other. It applies to every session on the server and changes only new grants — revoke, listing existing grants, session ownership, and grants already in place keep working in every mode. Configure it two ways:

• At boot, with the OMNIGENT_SHARING_MODE environment variable.
• At runtime, from Settings > Sharing in the web UI. This persists an override that takes effect immediately, without a restart.

The sharing mode has four tiers:

OMNIGENT_SHARING_MODE=read_only omni server start

An unset or unrecognized value fails open to on. Under restricted_read_only, a workspace is considered too broad to share when its path is the filesystem root (/), root's home (/root), or a direct child of a home parent such as /home/alice, /Users/bob, or /var/home/carol; a subdirectory of a home (e.g. /home/alice/proj) stays shareable.

Public access

Separately from the tiers above, a public-access switch controls whether a session can be shared with anyone who has the link (public read access). It is independent of the sharing mode — you can keep normal user-to-user sharing on while disabling public links.

OMNIGENT_PUBLIC_SHARING=off omni server start

Public access is enabled unless the value is explicitly falsy (0 / false / no / off); unset or unrecognized fails open to enabled. It is also editable at runtime from Settings > Sharing. When disabled, the Share dialog hides its Public access toggle and the server rejects new public grants; sessions already shared publicly stay public until revoked.

Domain allowlist

Restrict sign-ups to specific email domains. In your server config (/data/config.yaml):

allowed_domains: [yourcompany.com]
admins: [you@yourcompany.com]

Invite outsiders

Need to let in someone outside your domain, like a contractor? Set OMNIGENT_OIDC_ALLOW_INVITES=1 and send them a one-time invite link.

Migration

Already using one auth mode and want to switch? These commands move your existing users across without losing sessions or admin rights.

From built-in accounts to SSO

If you started with built-in accounts and want to switch to OIDC, one command brings everyone across so they keep their sessions and admin rights:

omni debug migrate-accounts-to-oidc <database-url> --domain yourcompany.com --commit

Without --commit the command is a dry run that reports what would change without modifying anything.