Configuration

Environment variables, authentication modes, and networking for the self-hosted OneCLI image.

All configuration for the self-hosted images is passed as environment variables. This page covers both editions; variables that only apply to the Enterprise image (onecli/slim) are marked. The full environment variable reference covers the gateway and CLI more broadly.

Core

Variable	Default	Description
DATABASE_URL	-	PostgreSQL connection string. Required.
APP_URL	http://localhost:10254	The public URL of your instance. Used in links and as the base for OAuth callback URLs. Set it to your real https:// URL in production.
ONECLI_ORG_API_KEY	Generated on first start	Enterprise image only. The organization API key seeded at startup. Format: oc_org_ + 64 lowercase hex characters (oc_org_$(openssl rand -hex 32)). A malformed value fails startup loudly rather than being replaced.
ONECLI_ORG_API_KEY_FILE	-	Enterprise image only. Path to a file containing the organization API key. Use with Docker or Kubernetes secrets instead of putting the key in the environment.
SECRET_ENCRYPTION_KEY	Generated by setup	AES-256-GCM key for the secret store. Generated by pnpm run setup / the install script. Keep it safe and store it in your secrets manager — it encrypts your stored secrets.
GATEWAY_INTERNAL_SECRET	Generated by setup	Authenticates the gateway to the API server.
BETTER_AUTH_SECRET	Generated by setup	Signs session cookies. (Renamed from NEXTAUTH_SECRET; if your .env still sets the old name, rename it — everyone signs in again once.)
LOG_LEVEL	info	Log verbosity for the dashboard and API.

If you don’t set ONECLI_ORG_API_KEY, the generated key is printed to the container logs exactly once, marked “Save it now — shown only once.” Prefer setting it yourself so the credential is pinned and never appears in logs.

Networking

Variable	Default	Description
GATEWAY_BASE_URL	host.docker.internal:10255	The gateway address embedded in the proxy configuration that /v1/container-config hands to agents. The default works for agent containers on the same Docker host. Set it to a reachable host and port when agents run elsewhere.
GATEWAY_PORT	10255	The port the gateway listens on inside the container.

The container exposes two ports: 10254 (dashboard and REST API) and 10255 (the gateway proxy agents connect to). Treat 10254 as an admin interface and expose 10255 wherever agents run.

Authentication

The first visit asks you to create an account — email and password. That account owns the instance; after it exists, joining needs an invitation. Create it right away: until you do, whoever reaches the host first becomes the owner.

Variable	Default	Description
BETTER_AUTH_SECRET	Generated by setup	Signs session cookies. Generate with openssl rand -base64 32.
GOOGLE_CLIENT_ID	-	Optional — adds a “Continue with Google” button beside the password form.
GOOGLE_CLIENT_SECRET	-	Optional — Google OAuth client secret. Redirect URI: <API_URL>/auth/callback/google.

You can change your password any time from Account → Preferences, which also signs out every other session.

Database

The compose files in the deploy guides bundle PostgreSQL. To use an external or managed database instead, drop the postgres service and point DATABASE_URL at your database:

DATABASE_URL=postgresql://user:[e-mail]:5432/onecli

Migrations run automatically when the container starts, so the database user needs DDL privileges on the target database.

App integrations

Self-hosted instances connect apps with your own OAuth credentials: create an OAuth app with each provider, then supply its client ID and secret in the dashboard or pre-configure it with environment variables. The app credentials reference lists the variables for every app. Register the callback URL as:

{APP_URL}/v1/apps/{provider}/callback

For example, https://onecli.internal.example.com/v1/apps/github/callback. Per-provider setup is covered in the integration guides.