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	Auto-generated	AES-256-GCM key for the secret store. If unset, one is generated on first start and persisted to /app/data. Keep that volume, or set the key explicitly and store it in your secrets manager.
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 instance runs in single-user mode by default: no login screen, and anyone who can reach the dashboard has admin access. Keep it on a private network, or enable multi-user mode with Google OAuth:

Variable	Default	Description
NEXTAUTH_SECRET	-	Setting this switches the instance to multi-user mode. Generate with openssl rand -base64 32.
NEXTAUTH_URL	http://localhost:10254	The URL OAuth redirects return to. Set it to your APP_URL in production.
GOOGLE_CLIENT_ID	-	Google OAuth client ID. Required in multi-user mode.
GOOGLE_CLIENT_SECRET	-	Google OAuth client secret. Required in multi-user mode.

In multi-user mode, every user who signs in joins your instance’s shared organization.

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.