This release is a pre-release and may not be stable for production use.
codex-lb
English | 简体中文
Load balancer for ChatGPT accounts. Pool multiple accounts, track usage, manage API keys, view everything in a dashboard.
Documentation: https://soju06.github.io/codex-lb/ — 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 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, 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 environment
Contributors ✨
Thanks goes to these wonderful people (emoji key):
This project follows the all-contributors specification. Contributions of any kind welcome!
1 maintainer
Metadata
1 maintainer
Release files for codex-lb 1.25.0b9
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| codex_lb-1.25.0b9.tar.gz | 19.4 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| codex_lb-1.25.0b9-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 22.5 MB
Release files / codex_lb-1.25.0b9.tar.gz
| Download URL | codex_lb-1.25.0b9.tar.gz |
|---|---|
| Size | 19.4 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
bf690c012c9266608945a652df70da7d6cb53b25350a492627816eb0c77d67bb
|
|
BLAKE2b-256 checksum How to use checksums |
40c9eb18e669a8637e3bdab90f7ecb17194997675adc9efe6228e649613fab22
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 14, 2026.
Transparency logRelease files / codex_lb-1.25.0b9-py3-none-any.whl
| Download URL | codex_lb-1.25.0b9-py3-none-any.whl |
|---|---|
| Size | 3.1 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b475bfda98bfc663ddbc465a83a60eb28cc0dda223e877eafb5b649ed6331e43
|
|
BLAKE2b-256 checksum How to use checksums |
d036db7350dd177db65d7159fea1385e20e414c9bdaf090efccecad8177c1e3b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 14, 2026.
Transparency log
