codex-lb
English | 简体中文
Load balancer for ChatGPT accounts. Pool multiple accounts, track usage, manage API keys, view everything in a dashboard.
**Documentation: ** — getting started, client setup, configuration, deployment, troubleshooting, and more screenshots.
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 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-lb
Open 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 |
|---|---|---|---|
| Codex CLI / IDE | http://127.0.0.1:2455/backend-api/codex |
Client setup → Codex CLI | |
| OpenCode | http://127.0.0.1:2455/v1 |
Client setup → OpenCode | |
| OpenClaw | http://127.0.0.1:2455/v1 |
Client setup → OpenClaw | |
| Hermes Agent | 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
- Codex-LB Rates — Home Assistant integration for pool and per-account quota remaining sensors (5h / weekly / monthly)
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 environment
Contributors ✨
Thanks goes to these wonderful people (emoji key):
Darafei Praliaskouski
💻 📖 ⚠️ 🐛
Nikita Maximilian Grimm
💻 📖 ⚠️
Mohammad Saleh Mahdinejad
💻 ⚠️ 🐛 📖
This project follows the all-contributors specification. Contributions of any kind welcome!