# Configuration reference

Generated by `bun scripts/generate-config-docs.ts` from the environment registries; do not edit by hand.
Each variable is declared once with a schema, default and scope. Values are trimmed and
empty values are treated as unset. `runtime` variables configure deployed processes,
`secret` variables are credentials, and `development` variables only matter for host-run
development or tooling. For the prose guide, read
[Runtime configuration](/en/docs/operations/runtime-configuration).

## Platform

Declared in `packages/cloud/src/config/env.ts`.

| Variable | Type | Scope | Default | Required | Description |
| --- | --- | --- | --- | --- | --- |
| `NODE_ENV` | string | runtime | unset | no | Release images set `production`; `development` enables development-only behavior such as insecure cookies and HTTP issuers. |
| `HOSTNAME` | string | runtime | unset | no | Container or host name; the default instance identity in worker leases and gateway registration. |
| `DATABASE_URL` | string | runtime | unset | no | Postgres connection read by Bun SQL and by application-owned pools. |
| `REDIS_URL` | string | runtime | unset | no | Valkey connection used by Bun Redis for caches and rate limits. Aliases: `VALKEY_URL`. |
| `NATS_SERVERS` | list | runtime | empty list | no | Comma-separated NATS JetStream bootstrap servers; the client dials all of them. |
| `SYNC_NAMESPACE` | string | runtime | empty | no | Sync namespace shared by every app of one installation; isolates its NATS resources from other installations on the same cluster. |
| `SYNC_REPLICAS` | 1 \| 3 \| 5 | runtime | `3` | no | Persistent JetStream replica count (1, 3 or 5); keep it consistent across the installation and migrate existing resources before changing it. |
| `NATS_CREDS_FILE` | string | runtime | unset | no | Path to a mounted NATS `.creds` file (JWT and NKey); unset means server-side no-auth. |
| `NATS_TLS_CA_FILE` | string | runtime | unset | no | Path to a mounted CA certificate that enables TLS to NATS; unset means plain TCP. |
| `NATS_IGNORE_CLUSTER_UPDATES` | boolean | runtime | `true` | no | Only dial the listed servers and ignore cluster-advertised peer addresses; set to `false` when every advertised address is reachable. |
| `APP_URL` | string | runtime | unset | no | Public Cloud URL used to bootstrap the `app.url` setting; the stored setting wins once written. |
| `GOTENBERG_URL` | string | runtime | unset | no | Internal Gotenberg base URL used to bootstrap the `gotenberg.url` PDF rendering setting; the stored setting wins once written. |
| `APP_SECRET` | string | secret | empty | no | Deployment-wide secret for at-rest settings encryption and signed cursors; generate once with `openssl rand -hex 32` and never change it after data has been written. |
| `ADMIN_LOGIN_TOKEN` | string | secret | empty | no | Core only: temporary first-administrator or recovery login token; remove it after normal administrator sign-in works. |
| `OUTGOING_MAIL_ALLOWED_TARGETS` | list | runtime | empty list | no | Comma-separated host names, IP addresses and CIDR ranges on internal networks allowed for outgoing mail SMTP and bounce IMAP connections; unset allows only public targets, an explicit value replaces this default, and invalid entries including `/0` stop the owning process at startup. |
| `GEO_ALLOWED_TARGETS` | list | runtime | `geo` | no | Comma-separated host names, IP addresses and CIDR ranges on internal networks allowed for Geo requests; unset allows public targets and `geo`, an explicit value replaces this default, and invalid entries including `/0` stop the owning process at startup. |
| `CLOUD_IDENTITY_KEY_ENCRYPTION_KEY` | string | secret | unset | no | Core only: 64-hex KEK for platform identity signing keys stored in Postgres; generate once with `openssl rand -hex 32` and never distribute it to other apps. |
| `CLOUD_IDENTITY_NEXT_KEY` | string | secret | unset | no | Core only: pre-distributed next KEK before promoting it to current; cannot be combined with `CLOUD_IDENTITY_PREVIOUS_KEY`. |
| `CLOUD_IDENTITY_PREVIOUS_KEY` | string | secret | unset | no | Core only: old KEK set during an explicit rolling rewrap of stored identity signing keys, then removed. |
| `CLOUD_OAUTH_BROKER_SECRET` | string | secret | unset | no | Core and OAuth only: 64-hex secret that lets the OAuth app request token signatures from Core; generate independently with `openssl rand -hex 32`. |
| `CLOUD_CORE_INTERNAL_ORIGIN` | string | runtime | unset | no | Direct Core listener origin for OAuth issuance, mandate-backed background work and internal callbacks; host-run callers use the Core port, not the gateway. |
| `CLOUD_APP_CREDENTIAL` | string | secret | unset | no | App-bound workload credential provisioned through Core's admin workload API; background apps such as Mail need one with `identity:invoke`. |
| `CLOUD_IDENTITY_JWKS_ORIGIN` | string | runtime | unset | no | Optional private origin of the Core listener for session and invocation JWKS; unset fetches keys from the public issuer origin. |
| `CLOUD_OAUTH_JWKS_ORIGIN` | string | runtime | unset | no | Optional private origin of the OAuth listener for OAuth JWKS; unset fetches keys from the public issuer origin. |
| `APP_DIR` | string | development | unset | no | Application directory for standalone consumers running `@k2b/cloud/scripts/build.ts` or the SSR dev server outside the monorepo; defaults to the package directory. |
| `CLOUD_DESKTOP_SQLITE_PATH` | string | development | unset | no | SQLite file used by `desktop.sql` in the Bun desktop process; defaults to `.local/desktop.sqlite` in the working directory. |

## Application: assistant

Declared in `packages/assistant/src/env.ts`.

| Variable | Type | Scope | Default | Required | Description |
| --- | --- | --- | --- | --- | --- |
| `ASSISTANT_RSQL_ALLOWED_TARGETS` | list | runtime | `rsql` | no | Comma-separated host names, IP addresses and CIDR ranges on internal networks allowed for Assistant rsql requests; unset allows public targets and `rsql`, an explicit value replaces this default, and invalid entries including `/0` stop the owning process at startup. |
| `CLOUD_CLI_CHROMIUM` | string | runtime | unset | no | Path to a Chromium executable for Assistant code mode when Playwright's bundled browser is unavailable; the assistant image sets `/usr/bin/chromium`. |

## Application: gateway-ops

Declared in `packages/gateway-ops/src/env.ts`.

| Variable | Type | Scope | Default | Required | Description |
| --- | --- | --- | --- | --- | --- |
| `GATEWAY_OPS_WEBHOOK_ALLOWED_TARGETS` | list | runtime | empty list | no | Comma-separated host names, IP addresses and CIDR ranges on internal networks allowed for health webhooks; unset allows only public targets, an explicit value replaces this default, and invalid entries including `/0` stop the owning process at startup. |
| `NATS_ADMIN_SERVERS` | list | runtime | empty list | no | Optional comma-separated NATS system-account servers used only for Gateway Ops cluster diagnostics. |
| `NATS_ADMIN_CREDS_FILE` | string | runtime | unset | no | Path to the mounted system-account `.creds` file for NATS diagnostics; do not combine with the NKey seed file. |
| `NATS_ADMIN_NKEY_SEED_FILE` | string | runtime | unset | no | Path to a static system-account NKey seed file for NATS diagnostics; an alternative to the `.creds` file. |
| `NATS_ADMIN_TLS_CA_FILE` | string | runtime | unset | no | Path to the CA certificate that enables TLS for the NATS diagnostics connection. |

## Application: gateway

Declared in `packages/gateway/src/env.ts`.

| Variable | Type | Scope | Default | Required | Description |
| --- | --- | --- | --- | --- | --- |
| `GATEWAY_INSTANCE_ID` | string | runtime | unset | no | Stable identity of this gateway router instance in the registry; defaults to `HOSTNAME`, then `gateway-router`. |
| `GATEWAY_TRUSTED_PROXIES` | list | runtime | `127.0.0.0/8,::1/128,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,fc00::/7` | no | Comma-separated IP addresses or CIDR ranges of the reverse proxies allowed to name the client in `X-Forwarded-For`; the default trusts loopback and private networks, which covers Traefik on a Docker network. Set the proxy's exact address or subnet when clients on private networks reach the gateway directly or through a proxy that appends to their `X-Forwarded-For`. An invalid entry stops the gateway at startup. |

## Application: notebooks

Declared in `packages/notebooks/src/env.ts`.

| Variable | Type | Scope | Default | Required | Description |
| --- | --- | --- | --- | --- | --- |
| `NOTEBOOKS_SNAPSHOT_ALLOWED_TARGETS` | list | runtime | empty list | no | Comma-separated host names, IP addresses and CIDR ranges on internal networks that notebook S3 snapshots may upload to, for example `minio,10.20.0.0/16`; unset allows only public storage. An entry covers every port on that host or range; `/0` entries and other invalid entries stop Notebooks at startup. |

## Application: pulse

Declared in `packages/pulse/src/env.ts`.

| Variable | Type | Scope | Default | Required | Description |
| --- | --- | --- | --- | --- | --- |
| `PULSE_SCRAPE_ALLOWED_TARGETS` | list | runtime | empty list | no | Comma-separated host names, IP addresses and CIDR ranges on internal networks that Pulse metrics sources may scrape, for example `prometheus,10.20.0.0/16`; unset allows only public endpoints. An entry covers every port on that host or range; `/0` entries and other invalid entries stop Pulse at startup. |

## Application: pwa-auth

Declared in `pwas/pwa-auth/server/env.ts`.

| Variable | Type | Scope | Default | Required | Description |
| --- | --- | --- | --- | --- | --- |
| `CLOUD_LOGIN_VAPID_PUBLIC_KEY` | string | runtime | unset | no | Cloud Login only: VAPID public key for sign-in push notifications; generate the pair once with `bunx web-push generate-vapid-keys`. Unset disables push. |
| `CLOUD_LOGIN_VAPID_PRIVATE_KEY` | string | secret | unset | no | Cloud Login only: VAPID private key matching `CLOUD_LOGIN_VAPID_PUBLIC_KEY`; changing it invalidates every phone's push subscription. |
| `CLOUD_LOGIN_VAPID_SUBJECT` | string | runtime | unset | no | Cloud Login only: operator contact sent to push services, as `mailto:` or `https://` URL. |