Environment Variables

Complete reference of all Codex-LB environment variables

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