Load balancer for ChatGPT accounts. Pool multiple accounts, track usage, manage API keys, view everything in a dashboard.

# Docker (recommended)
docker volume create codex-lb-data
docker run -d --name codex-lb \
 -p 2455:2455 -p 1455:1455 \
 -v codex-lb-data:/var/lib/codex-lb \
 ghcr.io/soju06/codex-lb:latest
# or uvx
uvx codex-lb

Open localhost:2455 → Add account → Done.

When accessing the dashboard remotely for the first time, a bootstrap token is required to set the initial password.

Auto-generated (default): On first startup (no password configured), the server generates a one-time token and prints it to logs:

docker logs codex-lb
# ============================================
# Dashboard bootstrap token (first-run):
# <token>
# ============================================

Open the dashboard → enter the token + new password → done. The token is shared across replicas and remains valid until a password is set. In multi-replica setups, replicas must share the same encryption key (the Helm chart default) for restart recovery to work.

Manual token: To use a fixed token instead, set the env var before starting:

docker run -d --name codex-lb \
 -e CODEX_LB_DASHBOARD_BOOTSTRAP_TOKEN=your-secret-token \
 -p 2455:2455 -p 1455:1455 \
 -v codex-lb-data:/var/lib/codex-lb \
 ghcr.io/soju06/codex-lb:latest

Local access (localhost) bypasses bootstrap entirely — no token needed.

Point any OpenAI-compatible client at codex-lb. If API key auth is enabled, pass a key from the dashboard as a Bearer token.

Model availability is discovered from the upstream Codex model catalog and can vary by account plan, workspace, rollout, and upstream deprecation state. Prefer the live GET /v1/models or GET /backend-api/codex/models response over a copied static table when configuring clients or API-key model allowlists.

model = "gpt-5.3-codex"
model_reasoning_effort = "xhigh"
model_provider = "codex-lb"
[model_providers.codex-lb]
name = "openai" # required — enables remote /responses/compact. Lowercase since Codex 2026年05月23日; older "OpenAI" stops resolving gpt-5.5
base_url = "http://127.0.0.1:2455/backend-api/codex"
wire_api = "responses"
supports_websockets = true
requires_openai_auth = true # required for codex app

export CODEX_LB_UPSTREAM_STREAM_TRANSPORT=websocket

[features]
responses_websockets = true
# or
responses_websockets_v2 = true

[model_providers.codex-lb]
name = "openai"
base_url = "http://127.0.0.1:2455/backend-api/codex"
wire_api = "responses"
env_key = "CODEX_LB_API_KEY"
supports_websockets = true
requires_openai_auth = true # required for codex app

export CODEX_LB_API_KEY="sk-clb-..." # key from dashboard
codex

RUST_LOG=debug codex exec "Reply with OK only."

# Preview what will change first.
codex-lb codex-sessions retag --from openai --to codex-lb --dry-run
# Then close Codex/Codex CLI and apply the retag.
codex-lb codex-sessions retag --from openai --to codex-lb --yes

{
 "$schema": "https://opencode.ai/config.json",
 "provider": {
 "openai": {
 "options": {
 "baseURL": "http://127.0.0.1:2455/v1",
 "apiKey": "{env:CODEX_LB_API_KEY}"
 },
 "models": {
 "gpt-5.4": {
 "name": "GPT-5.4",
 "reasoning": true,
 "options": { "reasoningEffort": "high", "reasoningSummary": "detailed" },
 "limit": { "context": 1050000, "output": 128000 }
 },
 "gpt-5.3-codex": {
 "name": "GPT-5.3 Codex",
 "reasoning": true,
 "options": { "reasoningEffort": "high", "reasoningSummary": "detailed" },
 "limit": { "context": 272000, "output": 65536 }
 },
 "gpt-5.1-codex-mini": {
 "name": "GPT-5.1 Codex Mini",
 "reasoning": true,
 "options": { "reasoningEffort": "high", "reasoningSummary": "detailed" },
 "limit": { "context": 272000, "output": 65536 }
 },
 "gpt-5.3-codex-spark": {
 "name": "GPT-5.3 Codex Spark",
 "reasoning": true,
 "options": { "reasoningEffort": "xhigh", "reasoningSummary": "detailed" },
 "limit": { "context": 128000, "output": 65536 }
 }
 }
 }
 },
 "model": "openai/gpt-5.3-codex"
}

export CODEX_LB_API_KEY="sk-clb-..." # key from dashboard
opencode

{
 "agents": {
 "defaults": {
 "model": { "primary": "codex-lb/gpt-5.4" },
 "models": {
 "codex-lb/gpt-5.4": { "params": { "cacheRetention": "short" } }
 "codex-lb/gpt-5.4-mini": { "params": { "cacheRetention": "short" } }
 "codex-lb/gpt-5.3-codex": { "params": { "cacheRetention": "short" } }
 }
 }
 },
 "models": {
 "mode": "merge",
 "providers": {
 "codex-lb": {
 "baseUrl": "http://127.0.0.1:2455/v1",
 "apiKey": "${CODEX_LB_API_KEY}", // or "dummy" if API key auth is disabled
 "api": "openai-responses",
 "models": [
 {
 "id": "gpt-5.4",
 "name": "gpt-5.4 (codex-lb)",
 "contextWindow": 1050000,
 "contextTokens": 272000,
 "maxTokens": 4096,
 "input": ["text"],
 "reasoning": false
 },
 {
 "id": "gpt-5.4-mini",
 "name": "gpt-5.4-mini (codex-lb)",
 "contextWindow": 400000,
 "contextTokens": 272000,
 "maxTokens": 4096,
 "input": ["text"],
 "reasoning": false
 },
 {
 "id": "gpt-5.3-codex",
 "name": "gpt-5.3-codex (codex-lb)",
 "contextWindow": 400000,
 "contextTokens": 272000,
 "maxTokens": 4096,
 "input": ["text"],
 "reasoning": false
 }
 ]
 }
 }
 }
}

from openai import OpenAI
client = OpenAI(
 base_url="http://127.0.0.1:2455/v1",
 api_key="sk-clb-...", # from dashboard, or any non-empty string if auth is disabled
)
response = client.chat.completions.create(
 model="gpt-5.3-codex",
 messages=[{"role": "user", "content": "Hello!"}],
)
print(response.choices[0].message.content)

API key auth is disabled by default. In that mode, only local requests to the protected proxy routes can proceed without a key; non-local requests are rejected until proxy authentication is configured. Enable it in Settings → API Key Auth on the dashboard when clients connect remotely or through Docker, VM, or container networking that appears non-local to the service.

When enabled, clients must pass a valid API key as a Bearer token:

Authorization: Bearer sk-clb-...

The protected proxy routes covered by this setting are:

• /v1/* (except /v1/usage, which always requires a valid key)
• /backend-api/codex/*
• /backend-api/transcribe

Creating keys: Dashboard → API Keys → Create. The full key is shown only once at creation. Keys support optional expiration, model restrictions, and rate limits (tokens / cost per day / week / month).

Environment variables with CODEX_LB_ prefix or .env.local. See .env.example. SQLite is the default database backend; PostgreSQL is optional via CODEX_LB_DATABASE_URL (for example postgresql+asyncpg://...).

The Docker Compose postgres profile uses the Postgres 18 image and mounts the named data volume at /var/lib/postgresql, the parent of the image's versioned PGDATA directory.

Existing Postgres 16 compose volumes must be upgraded before the Postgres 18 container starts:

docker compose --profile postgres stop postgres
docker run --rm -v codex-lb-postgres-data:/var/lib/postgresql -v "$PWD:/backup" alpine \
 tar -C /var/lib/postgresql -czf /backup/codex-lb-postgres-data-before-pg18.tgz .
docker compose --profile postgres-upgrade run --rm postgres-upgrade
docker compose --profile postgres up -d postgres

The postgres-upgrade profile runs pg_upgrade in one-shot mode against the same named volume and exits after the data directory has been upgraded to the Postgres 18 layout. Because that helper mounts and rewrites the operator's database volume, Compose pins the helper image by digest; refresh and review the digest deliberately when changing the helper image tag. Keep the backup until the application has started and codex-lb-db check succeeds against the upgraded database.

The normal postgres service refuses to start when it detects the old root-level PG_VERSION file from a pre-18 Compose volume. If that guard fires, run the postgres-upgrade profile above before starting Postgres again. It also refuses nested /var/lib/postgresql/data directories that still report a pre-18 major version, because those layouts need an explicit pg_upgrade before the Postgres 18 container can safely open them.

codex-lb supports three dashboard auth modes via environment variables:

• CODEX_LB_DASHBOARD_AUTH_MODE=standard — built-in dashboard password with optional TOTP from the Settings page.
• CODEX_LB_DASHBOARD_AUTH_MODE=trusted_header — trust a reverse-proxy auth header such as Authelia's Remote-User, but only from CODEX_LB_FIREWALL_TRUSTED_PROXY_CIDRS. Built-in password/TOTP remain available as an optional fallback, and password/TOTP management still requires a fallback password session.
• CODEX_LB_DASHBOARD_AUTH_MODE=disabled — fully bypass dashboard auth. Use only behind network restrictions or external auth. Built-in password/TOTP management is disabled in this mode.

trusted_header mode also requires:

CODEX_LB_FIREWALL_TRUST_PROXY_HEADERS=true
CODEX_LB_FIREWALL_TRUSTED_PROXY_CIDRS=172.18.0.0/16
CODEX_LB_DASHBOARD_AUTH_PROXY_HEADER=Remote-User

If the trusted header is missing and no fallback password is configured, the dashboard fails closed and shows a reverse-proxy-required message instead of loading the UI.

Authelia / trusted header

docker run -d --name codex-lb \
 -p 2455:2455 -p 1455:1455 \
 -e CODEX_LB_DASHBOARD_AUTH_MODE=trusted_header \
 -e CODEX_LB_DASHBOARD_AUTH_PROXY_HEADER=Remote-User \
 -e CODEX_LB_FIREWALL_TRUST_PROXY_HEADERS=true \
 -e CODEX_LB_FIREWALL_TRUSTED_PROXY_CIDRS=172.18.0.0/16 \
 -v codex-lb-data:/var/lib/codex-lb \
 ghcr.io/soju06/codex-lb:latest

Hard override / no app-level dashboard auth

docker run -d --name codex-lb \
 -p 2455:2455 -p 1455:1455 \
 -e CODEX_LB_DASHBOARD_AUTH_MODE=disabled \
 -v codex-lb-data:/var/lib/codex-lb \
 ghcr.io/soju06/codex-lb:latest

For Helm, pass the same values through extraEnv.

Backup this directory to preserve your data.

• Usage and quota - why does codex-lb still say rate_limited when Codex Desktop says reset?

helm install codex-lb oci://ghcr.io/soju06/charts/codex-lb \
 --set postgresql.auth.password=changeme \
 --set config.databaseMigrateOnStartup=true \
 --set migration.schemaGate.enabled=false
kubectl port-forward svc/codex-lb 2455:2455

Open localhost:2455 → Add account → Done.

The Helm chart auto-configures HTTP /responses owner handoff for multi-replica installs using a headless-service DNS name per pod. The default cluster domain is cluster.local; set Helm clusterDomain if your cluster uses a different suffix. Override config.sessionBridgeAdvertiseBaseUrl only if pods must be reached through a different internal address.

For external database, production config, ingress, observability, and more see the Helm chart README.

Fast Mode and service-tier behavior is documented in Responses API compatibility context.

# Docker
docker compose watch
# Local
uv sync && cd frontend && bun install && cd ..
uv run fastapi run app/main.py --reload # backend :2455
cd frontend && bun run dev # frontend :5173

Thanks goes to these wonderful people (emoji key):

This project follows the all-contributors specification. Contributions of any kind welcome!