Configuration reference
Identify required secrets, storage paths, bootstrap values and operation-specific settings.
On this page
Application environment#
Load configuration into the process from a protected environment file or secret manager. Do not commit values or pass secrets in command arguments. Use .env.example as the settings reference.
| Variable | Required or default | Purpose |
|---|---|---|
DATABASE_URL |
Required for a working app | Dedicated PostgreSQL connection |
BETTER_AUTH_URL |
Required | Exact browser/public origin; HTTPS in production |
BETTER_AUTH_SECRET |
Required | Random authentication secret |
BRIDGE_ENVELOPE_KEY |
Required for encrypted secret storage | Independent 32 random bytes encoded as base64 |
BRIDGE_PACKAGE_ROOT |
Production default /var/lib/oab/packages; development .local/packages |
Private writable package directory |
BRIDGE_HOST |
127.0.0.1 |
Custom production server bind address |
PORT |
3220 |
Custom production server port |
BRIDGE_BUILD_ID |
working-tree |
Identifier returned by /api/health; set to the deployed revision for traceability |
TEST_DATABASE_URL |
Test-only | Isolated database accepted by the tests |
NODE_ENV |
Set to production by custom server | Controls production origin enforcement |
BRIDGE_WEBSOCKET_ENABLED |
Set by scripts/server.mjs |
Set by the custom server when it serves the socket endpoint |
NEXT_TELEMETRY_DISABLED |
Optional 1 |
Disable framework telemetry during builds |
The auth secret and envelope key have different purposes. Changing the envelope key without a migration/recovery plan can make stored encrypted material unreadable. Preserve it in a separate protected backup.
Bootstrap and recovery only#
| Variable | Operation |
|---|---|
BRIDGE_OWNER_EMAIL, BRIDGE_OWNER_NAME, BRIDGE_OWNER_PASSWORD |
Initial bootstrap |
BRIDGE_OWNER_EMAIL, BRIDGE_OWNER_PASSWORD, BRIDGE_RECOVERY_ACTION |
Owner recovery; action must be RESET_OWNER_PASSWORD |
BRIDGE_MAINTENANCE_ACTION |
retention or prepare-restore |
BRIDGE_MAINTENANCE_SCOPE |
all or owners |
BRIDGE_OWNER_IDS |
Comma-separated owner IDs when scope is owners |
BRIDGE_CONFIRM_RESTORE |
DISABLE_RESTORED_ACCESS for restore preparation |
Unset bootstrap passwords after provisioning. Maintenance commands operate on the database selected by the protected environment. Their scope is not inferred from the current browser project.
Client and helper environment#
AGE_BINARY and AGE_KEYGEN_BINARY can select encryption tools in environments that use those overrides. Windows private storage uses LOCALAPPDATA; the client discovers OS identity using platform tools. CODEX_THREAD_ID is supplied by a compatible Codex runtime and must identify the current session.
The optional transfer helper consumes OPEN_AGENT_BRIDGE_TRANSFER_TOKEN from a protected process environment. Generate a fresh independent token for that temporary endpoint. OPEN_AGENT_BRIDGE_PREFLIGHT_PROJECT is set internally by preflight for a bounded child check. Keep those helper settings scoped to their intended processes.
Origin changes#
Use an origin without a path, credentials or trailing application subdirectory. Changing the public hostname requires updating the process configuration and reviewing affected saved agent configs and origin-bound identity storage. Use a stable origin for production identities.