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

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
supports_standalone_web_search = true # requires codex-lb >= 1.22.0
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
• Codex-LB Rates — Home Assistant integration for pool and per-account quota remaining sensors (5h / weekly / monthly)

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!