codex-lb 0.6.0

Codex load balancer and proxy for ChatGPT accounts with usage dashboard

codex-lb

Load balancer for ChatGPT accounts. Pool multiple accounts, track usage, view everything in a dashboard.

Screenshots

Main Dashboard View

Accounts View

Quick Start

Docker

docker run -d --name codex-lb \
  -p 2455:2455 -p 1455:1455 \
  -v ~/.codex-lb:/var/lib/codex-lb \
  ghcr.io/soju06/codex-lb:latest

If you expect high traffic (60+ requests/min), prefer a Docker volume for the data directory to reduce SQLite I/O errors on some hosts.

docker volume create codex-lb-data
docker run -d --name codex-lb \
  -p 2455:2455 -p 1455:1455 \
  -v codex-lb-data:/var/lib/codex-lb \
  ghcr.io/soju06/codex-lb:latest

uvx

uvx codex-lb

Open localhost:2455 → Add account → Done.

Codex CLI & Extension Setup

Add to ~/.codex/config.toml:

model = "gpt-5.2-codex"
model_reasoning_effort = "xhigh"
model_provider = "codex-lb"

[model_providers.codex-lb]
name = "OpenAI"  # MUST be "OpenAI" - enables /compact endpoint
base_url = "http://127.0.0.1:2455/backend-api/codex"
wire_api = "responses"
chatgpt_base_url = "http://127.0.0.1:2455"
requires_openai_auth = true  # Required: enables model selection in Codex IDE extension

OpenCode Setup

Run:

opencode auth login

Then select OpenAI -> Manually enter API Key and enter any value.

Add the following to ~/.config/opencode/opencode.json:

{
  ...
  "provider": {
    "openai": {
      "options": {
        "baseURL": "http://127.0.0.1:2455/v1"
      }
    },
    ...
  }
}

Configuration

All settings use the CODEX_LB_ prefix and can be set via environment variables or .env.local.

Dashboard TOTP

Protect the dashboard with TOTP two-factor authentication.

1. Set CODEX_LB_DASHBOARD_SETUP_TOKEN to any secret string:

CODEX_LB_DASHBOARD_SETUP_TOKEN=my-secret-token

2. Open the dashboard and go to Settings to enable TOTP.
3. Scan the QR code with your authenticator app and confirm.

Once enabled, the dashboard requires a TOTP code on every login. TOTP can be disabled from Settings while logged in.

Data

Data storage locations:

• Local/uvx: ~/.codex-lb/
• Docker: /var/lib/codex-lb/

Files:

• store.db – accounts, usage logs
• encryption.key – encrypts tokens (auto-generated)

Backup this directory to preserve your accounts.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Soju06 💻 ⚠️ 🚧 🚇

Jonas Kamsker 💻 🐛 🚧

Quack 💻 🐛 🚧 🎨

Jill Kok, San Mou 💻 ⚠️ 🚧

PARK CHANYOUNG 📖

Choi138 💻 🐛 ⚠️

LYA⚚CAP⚚OCEAN 💻 ⚠️

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