codex-lb
English | 简体中文
Load balancer for ChatGPT accounts. Pool multiple accounts, track usage, manage API keys, view everything in a dashboard.
Documentation:
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 |
| !dashboard | !accounts | |:---:|:---:|
Quick Start
# Docker (recommended)
docker volume create codex-lb-data
docker network inspect codex-lb-net >/dev/null 2>&1 || docker network create codex-lb-net
docker run -d --name codex-lb \
--network codex-lb-net \
-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
or nix
nix run github:Soju06/codex-lbOpen localhost:2455 → Add account → Done.
Accessing the dashboard remotely for the first time? You need a one-time bootstrap token — see Getting started.
Client Setup
Point any OpenAI-compatible client at codex-lb. For Codex CLI, ~/.codex/config.toml:
model = "gpt-5.6-sol"
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
| Logo | Client | Endpoint | Guide |
|---|--------|----------|-------|
| 
http://127.0.0.1:2455/backend-api/codex | Client setup → Codex CLI |
| 
http://127.0.0.1:2455/v1 | Client setup → OpenCode |
| 
http://127.0.0.1:2455/v1 | Client setup → OpenClaw |
| 
http://127.0.0.1:2455/v1 | Client setup → Hermes Agent |
| 
| OpenAI Python SDK | http://127.0.0.1:2455/v1 | Client setup → Python SDK |
Remote clients need an API key created from the dashboard.
Configuration
Environment variables with CODEX_LB_ prefix or .env.local — see .env.example and the
configuration guide. SQLite is the default database backend;
PostgreSQL is optional via CODEX_LB_DATABASE_URL.
Data
| Environment | Path |
|-------------|------|
| Local / uvx | ~/.codex-lb/ |
| Docker | /var/lib/codex-lb/ |
Backup this directory to preserve your data.
Documentation
Full docs live at
- Getting started — quick start, remote bootstrap token
- Client setup — Codex CLI, OpenCode, OpenClaw, Python SDK
- Configuration — the few settings that matter
- Authentication — dashboard auth modes
- API keys — protecting proxy routes
- Routing — strategy guide
- Database — SQLite / PostgreSQL, Postgres 16 → 18 upgrade
- Deployment — Docker, Kubernetes, remote access
- Troubleshooting
Community companions
Independent projects that consume the dashboard API, maintained outside codex-lb (see the docs listing for access guidance):
- Codex LB Status Bar — native macOS app: account status, quota details, account controls
- codex-lb SwiftBar — read-only SwiftBar/Bun monitor for pool status and quota headroom
- Codex LB Status — read-only Ubuntu tray monitor for pooled quota, account health, reset credits, and update state
- Codex LB for Omarchy — read-only Linux/Omarchy Quattro bar plugin for account quotas, usage totals, reset times, and optional desktop alerts
Development
# Docker
docker compose watch
Local
uv sync && cd frontend && bun install && cd ..
uv run codex-lb # backend :2455
cd frontend && bun run dev # frontend :5173
Nix
nix run .
nix develop # enter dev environmentContributors ✨
Thanks goes to these wonderful people (emoji key):
