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        # backend :2455
cd frontend && bun run dev                     # frontend :5173

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Soju06 💻 ⚠️ 🚧 🚇	Hwanmoo Yong 💻 ⚠️	Jonas Kamsker 💻 🐛 🚧	Quack 💻 🐛 🚧 🎨	Jill Kok, San Mou 💻 ⚠️ 🚧 🐛	PARK CHANYOUNG 📖 💻 ⚠️	Choi138 💻 🐛 ⚠️
LYA⚚CAP⚚OCEAN 💻 ⚠️	Diógenes Castro 💻 ⚠️	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 💻 ⚠️
JeffKandt ⚠️ 👀	klaascommerce 💻 ⚠️	ozpool 🤔 📖 💻 ⚠️	Manu ⚠️ 👀	Wojtek Majewski ⚠️	Andrew Noble 💻 ⚠️	Josu Gorostegui 💻 ⚠️
Linus Mixson 💻 ⚠️	Lotfree 💻 ⚠️ 📖 🐛	timefox 💻 ⚠️	Nikhil 💻 ⚠️	Miha Orazem 💻 ⚠️	Steven (Minh) Dang 📖	onlysdesign-ui 💻 ⚠️
Mahir Taha Özdin 🤔 💻 ⚠️	hikki 💻 🎨	Nataprom 💻 ⚠️	Iweisc 💻 ⚠️	ram/haidar 💻	Rudra Tiwari 💻	Wu Chao 💻
zwd0313 💻	jhordanjw123 💻 ⚠️	mastertyko 💻 ⚠️	NeoClaw 💻	abarsegov 💻	Akshay Kakatkar 💻 ⚠️	softkleenex 💻 ⚠️
mercenarioZ 💻 ⚠️	plastictaste 💻 ⚠️ 📖	落叶 💻 📖 ⚠️ 🌍	n3crosis 💻 ⚠️	copilot 💻	geoHeil 💻 ⚠️	Jonáš Sivek 💻 ⚠️
Rubén Pérez Bachiller 💻 ⚠️ 🐛	Guanwei Chen 💻 ⚠️	jawwadfirdousi 💻 ⚠️	Quang Do 💻 ⚠️	Abdullah Alzeiby 💻 ⚠️	zvladru 💻 ⚠️	anime girl 💻 ⚠️
evaldass 💻 ⚠️	Claude 💻	Shawn 💻	luawl 💻 ⚠️	knightcn1983 💻 ⚠️	Hafiy 💻 ⚠️ 📖	Kevin van Zonneveld 💻
Choong Jun Jin 💻 ⚠️	Roman Leventov 💻	AliReza Tofighi 📖	DOMANHDUC 💻	Kwan Perry 💻	James 💻 ⚠️

This project follows the all-contributors specification. Contributions of any kind welcome!