> ## Documentation Index
> Fetch the complete documentation index at: https://onecli.sh/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/reference/environment-variables) 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.                                                                                                                                                                                      |

<Note>
  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.
</Note>

## Networking

| Variable           | Default                      | Description                                                                                                                                                                                                                                                         |
| ------------------ | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GATEWAY_BASE_URL` | `host.docker.internal:10255` | The gateway address embedded in the proxy configuration that [`/v1/container-config`](/self-hosting/connect-agents) 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:

```bash theme={null}
DATABASE_URL=postgresql://user:password@db.internal.example.com: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](/self-hosting/app-credentials) 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](/integrations/app-connections).