Settings Reference
GENERATED — edit scripts/generate_settings_reference.py, not this file.
Regenerate with uv run python scripts/generate_settings_reference.py;
tests/unit/test_settings_reference.py fails when this page drifts from
app/core/config/settings.py.
codex-lb currently exposes 96 settings. Every setting is an environment
variable, normally with the CODEX_LB_ prefix (process environment or .env /
.env.local next to the process); aliased settings list every accepted name.
All defaults work with zero configuration —
start from Configuration for the handful that matter,
and treat everything else as advanced operational tunables.
Tiers
The Tier column is the configuration policy for each setting
(app/core/config/tiers.py, enforced by scripts/check_settings_tiers.py):
T0 bootstrap — needed before the database is reachable; env only.T1 instance topology — legitimately differs per replica or deployment; env only.T2 secret — encrypted in the database; env is at most a seed.T3 behaviour tunable / feature flag — the dashboard is the management
surface. T3 → dashboard marks a setting that already has a
dashboard_settings column of the same name: the dashboard value wins and
the variable is a deprecated fallback. T3 (env, migrating) marks the
remaining env-only backlog.T4 incident debug — env allowed, dashboard toggle recommended.
PORT (special case, no prefix)The listen port (default 2455) is read from the bare PORT process
environment variable, not a CODEX_LB_* setting, and applies to host
(uvx/local) runs only — env files map only 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.
CODEX_LB_ENV_FILE (special case, bootstrap only).env / .env.local are discovered next to the installed module root (the
repository checkout). CODEX_LB_ENV_FILE — an os.pathsep-separated list
of paths — overrides that discovery for installs whose module root cannot
contain env files (the Nix package wrapper points it at the launch
directory). It must be set in the process environment, not in an env file:
the env-file locations have to be known before env files are read.
CODEX_LB_WORKERS_PER_INSTANCE (special case, startup guard)Not a setting: the only supported value is 1 (one worker process per
instance), so there is nothing to configure. If it is set to anything else,
startup fails with a settings validation error — per-account concurrency caps
are partitioned per replica via the bridge ring, and multiple worker processes
inside one instance would silently multiply them. Scale horizontally via
replicas instead.
Process-level environment variables (not settings)
These are third-party or POSIX conventions codex-lb honors without
making them settings. They are read by their owning launcher, library, or
frozen migration rather than through Settings. Together with Settings
itself this table is the allowlist of environment reads under app/;
anything else belongs in app/core/config/settings.py.
Environment variable(s)
Consumer
HOST, PORT, SSL_CERTFILE, SSL_KEYFILE, UVICORN_TIMEOUT_KEEP_ALIVE, UVICORN_WS_MAX_SIZEUvicorn launch defaults read once by the codex-lb CLI (app/cli.py); host runs only.
HTTP_PROXY, HTTPS_PROXY, ALL_PROXY, WS_PROXY, NO_PROXY (and lowercase)Outbound proxy conventions honored by httpx/aiohttp/websockets for upstream egress.
REQUEST_METHODCGI marker; when present HTTP_PROXY is ignored (httpoxy guard, mirrors the httpx/requests rule).
TZPOSIX process timezone; automation schedules with the server_default timezone resolve to it (falling back to the host local zone, then UTC).
PROMETHEUS_MULTIPROC_DIRprometheus_client multiprocess-mode convention.
GITHUB_TOKENOptional bearer token for the GitHub latest-release version check.
POD_IP, POD_NAME, HOSTNAME, KUBERNETES_SERVICE_HOSTKubernetes/pod identity used for multi-replica validation and deployment-kind telemetry.
CODEX_HOME, USERPROFILE, WSL_DISTRO_NAMECodex CLI home discovery for the codex-lb codex-sessions retag tool.
CODEX_LB_TEST_DATABASE_URLTest-suite/CI only: overrides the database used by the test session factory.
CODEX_LB_ADDITIONAL_QUOTA_REGISTRY_FILE (inside app/db/alembic/versions/** only)Frozen Alembic migrations read the process environment directly because migrations must not depend on Settings; the live setting of the same name is documented in the tables below.
Core
Environment variable
Tier
Type
Default
CODEX_LB_DATA_DIRT0
Path~/.codex-lb (host) / /var/lib/codex-lb (container)
Database
Environment variable
Tier
Type
Default
CODEX_LB_DATABASE_ALEMBIC_AUTO_REMAP_ENABLEDT0
boolTrue
CODEX_LB_DATABASE_MAX_OVERFLOWT1
int15
CODEX_LB_DATABASE_MIGRATE_ON_STARTUPT0
boolTrue
CODEX_LB_DATABASE_MIGRATION_LOCK_TIMEOUT_SECONDST0
float300.0
CODEX_LB_DATABASE_MIGRATIONS_FAIL_FASTT0
boolTrue
CODEX_LB_DATABASE_POOL_SIZET1
int25
CODEX_LB_DATABASE_SQLITE_PRE_MIGRATE_BACKUP_ENABLEDT0
boolTrue
CODEX_LB_DATABASE_SQLITE_PRE_MIGRATE_BACKUP_MAX_FILEST0
int5
CODEX_LB_DATABASE_SQLITE_STARTUP_CHECK_MODET0
'quick' \| 'full' \| 'off''quick'
CODEX_LB_DATABASE_URLT0
strsqlite+aiosqlite:///<data_dir>/store.db
Encryption
Environment variable
Tier
Type
Default
CODEX_LB_ENCRYPTION_KEY_FILET0
Path<data_dir>/encryption.key
CODEX_LB_ENCRYPTION_KEY_FINGERPRINT_MODET0
'enforce' \| 'warn' \| 'off''enforce'
Upstream transport
Environment variable
Tier
Type
Default
CODEX_LB_UPSTREAM_BASE_URLT1
str'https://chatgpt.com/backend-api'
CODEX_LB_UPSTREAM_CONNECT_TIMEOUT_SECONDST3 (dashboard)
float8.0
CODEX_LB_UPSTREAM_ROUTE_CACHE_TTL_SECONDST1
float60.0
CODEX_LB_UPSTREAM_WEBSOCKET_TRUST_ENVT1
boolauto-detected from outbound proxy env vars
HTTP & streaming
Environment variable
Tier
Type
Default
CODEX_LB_COMPACT_REQUEST_BUDGET_SECONDST3 (dashboard)
float180.0
CODEX_LB_HTTP_CONNECTOR_LIMITT1
int100
CODEX_LB_HTTP_CONNECTOR_LIMIT_PER_HOSTT1
int50
CODEX_LB_HTTP_RESPONSES_STREAM_REQUEST_BUDGET_SECONDST3 (dashboard)
float7200.0
CODEX_LB_SSE_KEEPALIVE_INTERVAL_SECONDST3 (dashboard)
float10.0
CODEX_LB_STREAM_IDLE_TIMEOUT_SECONDST3 (dashboard)
float7200.0
CODEX_LB_TRANSCRIPTION_REQUEST_BUDGET_SECONDST3 (dashboard)
float120.0
HTTP Responses session bridge
Environment variable
Tier
Type
Default
CODEX_LB_HTTP_RESPONSES_SESSION_BRIDGE_ADVERTISE_BASE_URLT1
str \| NoneNone
CODEX_LB_HTTP_RESPONSES_SESSION_BRIDGE_CODEX_PREWARM_ENABLEDT3 (dashboard)
boolFalse
CODEX_LB_HTTP_RESPONSES_SESSION_BRIDGE_ENABLEDT4
boolTrue
CODEX_LB_HTTP_RESPONSES_SESSION_BRIDGE_INSTANCE_IDT1
strprocess hostname
CODEX_LB_HTTP_RESPONSES_SESSION_BRIDGE_INSTANCE_RINGT1
list[str][]
CODEX_LB_HTTP_RESPONSES_SESSION_BRIDGE_MAX_SESSIONST1
int256
CODEX_LB_HTTP_RESPONSES_SESSION_BRIDGE_OPERATION_EVENT_SPOOL_BATCH_SIZET1
int32
CODEX_LB_HTTP_RESPONSES_SESSION_BRIDGE_OPERATION_EVENT_SPOOL_FLUSH_INTERVAL_SECONDST1
float0.1
CODEX_LB_HTTP_RESPONSES_SESSION_BRIDGE_OPERATION_EVENT_SPOOL_MAX_BYTEST1
int2097152
CODEX_LB_HTTP_RESPONSES_SESSION_BRIDGE_OPERATION_EVENT_SPOOL_MAX_PENDING_BYTEST1
int33554432
CODEX_LB_HTTP_RESPONSES_SESSION_BRIDGE_OPERATION_EVENT_SPOOL_MAX_PENDING_EVENTST1
int2048
CODEX_LB_HTTP_RESPONSES_SESSION_BRIDGE_OPERATION_SPOOL_FORMATT1
'rows_v1' \| 'chunks_v2''rows_v1'
CODEX_LB_HTTP_RESPONSES_SESSION_BRIDGE_OPERATION_SPOOL_RETENTION_SECONDST3 (dashboard)
float604800
CODEX_LB_HTTP_RESPONSES_SESSION_BRIDGE_QUEUE_LIMITT1
int8
CODEX_LB_HTTP_RESPONSES_SESSION_BRIDGE_REQUEST_BUDGET_SECONDST3 (dashboard)
float7200.0
Proxy admission & account caps
Environment variable
Tier
Type
Default
CODEX_LB_PROXY_ACCOUNT_CAP_PARTITION_SCALE_DOWN_SECONDST1
int60
CODEX_LB_PROXY_ACCOUNT_CAPS_SCOPET1
'partitioned' \| 'replica''partitioned'
CODEX_LB_PROXY_ACCOUNT_ERROR_RATE_WEIGHTING_ENABLEDT3 (dashboard)
boolTrue
CODEX_LB_PROXY_ACCOUNT_INFLIGHT_PENALTY_PCTT3 (dashboard)
float2.5
CODEX_LB_PROXY_ACCOUNT_LEASE_TOKEN_WEIGHTT3 (dashboard)
float1.0
CODEX_LB_PROXY_ACCOUNT_LEASE_TTL_SECONDST3 (dashboard)
float900.0
CODEX_LB_PROXY_ACCOUNT_RESPONSE_CREATE_LIMITT3 (dashboard)
int4
CODEX_LB_PROXY_ACCOUNT_STREAM_LIMITT3 (dashboard)
int8
CODEX_LB_PROXY_ACCOUNT_STREAM_RECOVERY_RESERVET3 (dashboard)
int1
CODEX_LB_PROXY_API_KEY_FAIR_SHARE_CONGESTION_THRESHOLD_PCTT3 (dashboard)
int0
CODEX_LB_PROXY_DOWNSTREAM_WEBSOCKET_IDLE_TIMEOUT_SECONDST3 (dashboard)
float120.0
CODEX_LB_PROXY_OVERLOAD_ISOLATION_SECONDST3 (dashboard)
int1800
CODEX_LB_PROXY_REQUEST_BUDGET_SECONDST3 (dashboard)
float600.0
CODEX_LB_PROXY_RESPONSE_CREATE_LIMITT1
int256
CODEX_LB_PROXY_UNAUTHENTICATED_CLIENT_CIDRST1
list[str][]
OAuth
Environment variable
Tier
Type
Default
CODEX_LB_OAUTH_CALLBACK_HOSTT1
str127.0.0.1 (host) / 0.0.0.0 (container)
Token refresh
Environment variable
Tier
Type
Default
CODEX_LB_AUTH_GUARDIAN_ENABLEDT3 (dashboard)
boolTrue
Usage
Environment variable
Tier
Type
Default
CODEX_LB_ADDITIONAL_QUOTA_REGISTRY_FILET1
Path \| NoneNone
CODEX_LB_RATE_LIMIT_RESET_CREDITS_REFRESH_ENABLEDT3 (dashboard)
boolTrue
Model registry
Environment variable
Tier
Type
Default
CODEX_LB_MODEL_CONTEXT_WINDOW_OVERRIDEST3 (dashboard)
dict[str, int]{}
CODEX_LB_MODEL_REGISTRY_CLIENT_VERSIONT1
str'0.158.0'
CODEX_LB_MODEL_REGISTRY_SNAPSHOT_MAX_AGE_SECONDST1
int86400
Firewall
Environment variable
Tier
Type
Default
CODEX_LB_FIREWALL_IP_CACHE_TTL_SECONDST1
int30
CODEX_LB_FIREWALL_TRUST_PROXY_HEADERST1
boolFalse
CODEX_LB_FIREWALL_TRUSTED_PROXY_CIDRST1
list[str]['127.0.0.1/32', '::1/128']
FORWARDED_ALLOW_IPS (alias CODEX_LB_FORWARDED_ALLOW_IPS)T1
str \| NoneNone
Dashboard
Environment variable
Tier
Type
Default
CODEX_LB_CONNECT_ADDRESST1
str \| NoneNone
CODEX_LB_DASHBOARD_AUTH_MODET1
'standard' \| 'trusted_header' \| 'disabled''standard'
CODEX_LB_DASHBOARD_AUTH_PROXY_GROUPS_HEADERT1
str'Remote-Groups'
CODEX_LB_DASHBOARD_AUTH_PROXY_HEADERT1
str'Remote-User'
CODEX_LB_DASHBOARD_BOOTSTRAP_TOKENT0
str \| NoneNone
CODEX_LB_DASHBOARD_TRUST_LOOPBACK_HOST_HEADER_FOR_LONG_SESSIONST1
boolFalse
Conversation archive
Environment variable
Tier
Type
Default
CODEX_LB_CONVERSATION_ARCHIVE_DIRT1
Path<data_dir>/conversation-archive
CODEX_LB_CONVERSATION_ARCHIVE_ENABLEDT3 (dashboard)
boolFalse
CODEX_LB_CONVERSATION_ARCHIVE_QUEUE_MAX_BYTEST1
int268435456
Schedulers
Environment variable
Tier
Type
Default
CODEX_LB_AUTOMATIONS_SCHEDULER_ENABLEDT3 (dashboard)
boolTrue
Multi-replica
Environment variable
Tier
Type
Default
CODEX_LB_LEADER_ELECTION_ENABLEDT1
boolTrue
CODEX_LB_LEADER_ELECTION_TTL_SECONDST1
int60
Observability
Environment variable
Tier
Type
Default
CODEX_LB_LOG_FORMATT1
'text' \| 'json''text'
CODEX_LB_METRICS_ENABLEDT1
boolFalse
CODEX_LB_METRICS_PORTT1
int9090
CODEX_LB_OTEL_ENABLEDT1
boolFalse
CODEX_LB_OTEL_EXPORTER_ENDPOINTT1
str''
CODEX_LB_TRACET4
str''
Resilience & load shedding
Environment variable
Tier
Type
Default
CODEX_LB_BACKPRESSURE_MAX_CONCURRENT_REQUESTST1
int0
CODEX_LB_BULKHEAD_DASHBOARD_LIMITT1
int50
CODEX_LB_BULKHEAD_PROXY_LIMITT1
int512
CODEX_LB_CIRCUIT_BREAKER_ENABLEDT3 (dashboard)
boolFalse
CODEX_LB_DETERMINISTIC_FAILOVER_ENABLEDT3 (dashboard)
boolTrue
CODEX_LB_MEMORY_REJECT_THRESHOLD_MBT1
int0
CODEX_LB_SHUTDOWN_DRAIN_TIMEOUT_SECONDST1
int30
CODEX_LB_SOFT_DRAIN_ENABLEDT3 (dashboard)
boolTrue
Other
Environment variable
Tier
Type
Default
CODEX_LB_EVENT_LOOP_LAG_WARN_THRESHOLD_SECONDST1
float0.5
CODEX_LB_TELEMETRY_ENABLEDT3 (dashboard)
bool \| NoneNone
CODEX_LB_TELEMETRY_ENDPOINTT1
str'https://telemetry.tokmaxxing.com'
CODEX_LB_THREAD_CACHE_IDENTITY_MODET3 (dashboard)
str'shared'
CODEX_LB_TIMEOUT_INVARIANT_VALIDATION_STRICTT4
boolFalse
Removed
Images and default account probes choose gpt-5.6-luna, then gpt-5.5,
using registry plan visibility and suppression. If neither qualifies, they
use gpt-5.6-luna. Catalog visibility does not guarantee account access.
There is no host-model setting. See the
Images spec
and probe spec .
Removed settings (ignored with a one-release startup warning; each is now a
fixed default or a dashboard runtime setting — see PRINCIPLES.md P2 /
issue #1340 ):
CODEX_LB_REQUEST_LOG_RETENTION_DAYSCODEX_LB_USAGE_HISTORY_RETENTION_DAYSCODEX_LB_HTTP_DOWNSTREAM_TRANSPORT_POLICYCODEX_LB_OPENAI_CACHE_AFFINITY_MAX_AGE_SECONDSCODEX_LB_WARMUP_MODELCODEX_LB_HTTP_RESPONSES_SESSION_BRIDGE_GATEWAY_SAFE_MODECODEX_LB_UPSTREAM_STREAM_TRANSPORTCODEX_LB_UPSTREAM_COMPACT_TIMEOUT_SECONDSCODEX_LB_MAX_SSE_EVENT_BYTESCODEX_LB_UPSTREAM_RESPONSE_CREATE_MAX_BYTESCODEX_LB_OAUTH_TIMEOUT_SECONDSCODEX_LB_TOKEN_REFRESH_TIMEOUT_SECONDSCODEX_LB_TOKEN_REFRESH_CLAIM_TTL_SECONDSCODEX_LB_PROXY_REFRESH_FAILURE_COOLDOWN_SECONDSCODEX_LB_PROXY_ADMISSION_WAIT_TIMEOUT_SECONDSCODEX_LB_USAGE_FETCH_TIMEOUT_SECONDSCODEX_LB_USAGE_FETCH_MAX_RETRIESCODEX_LB_USAGE_REFRESH_ENABLEDCODEX_LB_USAGE_REFRESH_INTERVAL_SECONDSCODEX_LB_USAGE_REFRESH_AUTH_FAILURE_COOLDOWN_SECONDSCODEX_LB_LIVE_USAGE_INGESTION_ENABLEDCODEX_LB_RATE_LIMIT_RESET_CREDITS_REFRESH_INTERVAL_SECONDSCODEX_LB_STICKY_SESSION_CLEANUP_ENABLEDCODEX_LB_QUOTA_PLANNER_SCHEDULER_ENABLEDCODEX_LB_MODEL_REGISTRY_ENABLEDCODEX_LB_MAX_DECOMPRESSED_BODY_BYTESCODEX_LB_MAX_DECOMPRESSED_RESPONSES_BODY_BYTESCODEX_LB_IMAGE_INLINE_FETCH_ENABLEDCODEX_LB_IMAGE_INLINE_ALLOWED_HOSTSCODEX_LB_IMAGES_DEFAULT_MODELCODEX_LB_OPENAI_PROMPT_CACHE_KEY_DERIVATION_ENABLEDCODEX_LB_PROXY_TOKEN_REFRESH_LIMITCODEX_LB_PROXY_UPSTREAM_WEBSOCKET_CONNECT_LIMITCODEX_LB_PROXY_COMPACT_RESPONSE_CREATE_LIMITCODEX_LB_HTTP_RESPONSES_SESSION_BRIDGE_IDLE_TTL_SECONDSCODEX_LB_HTTP_RESPONSES_SESSION_BRIDGE_CODEX_IDLE_TTL_SECONDSCODEX_LB_HTTP_RESPONSES_SESSION_BRIDGE_STUCK_GATE_RETIRE_AFTER_SECONDSCODEX_LB_HTTP_RESPONSES_SESSION_BRIDGE_ANCHOR_POISON_FAILURE_THRESHOLDCODEX_LB_HTTP_RESPONSES_SESSION_BRIDGE_SERVER_RECOVERY_MAX_ATTEMPTSCODEX_LB_HTTP_RESPONSES_SESSION_BRIDGE_CLEAN_CLOSE_RETRY_JITTER_MAX_SECONDSCODEX_LB_HTTP_RESPONSES_SESSION_BRIDGE_OPERATION_LEDGER_ENABLEDCODEX_LB_HTTP_RESPONSES_SESSION_BRIDGE_AMBIGUOUS_CONTINUATION_RECOVERY_MODECODEX_LB_TOKEN_REFRESH_INTERVAL_DAYS
Specs: user-documentation · responses-api-compat · rate-limit-reset-credits · deployment-installation · proxy-runtime-observability