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
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
Development
# Docker
docker compose watch
# Local
uv sync && cd frontend && bun install && cd ..
uv run fastapi run app/main.py --reload --no-proxy-headers # backend :2455
cd frontend && bun run dev # frontend :5173
Contributors ✨
Thanks goes to these wonderful people (emoji key):
This project follows the all-contributors specification. Contributions of any kind welcome!
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file codex_lb-1.22.0.tar.gz.
File metadata
- Download URL: codex_lb-1.22.0.tar.gz
- Upload date:
- Size: 8.3 MB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.1.0 CPython/3.13.13
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
4de6fac5819434f3871da0227d5098154637d2f9fbe2d1af9c5e66b30c199e37
|
|
| MD5 |
7fe478ac90c9d63ad030f1e627b8133b
|
|
| BLAKE2b-256 |
080e647d9a921f29dbbedb57ee9de994c81d1fdc74a096538524e0850557d85b
|
Provenance
The following attestation bundles were made for codex_lb-1.22.0.tar.gz:
Publisher:
release.yml on Soju06/codex-lb
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
codex_lb-1.22.0.tar.gz -
Subject digest:
4de6fac5819434f3871da0227d5098154637d2f9fbe2d1af9c5e66b30c199e37 - Sigstore transparency entry: 2231571130
- Sigstore integration time:
-
Permalink:
Soju06/codex-lb@4c0dbc9ceb2b5d70204ea7603cf1b4bef83db234 -
Branch / Tag:
refs/tags/v1.22.0 - Owner: https://github.com/Soju06
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@4c0dbc9ceb2b5d70204ea7603cf1b4bef83db234 -
Trigger Event:
release
-
Statement type:
File details
Details for the file codex_lb-1.22.0-py3-none-any.whl.
File metadata
- Download URL: codex_lb-1.22.0-py3-none-any.whl
- Upload date:
- Size: 2.0 MB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.1.0 CPython/3.13.13
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
476b1bf4716bd80fe3f8588b9d3f901259d9c3300a276874784e0846af7cd4b9
|
|
| MD5 |
2f7170d4f397cf37feb76811cf70d9a9
|
|
| BLAKE2b-256 |
d393f1b70213c3c56b7d8af2a12f6eb17ba5fdc73aa9bed17e19a975cfd885c1
|
Provenance
The following attestation bundles were made for codex_lb-1.22.0-py3-none-any.whl:
Publisher:
release.yml on Soju06/codex-lb
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
codex_lb-1.22.0-py3-none-any.whl -
Subject digest:
476b1bf4716bd80fe3f8588b9d3f901259d9c3300a276874784e0846af7cd4b9 - Sigstore transparency entry: 2231571781
- Sigstore integration time:
-
Permalink:
Soju06/codex-lb@4c0dbc9ceb2b5d70204ea7603cf1b4bef83db234 -
Branch / Tag:
refs/tags/v1.22.0 - Owner: https://github.com/Soju06
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@4c0dbc9ceb2b5d70204ea7603cf1b4bef83db234 -
Trigger Event:
release
-
Statement type:
