Configuration¶
codex-lb runs with zero configuration — every setting has a working default, and container vs. host environments are auto-detected. Configure only what a docs page for your scenario tells you to.
Settings are environment variables with the CODEX_LB_ prefix, or a .env.local file next to the process. The commented sample lives at .env.example.
The settings that matter¶
| Variable | Default | When to set it |
|---|---|---|
CODEX_LB_DATA_DIR |
~/.codex-lb (host) / /var/lib/codex-lb (Docker) |
Move the data directory (DB, encryption key, archives) |
PORT |
2455 |
Change the listen port on host (uvx/local) runs — process environment only, not .env.local (env files map only CODEX_LB_-prefixed variables). In Docker the container always listens on 2455 (the entrypoint pins --port 2455); change the host side of the compose ports mapping instead (e.g. "8080:2455") |
CODEX_LB_DATABASE_URL |
SQLite in the data dir | Use PostgreSQL — see Database |
CODEX_LB_ENCRYPTION_KEY_FILE |
auto-generated in the data dir | Pin the key location (recommended for Docker volumes and required to be shared across replicas) |
CODEX_LB_DASHBOARD_AUTH_MODE |
standard |
trusted_header / disabled — see Authentication |
CODEX_LB_FIREWALL_TRUST_PROXY_HEADERS |
false |
Behind a reverse proxy — see Remote Access |
CODEX_LB_FIREWALL_TRUSTED_PROXY_CIDRS |
127.0.0.1/32,::1/128 |
CIDRs allowed to set X-Forwarded-For |
CODEX_LB_OAUTH_CALLBACK_HOST |
auto-detected (0.0.0.0 in containers) |
Rarely — bind the OAuth login callback explicitly |
Everything else¶
The remaining settings (timeouts, connection pools, bulkheads, session bridge, leader election, observability, circuit breakers, ...) are advanced operational tunables with tested defaults. The full generated settings reference lists every variable with its type and default. Do not tune them unless the documentation for your specific scenario says so:
- Deployment on Kubernetes / multi-replica
- Remote access and reverse proxies
- Database backends
- Troubleshooting
Runtime behavior such as the routing strategy, upstream stream transport, per-account limits, the routing weights and overload isolation window (Settings → Advanced → Routing: in-flight penalty, leased-token weight, lease TTL, overload isolation seconds, error-rate weighting), and the upstream timeouts and request budgets (Settings → Advanced → Upstream timeouts: connect timeout, proxy/compact/transcription budgets, Responses stream request budget, HTTP session bridge request budget, stream idle timeout, downstream WebSocket idle timeout, SSE keepalive interval) is configured live in the dashboard under Settings — no restart required. The resilience toggles (soft drain, deterministic failover, circuit breaker) live there too, under Settings → Advanced → Resilience, as do the background job switches (Auth Guardian, automations scheduler, reset-credit polling) under Settings → Advanced → Background jobs — the loops read the value at the start of every cycle, so a pause applies on the next tick without a restart; their CODEX_LB_* variables remain a deprecated fallback for one release while the dashboard value is unset. The Codex session prewarm switch (one generate=false warm-up on the first turn of a new Codex session, one extra upstream request per new session) lives under Settings → Advanced → Session bridge; CODEX_LB_HTTP_RESPONSES_SESSION_BRIDGE_CODEX_PREWARM_ENABLED stays as the same kind of deprecated fallback. Per-model context window overrides are rows in Settings → Advanced → Model catalogue (slug → reported context window, clamped to the upstream max_context_window); a row wins over the CODEX_LB_MODEL_CONTEXT_WINDOW_OVERRIDES entry for its slug, and that variable remains a deprecated per-slug fallback for one release. The conversation archive toggle (Settings → Advanced → Conversation archive) is dashboard-managed as well: enabling it asks for confirmation, every effective on/off change is written to the audit log with the actor when the authentication mode carries one, and CODEX_LB_CONVERSATION_ARCHIVE_ENABLED remains a deprecated fallback while the dashboard value is unset; the archive directory stays environment-only because each replica writes its own local shard. The HTTP bridge operation spool retention (Settings → Data retention) is dashboard-managed too: the spool holds the raw request payloads and response events durable bridge recovery replays, so a shorter window deletes that prompt material sooner, and the API refuses a value below the longest window in which a spooled operation can still be replayed (it names the binding term). If the environment alias alone already sits below that floor — a state no dashboard save ever passed — startup warns about it and the dashboard still accepts changes that do not make it worse, while refusing any that would deepen it; CODEX_LB_HTTP_RESPONSES_SESSION_BRIDGE_OPERATION_SPOOL_RETENTION_SECONDS remains a deprecated fallback for one release. While a setting is still inherited, the dashboard's "Inherited from environment" badge shows the value of the replica that served the page, so on a multi-replica deployment whose replicas disagree it is not the whole picture — setting the value in the dashboard is what makes it identical everywhere.
Where settings live¶
The dashboard is the primary configuration surface. Environment variables are for two things only: values needed before the database is reachable (data directory, database URL, encryption key, port) and values that legitimately differ between replicas (advertise URLs, trusted-proxy CIDRs, bind hosts). Everything an operator might change while the proxy is running — caps, timeouts, retries, feature toggles, retention — belongs in the dashboard and takes effect on every replica without a restart. Where a dashboard setting also has an environment fallback, precedence is fixed: code default, then environment, then a value set in the dashboard; the environment never overrides a value you set in the dashboard, and clearing the dashboard value returns to the environment (or default). When scripting PUT /api/settings, send only the fields you intend to change: effective values echoed back from GET are stored as explicit dashboard values.
This is the placement rule for new and migrated settings. Environment-only values that remain are bootstrap and per-replica topology (T0/T1) and the incident-debug switches (T4), plus the deprecated aliases of settings the dashboard already owns. CODEX_LB_TELEMETRY_ENABLED follows the rule: it is a fallback that applies only until a telemetry decision is saved in the dashboard, and a saved decision is never overridden by it (see telemetry). The settings reference lists what is currently read from the environment; the MIGRATING registry in app/core/config/tiers.py that tracked the remaining moves is now empty — every behaviour tunable either has a dashboard home or became a fixed constant. The rule, the tier of each setting, and the deprecation path for environment variables are specified in configuration-tiers.
Specs: deployment-installation · replica-operations · configuration-tiers