# 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/)):

Soju06 💻 ⚠️ 🚧 🚇	Jonas Kamsker 💻 🐛 🚧	Quack 💻 🐛 🚧 🎨	Jill Kok, San Mou 💻 ⚠️ 🚧 🐛	PARK CHANYOUNG 📖 💻 ⚠️	Choi138 💻 🐛 ⚠️	LYA⚚CAP⚚OCEAN 💻 ⚠️
Eugene Korekin 💻 🐛 ⚠️	jordan 💻 🐛 ⚠️	DOCaCola 🐛 ⚠️ 📖	JoeBlack2k 💻 🐛 ⚠️	Peter A. 📖 💻 🐛	Hannah Markfort 💻 ⚠️	mws-weekend-projects 💻 ⚠️
Quang Do 💻 ⚠️	Anand Aiyer 🐛 💻 ⚠️	defin85 💻 🐛 ⚠️	Jacky Fong 💻 🐛 💬 🚧 ⚠️	flokosti96 💻 ⚠️	Woonggi Min 💻 ⚠️	Yigit Konur 🐛 💻
Ruben 💻 ⚠️ 🐛	Steve Santacroce 💻 ⚠️ 🐛	Hugh Do 💻 ⚠️	Hubert Salwin 💻 ⚠️	Teemu Koskinen 📖	Yu Peng Zheng 📖 💻	embogomolov 💻 ⚠️
Renat Sharipov 💻 ⚠️	Liu Rui 📖 💻 ⚠️ 🐛	OverHash 💻 ⚠️	Kazet 💻 ⚠️	Bala Kumar 💻 ⚠️ 🤔	ihazgithub 💻 ⚠️	Temirkhan 💻 ⚠️ 📖 🐛
tobwen 💻 ⚠️ 🐛	Rio 💻 🐛 ⚠️	Mika 💻 📖 ⚠️	Darafei Praliaskouski 💻 📖 ⚠️ 🐛	Maxim Feofilov 💻 ⚠️	klaascommerce 💻 ⚠️	JeffKandt ⚠️ 👀
ozpool 🤔 📖 💻 ⚠️	Manu ⚠️ 👀	Wojtek Majewski ⚠️	Andrew Noble 💻 ⚠️	Josu Gorostegui 💻 ⚠️	Linus Mixson 💻 ⚠️	timefox 💻 ⚠️
Lotfree 💻 ⚠️ 📖 🐛	hikki 💻 🎨	Miha Orazem 💻 ⚠️	Nikhil 💻 ⚠️	onlysdesign-ui 💻 ⚠️	Steven (Minh) Dang 📖	Nataprom 💻 ⚠️
Iweisc 💻 ⚠️	Mahir Taha Özdin 🤔 💻 ⚠️	ram/haidar 💻	Rudra Tiwari 💻	Wu Chao 💻	zwd0313 💻	mastertyko 💻 ⚠️
Diógenes Castro 💻 ⚠️	jhordanjw123 💻 ⚠️	abarsegov 💻	Akshay Kakatkar 💻 ⚠️	NeoClaw 💻	plastictaste 💻 ⚠️ 📖	softkleenex 💻 ⚠️
n3crosis 💻 ⚠️	geoHeil 💻 ⚠️	copilot 💻	mercenarioZ 💻 ⚠️	Rubén Pérez Bachiller 💻 ⚠️ 🐛	Guanwei Chen 💻 ⚠️	Jonáš Sivek 💻 ⚠️
落叶 💻 📖 ⚠️ 🌍	jawwadfirdousi 💻 ⚠️	Quang Do 💻 ⚠️	zvladru 💻 ⚠️	Hwanmoo Yong 💻 ⚠️	Abdullah Alzeiby 💻 ⚠️	anime girl 💻 ⚠️
evaldass 💻 ⚠️	Claude 💻	luawl 💻 ⚠️	Shawn 💻	Hafiy 💻 ⚠️ 📖	Choong Jun Jin 💻 ⚠️	knightcn1983 💻 ⚠️
Kevin van Zonneveld 💻	Roman Leventov 💻	AliReza Tofighi 📖	DOMANHDUC 💻	Kwan Perry 💻	James 💻 ⚠️	SSY 💻 ⚠️ 📖
Fatih Özbek 💻 ⚠️	Kushida 💻 ⚠️	Aidid Haiqal 💻 ⚠️	yshishenya 💻	alchemistkiv 💻 ⚠️	mhooooo 💻 ⚠️	crowscc 💻
Syakur Rahman 💻 ⚠️	cigro-manager 💻	Paul Eipper 💻 ⚠️ 📖	ret2basic.eth 💻 ⚠️	유영준 💻 ⚠️	mrnaturalmonopoly-prog 💻 ⚠️	mrunnaturalmonopoly-svg 💻 ⚠️
HulianBuligon 💻 ⚠️	joschi655 💻 ⚠️	daydreamer.jin 💻 ⚠️ 📖	rknightion 💻 ⚠️	glopyglerky 💻 ⚠️	Ahmad Maulana Iqbal 💻 ⚠️	Dvredin 💻
DuyBui 💻 ⚠️	Kevin Lin 💻 ⚠️	Borealin 💻 ⚠️	Nikita Maximilian Grimm 💻 📖 ⚠️	BrenticusMaximus 💻 ⚠️	Sakthimaran 💻 ⚠️	Evan 💻
Chao Xu 💻 ⚠️	zenasharp 💻 ⚠️ 📖	HanSu Lee 💻 ⚠️	Derek Pearson 💻	JustYannicc 💻 ⚠️ 📖	ygx 💻 ⚠️	Aarav 💻
Evan Haug 💻 ⚠️	Jason HONG 💻	Mohammad Saleh Mahdinejad 💻 ⚠️ 🐛 📖	Muhammad Ilham Dedi 💻 🐛 ⚠️	Victor Statko 📖	flameboy 📖	elmakus 💻 ⚠️ 🐛
Abaddollyon 💻 ⚠️	Markus Jakl 💻 ⚠️ 🐛

This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!