Environment variables

Validated once at startup with a strict schema — a missing or malformed required variable fails the process immediately with a clear message, rather than surfacing as a confusing runtime error later. Only MASTER_KEY, ENCRYPTION_KEYRING, ACTIVE_ENCRYPTION_KEY_ID, DATABASE_URL, and REDIS_URL have no default and must be set; everything else ships with a production-ready value.

Required

Variable	Format	Notes
`MASTER_KEY`	String, 32+ chars	Full-access operator key. Generate with `openssl rand -base64 48`.
`ENCRYPTION_KEYRING`	JSON object	Maps key ids to 64-character hex AES keys. Keep old ids during rotation.
`ACTIVE_ENCRYPTION_KEY_ID`	Key id	Must exist in `ENCRYPTION_KEYRING`; encrypts every new envelope.
`DATABASE_URL`	Postgres connection URL
`REDIS_URL`	Redis connection URL

Server

Variable	Default	Controls
`PORT`	`4000`	HTTP listen port.
`TRUSTED_PROXY_HOPS`	`0`	Number of rightmost, operator-controlled proxy hops trusted in `X-Forwarded-For`. `0` ignores the header.
`NODE_ENV`	`development`	`development` \| `test` \| `production`.
`LOG_LEVEL`	`info`	`debug` \| `info` \| `warn` \| `error`.
`SHUTDOWN_TIMEOUT_MS`	`10000`	Drain budget on `SIGTERM`/`SIGINT` before forcing exit.

Requests, logging, and limits

Variable	Default	Controls
`OBSERVABILITY_SUCCESS_SAMPLE_RATE`	`0.01`	Sampling rate for non-degraded successful operations. Non-success and degraded operations are always sampled.
`OBSERVABILITY_PAYLOAD_RETENTION_DAYS`	`7`	Encrypted forensic payload retention.
`OBSERVABILITY_METADATA_RETENTION_DAYS`	`30`	Retention for completed operation and upstream-attempt metadata.
`OBSERVABILITY_PAYLOAD_MAX_BYTES`	`32768`	Maximum size of each request, response, error, and attempt component in an encrypted sample after redaction.
`IMAGES_MAX_MULTIPART_BYTES`	`805000000` (~805 MB)	Aggregate cap on an image multipart upload (images + mask + fields), streamed to temporary disk.
`AUDIO_MAX_MULTIPART_BYTES`	`30000000` (30 MB)	Aggregate cap on an audio transcription multipart upload.
`RESPONSES_STORE_DEFAULT`	`true`	Default for `store` when a `/v1/responses` request omits it. Set `false` for privacy-first deployments.
`RESPONSES_STATE_RETENTION_DAYS`	`14`	How long a stored Response (with `store: true`) stays retrievable via `GET /v1/responses/:id`.
`RESPONSES_WEBSOCKET_MAX_CONNECTIONS`	`1000`	Maximum live Responses WebSocket connections per gateway process.
`RESPONSES_WEBSOCKET_MAX_CONNECTIONS_PER_KEY`	`20`	Maximum live Responses WebSocket connections for one virtual key (the master key has its own scope).
`RESPONSES_WEBSOCKET_MAX_QUEUED_TURNS`	`64`	Maximum queued `response.create` turns per connection; one turn is processed at a time.
`RESPONSE_STATE_GC_INTERVAL_MS`	`3600000` (1h)	How often the in-process job deletes expired response state.

Runtime extensions

Variable	Default	Controls
`BIFROST_EXTENSION_MAX_FAILURES`	`3`	Consecutive hook failures before an extension instance is disabled for that process.
`BIFROST_EXTENSIONS_RELOAD_INTERVAL_MS`	`15000`	How often each replica polls for a changed extension registry to hot-reload.
`BIFROST_EXTENSIONS_MAX_CODE_BYTES`	`1000000` (1 MB)	Maximum size of an uploaded extension module's source.
`BIFROST_EXTENSION_HOOK_TIMEOUT_MS`	`5000`	Per-hook wall-clock budget. `0` disables the timeout. An exceeded hook is aborted and counts as a failure.

Observability (OpenTelemetry)

Variable	Default	Controls
`OTEL_ENABLED`	`false`	Master switch. Metrics/traces are otherwise not exported at all.
`OTEL_SERVICE_NAME`	`bifrost`	Service name attached to exported telemetry.
`OTEL_METRIC_EXPORT_INTERVAL_MS`	`60000`	How often metrics are pushed to the collector.

These are read by the gateway's own schema. Once OTEL_ENABLED=true, the exporters (OTLPMetricExporter, OTLPTraceExporter) also read the standard OpenTelemetry SDK environment variables directly — notably OTEL_EXPORTER_OTLP_ENDPOINT and OTEL_EXPORTER_OTLP_HEADERS — which are not gateway-specific and so aren't validated by the schema above. See Observability for a working example.

Boolean variables (RESPONSES_STORE_DEFAULT, OTEL_ENABLED) accept 1/true/yes/on or 0/false/no/off, case-insensitively.