codex-lb 1.0.0

Codex load balancer and proxy for ChatGPT accounts with usage dashboard

codex-lb

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

More screenshots

Settings	Login

Dashboard (dark)	Accounts (dark)	Settings (dark)

Features

Account Pooling Load balance across multiple ChatGPT accounts	Usage Tracking Per-account tokens, cost, 28-day trends	API Keys Per-key rate limits by token, cost, window, model
Dashboard Auth Password + optional TOTP	OpenAI-compatible Codex CLI, OpenCode, any OpenAI client	Auto Model Sync Available models fetched from upstream

Quick Start

# 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.

Client Setup

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

Logo	Client	Endpoint	Config
	Codex CLI	http://127.0.0.1:2455/backend-api/codex	~/.codex/config.toml
	OpenCode	http://127.0.0.1:2455/v1	~/.config/opencode/opencode.json
	OpenClaw	http://127.0.0.1:2455/v1	~/.openclaw/openclaw.json
	OpenAI Python SDK	http://127.0.0.1:2455/v1	Code

 Codex CLI / IDE Extension

~/.codex/config.toml:

model = "gpt-5.3-codex"
model_reasoning_effort = "xhigh"
model_provider = "codex-lb"

[model_providers.codex-lb]
name = "OpenAI"  # MUST be "OpenAI" - enables /compact endpoint
base_url = "http://127.0.0.1:2455/backend-api/codex"
wire_api = "responses"
requires_openai_auth = true

With API key auth:

model = "gpt-5.3-codex"
model_reasoning_effort = "xhigh"
model_provider = "codex-lb"

[model_providers.codex-lb]
name = "OpenAI"  # MUST be "OpenAI" - enables /compact endpoint
base_url = "http://127.0.0.1:2455/backend-api/codex"
wire_api = "responses"
env_key = "CODEX_LB_API_KEY"

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

 OpenCode

~/.config/opencode/opencode.json:

{
  "provider": {
    "openai": {
      "options": { "baseURL": "http://127.0.0.1:2455/v1" }
    }
  }
}

With API key auth:

{
  "provider": {
    "codex-lb": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "codex-lb",
      "options": {
        "baseURL": "http://127.0.0.1:2455/v1",
        "apiKey": "{env:CODEX_LB_API_KEY}"   // reads from env var
      },
      "models": {
        "gpt-5.3-codex": { "name": "GPT-5.3 Codex" }
      }
    }
  },
  "model": "codex-lb/gpt-5.3-codex"
}

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

 OpenClaw

~/.openclaw/openclaw.json:

{
  "agents": {
    "defaults": {
      "model": { "primary": "codex-lb/gpt-5.3-codex" }
    }
  },
  "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-completions",
        "models": [
          { "id": "gpt-5.3-codex", "name": "GPT-5.3 Codex" },
          { "id": "gpt-5.3-codex-spark", "name": "GPT-5.3 Codex Spark" }
        ]
      }
    }
  }
}

Set the env var or replace ${CODEX_LB_API_KEY} with a key from the dashboard. If API key auth is disabled, any value works.

 OpenAI Python SDK

from openai import OpenAI

client = OpenAI(
    base_url="http://127.0.0.1:2455/v1",
    api_key="sk-clb-...",  # from dashboard, or any 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 Authentication

API key auth is disabled by default — the proxy is open to any client. Enable it in Settings → API Key Auth on the dashboard.

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

Authorization: Bearer sk-clb-...

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).

Configuration

Environment variables with CODEX_LB_ prefix or .env.local. See .env.example. Dashboard auth is configured in Settings.

Data

Environment	Path
Local / uvx	~/.codex-lb/
Docker	/var/lib/codex-lb/

Backup this directory to preserve your data.

Development

# 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

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Soju06 💻 ⚠️ 🚧 🚇

Jonas Kamsker 💻 🐛 🚧

Quack 💻 🐛 🚧 🎨

Jill Kok, San Mou 💻 ⚠️ 🚧

PARK CHANYOUNG 📖

Choi138 💻 🐛 ⚠️

LYA⚚CAP⚚OCEAN 💻 ⚠️

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