Codex/ChatGPT multiple account load balancer & proxy with usage tracking, dashboard, and OpenCode-compatible endpoints
# codex-lb
**English** | [简体中文](./README.zh-CN.md)
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
```bash
# 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](http://localhost:2455) → Add account → Done.
Accessing the dashboard remotely for the first time? You need a one-time bootstrap token —
see [Getting started](https://soju06.github.io/codex-lb/getting-started/).
## Client Setup
Point any OpenAI-compatible client at codex-lb. For Codex CLI, `~/.codex/config.toml`:
```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](https://soju06.github.io/codex-lb/client-setup/#codex-cli-ide-extension) |
| | **OpenCode** | `http://127.0.0.1:2455/v1` | [Client setup → OpenCode](https://soju06.github.io/codex-lb/client-setup/#opencode) |
| | **OpenClaw** | `http://127.0.0.1:2455/v1` | [Client setup → OpenClaw](https://soju06.github.io/codex-lb/client-setup/#openclaw) |
| | **Hermes Agent** | `http://127.0.0.1:2455/v1` | [Client setup → Hermes Agent](https://soju06.github.io/codex-lb/client-setup/#hermes-agent) |
| | **OpenAI Python SDK** | `http://127.0.0.1:2455/v1` | [Client setup → Python SDK](https://soju06.github.io/codex-lb/client-setup/#openai-python-sdk) |
Remote clients need an [API key](https://soju06.github.io/codex-lb/api-keys/) created from the dashboard.
## Configuration
Environment variables with `CODEX_LB_` prefix or `.env.local` — see [`.env.example`](.env.example) and the
[configuration guide](https://soju06.github.io/codex-lb/configuration/). 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](https://soju06.github.io/codex-lb/getting-started/) — quick start, remote bootstrap token
- [Client setup](https://soju06.github.io/codex-lb/client-setup/) — Codex CLI, OpenCode, OpenClaw, Python SDK
- [Configuration](https://soju06.github.io/codex-lb/configuration/) — the few settings that matter
- [Authentication](https://soju06.github.io/codex-lb/authentication/) — dashboard auth modes
- [API keys](https://soju06.github.io/codex-lb/api-keys/) — protecting proxy routes
- [Routing](https://soju06.github.io/codex-lb/routing/) — strategy guide
- [Database](https://soju06.github.io/codex-lb/database/) — SQLite / PostgreSQL, Postgres 16 → 18 upgrade
- [Deployment](https://soju06.github.io/codex-lb/deployment/docker/) — [Docker](https://soju06.github.io/codex-lb/deployment/docker/), [Kubernetes](https://soju06.github.io/codex-lb/deployment/kubernetes/), [remote access](https://soju06.github.io/codex-lb/deployment/remote/)
- [Troubleshooting](https://soju06.github.io/codex-lb/troubleshooting/)
### Community companions
Independent projects that consume the dashboard API, maintained outside codex-lb
(see [the docs listing](https://soju06.github.io/codex-lb/#community-companions)
for access guidance):
- [Codex LB Status Bar](https://github.com/sm1ee/codex-lb-statusbar) — native macOS app: account status, quota details, account controls
- [codex-lb SwiftBar](https://github.com/joschi655/codex-lb-swiftbar) — read-only SwiftBar/Bun monitor for pool status and quota headroom
- [Codex LB Status](https://github.com/VictorStatko/codex-lb-status) — read-only Ubuntu tray monitor for pooled quota, account health, reset credits, and update state
- [Codex LB for Omarchy](https://github.com/janaki-sasidhar/omarchy-codex-lb) — read-only Linux/Omarchy Quattro bar plugin for account quotas, usage totals, reset times, and optional desktop alerts
## Development
```bash
# 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](https://allcontributors.org/en/reference/emoji-key/)):