English | 简体中文
Load balancer for ChatGPT accounts. Pool multiple accounts, track usage, manage API keys, view everything in a dashboard.
Fork Docker guide: Docker · Upstream documentation — client setup, configuration, troubleshooting, and screenshots.
Note
🛡️ Hardened Community Edition (by @Frozen811)
This production-ready fork includes 100% verified in-code fixes for all 164 tracked issues and community PRs:
- Fixes HTTP/2 Native Egress cascade stream drops and stream-cap exhaustion (#2471, #2470)
- Delivers terminal error frames on injected anchor rejection (#2493)
- Integrates Replay Relocation engine and account-neutral transcript rebuilding (PR #2428)
- Removes unsupported
max_output_tokensfrom Force Probe to prevent upstream HTTP 400 errors (PR #2496) - Adds dashboard single & bulk API key usage reset (#2492)
- Supports MySQL / MariaDB databases alongside PostgreSQL & SQLite with dialect abstraction and facet indexes (#2502, #2522, #2532)
- Enables bounded inline image streaming and upstream transport label recording (#2508, #2534, #2503)
- Fully bumped and verified frontend and Python dependency stacks (PR #2509, PR #2533)
Release notes: COMMUNITY_RELEASE.md | Release: v1.25.0-hardened.3 | How to update: Update Guide
Option 1: Historical public Docker image (linux/amd64, source f622c563; newer fixes require a source build)
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/frozen811/codex-lb@sha256:ad9aa84b12bce9f6afc63adb3aa86e73f6aafca1814e6f20b486b00f21c60447Option 2: Historical release wheel with uvx or pip (identity and source-build guide)
# Run via uvx:
uvx --from https://github.com/Frozen811/codex-lb/releases/download/v1.25.0-hardened.3/codex_lb-1.25.1-py3-none-any.whl codex-lb
# Or install pre-built wheel directly:
pip install https://github.com/Frozen811/codex-lb/releases/download/v1.25.0-hardened.3/codex_lb-1.25.1-py3-none-any.whl
codex-lbOption 3: Local Clone with 1-Click Launchers
git clone https://github.com/Frozen811/codex-lb.git
cd codex-lb
# Windows: double-click start.bat or run:
.\run.ps1
# Linux / macOS:
./run.sh| Feature / Defect Area | Upstream (Soju06/codex-lb) |
Hardened Edition (Frozen811/codex-lb) |
|---|---|---|
| HTTP/2 Stream Cascade Failure (#2471, #2470) | ❌ Network drop drops all concurrent streams | ✅ Per-stream isolation; clean aclose() |
| Account Stream Cap Lease Leak | ❌ Leaks concurrency lease on disconnect | ✅ Guaranteed release in finally blocks |
Upstream 400 on max_output_tokens (PR #2496) |
❌ Force probe fails with HTTP 400 | ✅ Unsupported field omitted; returns 200 |
| Warmup Compaction 404 Fallback (#1895) | ❌ Upstream 404 halts quota initialization | ✅ Transparent plain Responses API fallback |
| Dashboard API Key Limit Usage Reset (#2492) | ❌ Missing; requires key regeneration | ✅ Single & bulk usage counter reset |
| Dead Client Continuation Anchor (#2493) | ❌ Client hangs without terminal frame | ✅ Clean terminal response.failed event |
| Replay Relocation Engine (PR #2428) | ❌ Unmerged open PR | ✅ Fully integrated & regression-tested |
| Log Credential Redaction (#2028) | ❌ Unhandled loop errors leak credentials | ✅ Sanitized with _RedactedRepr |
| Pre-built Docker Image | Separate upstream artifact | Historical fork image; see Docker provenance |
| OpenSpec Validation | ✅ 67/67 Specifications strictly validated |
| 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 |
 |
 |
|---|
# Docker (run from a fork checkout; see the Docker guide)
docker build -t codex-lb:local .
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 \
codex-lb:local
# or the historical fork wheel (see the Python guide for current source)
uvx --from https://github.com/Frozen811/codex-lb/releases/download/v1.25.0-hardened.3/codex_lb-1.25.1-py3-none-any.whl 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.
Point any OpenAI-compatible client at codex-lb. For Codex CLI, ~/.codex/config.toml:
model = "gpt-6-astra"
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
supports_standalone_web_search = true # requires codex-lb >= 1.22.0
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.
Environment variables with CODEX_LB_ prefix or .env.local — see .env.example and the
configuration guide. SQLite is the default database backend;
PostgreSQL and MySQL are optional via CODEX_LB_DATABASE_URL.
| Environment | Path |
|---|---|
| Local / uvx | ~/.codex-lb/ |
| Docker | /var/lib/codex-lb/ |
Backup this directory to preserve your data.
Full docs live at https://soju06.github.io/codex-lb/:
- 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 / MySQL, Postgres 16 → 18 upgrade
- Deployment — Docker, Kubernetes, remote access
- Troubleshooting
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)
# 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 environmentThanks goes to these wonderful people (emoji key):
This project follows the all-contributors specification. Contributions of any kind welcome!