Skip to main content
Codex-LB is configured using environment variables with the CODEX_LB_ prefix. You can set these in your shell, a .env file, or a .env.local file in the project root.

​
Configuration Files

Codex-LB reads environment variables from:
  1. System environment variables
  2. .env file (tracked in git, shared defaults)
  3. .env.local file (gitignored, local overrides)
The .env.local file takes precedence over .env, which takes precedence over system defaults.
For Docker deployments, use the -e flag or --env-file option to pass environment variables to the container.

​
Database Configuration

​
CODEX_LB_DATABASE_URL
string
default:"sqlite+aiosqlite:///~/.codex-lb/store.db"
Database connection URL. Supports SQLite and PostgreSQL.SQLite (default):
CODEX_LB_DATABASE_URL=sqlite+aiosqlite:///~/.codex-lb/store.db
PostgreSQL:
CODEX_LB_DATABASE_URL=postgresql+asyncpg://user:pass@localhost:5432/codex_lb
See Database Configuration for detailed setup.
​
CODEX_LB_DATABASE_MIGRATE_ON_STARTUP
boolean
default:"true"
Automatically run database migrations on startup. Recommended for most deployments.
​
CODEX_LB_DATABASE_SQLITE_PRE_MIGRATE_BACKUP_ENABLED
boolean
default:"true"
Create a backup of the SQLite database before running migrations. Only applies to SQLite databases.
​
CODEX_LB_DATABASE_SQLITE_PRE_MIGRATE_BACKUP_MAX_FILES
integer
default:"5"
Maximum number of SQLite backup files to retain. Older backups are automatically deleted.
​
CODEX_LB_DATABASE_POOL_SIZE
integer
default:"15"
Maximum number of database connections in the connection pool. Only applies to PostgreSQL.
​
CODEX_LB_DATABASE_MAX_OVERFLOW
integer
default:"10"
Maximum number of connections that can be created beyond pool_size. Only applies to PostgreSQL.
​
CODEX_LB_DATABASE_POOL_TIMEOUT_SECONDS
float
default:"30.0"
Timeout in seconds when waiting for a database connection from the pool.

​
Upstream Configuration

​
CODEX_LB_UPSTREAM_BASE_URL
string
default:"https://chatgpt.com/backend-api"
Base URL for the upstream ChatGPT backend API. Do not include the /codex suffix.
​
CODEX_LB_UPSTREAM_CONNECT_TIMEOUT_SECONDS
float
default:"30.0"
Connection timeout in seconds for upstream API requests.
​
CODEX_LB_STREAM_IDLE_TIMEOUT_SECONDS
float
default:"300.0"
Maximum idle time in seconds for streaming responses before timing out.

​
OAuth & Token Refresh

​
CODEX_LB_AUTH_BASE_URL
string
default:"https://auth.openai.com"
Base URL for the OpenAI authentication service.
​
CODEX_LB_OAUTH_CLIENT_ID
string
default:"app_EMoamEEZ73f0CkXaXp7hrann"
OAuth client ID for OpenAI authentication. Do not change unless instructed by OpenAI.
​
CODEX_LB_OAUTH_SCOPE
string
default:"openid profile email"
OAuth scopes to request during authorization.
​
CODEX_LB_OAUTH_TIMEOUT_SECONDS
float
default:"30.0"
Timeout in seconds for OAuth authorization and token exchange requests.
​
CODEX_LB_OAUTH_REDIRECT_URI
string
default:"http://localhost:1455/auth/callback"
OAuth redirect URI for the authorization callback. Must match the registered redirect URI.See OAuth Configuration for details on redirect URIs.
​
CODEX_LB_OAUTH_CALLBACK_HOST
string
default:"127.0.0.1"
Host address for the OAuth callback server. Defaults to 0.0.0.0 in Docker containers.
​
CODEX_LB_OAUTH_CALLBACK_PORT
integer
default:"1455"
Port for the OAuth callback server.
Do not change this port. OpenAI has strict requirements for the callback port. Changing it may break authentication.
​
CODEX_LB_TOKEN_REFRESH_TIMEOUT_SECONDS
float
default:"30.0"
Timeout in seconds for token refresh requests.
​
CODEX_LB_TOKEN_REFRESH_INTERVAL_DAYS
integer
default:"8"
Interval in days between automatic token refreshes. Codex-LB automatically refreshes account tokens to keep them valid.

​
Encryption

​
CODEX_LB_ENCRYPTION_KEY_FILE
string
default:"~/.codex-lb/encryption.key"
Path to the encryption key file. This file is used to encrypt sensitive data like access tokens and refresh tokens.Docker deployments: Override this to persist the key in a Docker volume:
CODEX_LB_ENCRYPTION_KEY_FILE=/var/lib/codex-lb/encryption.key
The encryption key file is critical. If lost, encrypted data cannot be recovered. Back up this file securely.

​
Usage Tracking

​
CODEX_LB_USAGE_FETCH_TIMEOUT_SECONDS
float
default:"10.0"
Timeout in seconds for fetching usage data from the upstream API.
​
CODEX_LB_USAGE_FETCH_MAX_RETRIES
integer
default:"2"
Maximum number of retries when fetching usage data fails.
​
CODEX_LB_USAGE_REFRESH_ENABLED
boolean
default:"true"
Enable automatic background refresh of usage data for all accounts.
​
CODEX_LB_USAGE_REFRESH_INTERVAL_SECONDS
integer
default:"60"
Interval in seconds between automatic usage data refreshes.

​
Firewall & IP Access Control

​
CODEX_LB_FIREWALL_TRUST_PROXY_HEADERS
boolean
default:"false"
Trust X-Forwarded-For headers for client IP detection.
Only enable this when Codex-LB is behind a trusted reverse proxy (like nginx or Cloudflare). Enabling this without a trusted proxy allows clients to spoof their IP addresses.
See Firewall Configuration for setup details.
​
CODEX_LB_FIREWALL_TRUSTED_PROXY_CIDRS
string
default:"127.0.0.1/32,::1/128"
Comma-separated list of CIDR ranges for trusted proxy sources. Only requests from these IPs will have their X-Forwarded-For headers trusted.Example (nginx on localhost + Cloudflare):
CODEX_LB_FIREWALL_TRUSTED_PROXY_CIDRS="127.0.0.1/32,::1/128,173.245.48.0/20,103.21.244.0/22"

​
Advanced Settings

​
CODEX_LB_DATABASE_MIGRATIONS_FAIL_FAST
boolean
default:"true"
Terminate the application if database migrations fail. Recommended for production.
​
CODEX_LB_DATABASE_ALEMBIC_AUTO_REMAP_ENABLED
boolean
default:"true"
Automatically remap legacy Alembic revision IDs during migrations.
​
CODEX_LB_LOG_PROXY_REQUEST_SHAPE
boolean
default:"false"
Log the shape of proxy requests for debugging. Not recommended in production.
​
CODEX_LB_LOG_PROXY_REQUEST_SHAPE_RAW_CACHE_KEY
boolean
default:"false"
Log raw cache keys in request shape logs. Only applies if LOG_PROXY_REQUEST_SHAPE is enabled.
​
CODEX_LB_LOG_PROXY_REQUEST_PAYLOAD
boolean
default:"false"
Log full request payloads for debugging. Not recommended in production due to sensitive data.
​
CODEX_LB_MAX_DECOMPRESSED_BODY_BYTES
integer
default:"33554432"
Maximum size in bytes for decompressed request bodies (32 MiB).
​
CODEX_LB_MAX_SSE_EVENT_BYTES
integer
default:"2097152"
Maximum size in bytes for Server-Sent Events (2 MiB).
​
CODEX_LB_IMAGE_INLINE_FETCH_ENABLED
boolean
default:"true"
Enable inline fetching of images in requests.
​
CODEX_LB_IMAGE_INLINE_ALLOWED_HOSTS
string
default:""
Comma-separated list of allowed hosts for inline image fetching. Empty means all hosts are allowed.
​
CODEX_LB_MODEL_REGISTRY_ENABLED
boolean
default:"true"
Enable automatic model registry synchronization from upstream.
​
CODEX_LB_MODEL_REGISTRY_REFRESH_INTERVAL_SECONDS
integer
default:"300"
Interval in seconds between model registry refreshes.
​
CODEX_LB_MODEL_REGISTRY_CLIENT_VERSION
string
default:"0.101.0"
Client version to report to the upstream model registry.

​
Example Configurations

​
Local Development

# .env.local
CODEX_LB_DATABASE_URL=sqlite+aiosqlite:///~/.codex-lb/store.db
CODEX_LB_DATABASE_MIGRATE_ON_STARTUP=true
CODEX_LB_USAGE_REFRESH_ENABLED=true

​
Docker Deployment

# .env
CODEX_LB_DATABASE_URL=sqlite+aiosqlite:///var/lib/codex-lb/store.db
CODEX_LB_ENCRYPTION_KEY_FILE=/var/lib/codex-lb/encryption.key
CODEX_LB_OAUTH_CALLBACK_HOST=0.0.0.0

​
PostgreSQL with Reverse Proxy

# .env.local
CODEX_LB_DATABASE_URL=postgresql+asyncpg://codex:password@db:5432/codex_lb
CODEX_LB_DATABASE_POOL_SIZE=20
CODEX_LB_DATABASE_MAX_OVERFLOW=10
CODEX_LB_FIREWALL_TRUST_PROXY_HEADERS=true
CODEX_LB_FIREWALL_TRUSTED_PROXY_CIDRS=172.18.0.0/16

Build docs developers (and LLMs) love

Get started for freeTalk to us