Configuration reference
Every environment variable Cloud processes read, generated from the configuration registries.
10 min read
Updated 2026-10-31
#configuration#environment#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. Environment values are trimmed;
file alternatives remove only one trailing newline. 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.
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. |
CLOUD_DEV_APP_KEYS |
boolean | development | false |
no | Isolated Compose development installation only: enroll the public development fixture keys after Core migrations. Refused outside NODE_ENV=development. |
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. Aliases: DATABASEURL, TLS_DATABASE_URL, POSTGRES_URL, PGURL, PG_URL, TLS_POSTGRES_DATABASE_URL. |
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; separates NATS resource names, not access. Use one NATS account per installation. |
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. |
WORKFLOW_AI_BUDGET |
JSON | runtime | {"maxStepsPerSource":2,"tasksPerMinute":10,"burst":20,"sourcesPer24Hours":2000,"scopeConcurrent":1,"globalConcurrent":4} |
no | Deprecated: bootstraps ai.workflow_budget once when no stored value exists; remove after cld admin settings status --env succeeds. JSON scoped workflow inference budget: active or successful logical requests per source/24h, token-bucket admission per minute and burst, distinct sources per rolling 24h, outstanding tasks per scope and globally; capacity/rate overload uses bounded workflow retries, daily/source limits fail visibly, and cache hits consume no reservation. |
WORKFLOW_AI_ATTEMPT_TIMEOUT_MS |
number | runtime | 60000 |
no | Deprecated: bootstraps ai.workflow_attempt_timeout_ms once when no stored value exists; remove after cld admin settings status --env succeeds. Absolute workflow AI attempt budget in milliseconds, including admission and repair; expiry aborts the provider and follows the bounded retry policy. |
WORKFLOW_AI_QUEUE_TIMEOUT_MS |
number | runtime | 60000 |
no | Deprecated: bootstraps ai.workflow_queue_timeout_ms once when no stored value exists; remove after cld admin settings status --env succeeds. Maximum workflow AI queue wait in milliseconds; recovery fails overdue or lost deliveries visibly so an operator can retry the workflow. |
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 | Deprecated: env only bootstraps gotenberg.url; remove after cld admin settings status --env succeeds. 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. File alternative: APP_SECRET_FILE. |
ADMIN_LOGIN_TOKEN |
string | secret | empty | no | Core only: temporary first-administrator or recovery login token; remove it after normal administrator sign-in works. File alternative: ADMIN_LOGIN_TOKEN_FILE. |
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 | Deprecated: bootstraps gateway.trusted_proxies once when no stored value exists; remove after cld admin settings status --env succeeds. 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. Invalid bootstrap input with no stored row and invalid stored proxy lists stop gateway startup. |
OUTGOING_MAIL_ALLOWED_TARGETS |
list | runtime | empty list | no | Deprecated: bootstraps outgoing_mail.allowed_targets once when no stored value exists; remove after cld admin settings status --env succeeds. 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 are ignored with a bootstrap warning. |
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. File alternative: CLOUD_IDENTITY_KEY_ENCRYPTION_KEY_FILE. |
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. File alternative: CLOUD_IDENTITY_NEXT_KEY_FILE. |
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. File alternative: CLOUD_IDENTITY_PREVIOUS_KEY_FILE. |
CLOUD_OAUTH_BROKER_SECRET |
string | secret | unset | no | Deprecated: Core and OAuth legacy 64-hex broker secret, used only when OAuth has no app key. Configure an OAuth app key instead; retained for this release. File alternative: CLOUD_OAUTH_BROKER_SECRET_FILE. |
CLOUD_APP_KEY |
string | secret | unset | no | App Ed25519 private key for startup bootstrap, background calls and OAuth issuance; alternatively mount CLOUD_APP_KEY_FILE. Requires the direct Core origin. Core and Gateway refuse app keys. Built-in apps need only the key and direct Core origin; retain infrastructure env for Core and Gateway. File alternative: CLOUD_APP_KEY_FILE. |
CLOUD_CORE_INTERNAL_ORIGIN |
string | runtime | unset | no | Direct Core listener origin for app connection bootstrap, OAuth issuance, mandate-backed background work and internal callbacks; never the gateway. Cross-host bootstrap requires verified TLS; install private CAs through NODE_EXTRA_CA_CERTS before the first fetch. |
CLOUD_APP_CREDENTIAL |
string | secret | unset | no | Deprecated: host-run override for the automatically delivered workload credential when no app key is configured; use CLOUD_APP_KEY or CLOUD_APP_KEY_FILE instead. Retained for this release. File alternative: CLOUD_APP_CREDENTIAL_FILE. |
CLOUD_IDENTITY_JWKS_ORIGIN |
string | runtime | unset | no | Deprecated: use CLOUD_CORE_INTERNAL_ORIGIN; the explicit old origin remains honored for this release. Optional private origin of the Core listener for session and invocation JWKS; unset uses CLOUD_CORE_INTERNAL_ORIGIN, then the public issuer origin. |
CLOUD_OAUTH_JWKS_ORIGIN |
string | runtime | unset | no | Deprecated: explicit legacy OAuth JWKS origin, honored for this release. Unset uses Core internal OAuth JWKS through CLOUD_CORE_INTERNAL_ORIGIN, then 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 | Deprecated: bootstraps assistant.rsql_allowed_targets once when no stored value exists; remove after cld admin settings status --env succeeds. 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 are ignored with a bootstrap warning. |
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 | Deprecated: bootstraps gateway.webhook_allowed_targets once when no stored value exists; remove after cld admin settings status --env succeeds. 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 are ignored with a bootstrap warning. |
NATS_ADMIN_SERVERS |
list | runtime | empty list | no | Deprecated: bootstraps gateway.nats_admin_servers once; configure NATS diagnostics in Administration instead. |
NATS_ADMIN_CREDS_FILE |
string | runtime | unset | no | Deprecated: imports system-account .creds file contents into gateway.nats_admin_access at startup; do not combine with NATS_ADMIN_NKEY_SEED_FILE. |
NATS_ADMIN_NKEY_SEED_FILE |
string | runtime | unset | no | Deprecated: imports the user NKey seed contents into gateway.nats_admin_access and selects the nkey format at startup. |
NATS_ADMIN_TLS_CA_FILE |
string | runtime | unset | no | Deprecated: imports CA PEM contents into gateway.nats_admin_tls_ca at startup; no file path is stored. |
Application: gateway
Declared in packages/gateway/src/env.ts.
| Variable | Type | Scope | Default | Required | Description |
|---|---|---|---|---|---|
GATEWAY_INTERNAL_URL |
string | runtime | http://gateway:3000 |
no | Gateway origin advertised to private ingress discovery. Use a unique private network alias when several installations share an ingress network. Also recognized as an internal Cloud host. |
GATEWAY_INGRESS_ENTRYPOINT |
string | runtime | websecure |
no | Traefik entrypoint for app-domain routers emitted by the private HTTP provider. Must name a configured HTTPS entrypoint. |
GATEWAY_INGRESS_PORT |
number | runtime | 3001 |
no | Private ingress provider listener for Traefik HTTP discovery and Caddy certificate admission. Keep this port off public ingress and publish no host port. |
GATEWAY_INSTANCE_ID |
string | runtime | unset | no | Deprecated: remove to use a random per-process gateway identity. An explicit value is still honored for this release. |
Application: mail
Declared in packages/mail/src/env.ts.
| Variable | Type | Scope | Default | Required | Description |
|---|---|---|---|---|---|
MAIL_WORKFLOW_AI_BODY_MAX_CHARS |
number | runtime | 20000 |
no | Deprecated: bootstraps mail.workflow_ai_body_max_chars once; remove after cld admin settings status --env succeeds. Maximum Mail body characters loaded for an AI workflow step; the pilot budget rejects larger bodies visibly without truncation and preserves the original for manual inspection. |
Application: notebooks
Declared in packages/notebooks/src/env.ts.
| Variable | Type | Scope | Default | Required | Description |
|---|---|---|---|---|---|
NOTEBOOKS_SNAPSHOT_ALLOWED_TARGETS |
list | runtime | empty list | no | Deprecated: bootstraps notebooks.snapshot_allowed_targets once when no stored value exists; remove after cld admin settings status --env succeeds. 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. Bare entries cover every port; host:port and [ipv6]:port restrict a host or IP to one port; /0 entries and other invalid entries are ignored with a bootstrap warning. |
Application: notes
Declared in pwas/notes/server/env.ts.
| Variable | Type | Scope | Default | Required | Description |
|---|---|---|---|---|---|
NOTES_PUBLIC_ORIGIN |
string | runtime | unset | yes | Notes only: public website origin used for WebSocket, mutation, and administrator origin checks. |
NOTES_ADMIN_PASSWORD_HASH |
string | secret | unset | no | Notes only: Argon2id operator password hash generated with Bun.password.hash; changing it invalidates all administrator sessions. |
NOTES_TRUSTED_PROXY |
string | runtime | unset | no | Notes only: immediate proxy address allowed to supply the last X-Forwarded-For entry; unset trusts no forwarding header. |
NOTES_STORAGE_BYTES |
number | runtime | unset | yes | Notes only: total reserved application storage budget in bytes; new notes and files pause at 90 percent and existing updates stop at capacity. |
NOTES_MAX_CONNECTIONS |
number | runtime | unset | yes | Notes only: maximum simultaneous WebSockets in this single process, selected from the pre-launch load test. |
NOTES_MAX_OPEN_PADS |
number | runtime | unset | yes | Notes only: maximum documents held in memory at once, selected from the pre-launch load test. |
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. File alternative: CLOUD_LOGIN_VAPID_PRIVATE_KEY_FILE. |
CLOUD_LOGIN_VAPID_SUBJECT |
string | runtime | unset | no | Cloud Login only: operator contact sent to push services, as mailto: or https:// URL. |