codex-balancer

README

codex-balancer

I wrote this README by hand, no LLM :)

Balancing usage across several ChatGPT Codex accounts.

Install

go install github.com/supabitapp/codex-balancer@latest

Running the proxy

codex-balancer server           # serve the proxy with a TUI at

The server runs at http://127.0.0.1:8317

• /v1/responses — HTTP POST (SSE or JSON) and WebSocket GET
• /codex/responses and /v1/codex/responses — equivalent HTTP POST and WebSocket GET aliases for pi
• /v1/alpha/search, /v1/images/generations and /v1/images/edits — unary POST proxies for Codex's standalone web search and image tools, sent with a pool account's credentials
• /dashboard — HTML dashboard
• /stats — JSON stats of the server, including the dashboard's estimated monthly API-price value, formatted monthly input and output token totals, and each account's reset countdown and 24-hour traffic share
• /accounts — add an account. On a real server, send this to your friends so they join the pool without exposing credentials.

In the TUI, press r to cycle an account through normal, priority, and paused routing, or space to pause/resume. The admin page's routing selector offers the same modes.

CLI

There is a CLI to manage the accounts

codex-balancer accounts add                 # sign in through a local browser
codex-balancer accounts list
codex-balancer accounts mode you@example.com priority
codex-balancer accounts mode you@example.com paused
codex-balancer accounts mode you@example.com normal

Paused accounts stay in the pool but receive no routed requests. Existing connections restart so clients can reconnect to another account. Choose normal or priority to resume routing; space in the TUI restores the previous preference when resuming. Pauses persist across server restarts.

Routing uses included quota first. When no eligible account with included quota is available, accounts whose weekly quota is exhausted can serve requests using a positive credit balance or unlimited credits. Paused accounts, accounts that need reauthentication, cooldowns, and spend/overage limits are respected. An upstream usage rejection disables that account's credit fallback until its next usage poll. Banked quota resets remain manual.

Adding an account preserves its existing model training setting. Self-serve Business Pro Lite (self_serve_business_prolite) accounts route using their per-account quota. Other Business and Enterprise workspaces are displayed but excluded from routing.

Use the CLI to manage client API keys:

codex-balancer keys add my-laptop
codex-balancer keys list
codex-balancer keys rm my-laptop

keys list includes the input, cached, output, and total tokens attributed to each key.

State lives in ~/.codex-balancer/state.db.

Point Codex at it

On each machine that runs Codex, export a key from the server before starting Codex:

export CODEX_BALANCER_API_KEY="<server-key>"

add that to your ~/.zshrc or whatever env loading mechanism or shell you use.

Then in ~/.codex/config.toml:

model_provider = "balancer"

[model_providers.balancer]
name = "OpenAI" # must be exactly this for server-side compaction to work
base_url = "http://127.0.0.1:8317/v1"
env_key = "CODEX_BALANCER_API_KEY"
requires_openai_auth = true
supports_websockets = true

Point pi at it

export CODEX_BALANCER_API_KEY="<server-key>"

Merge this into ~/.pi/agent/models.json, keeping any unrelated providers:

{
  "providers": {
    "openai-codex": {
      "baseUrl": "http://127.0.0.1:8317/v1",
      "apiKey": "$CODEX_BALANCER_API_KEY"
    }
  }
}

Observability

HTTP Responses has verbose, request-correlated logs. Use server -no-tui -json for JSON logs; clients can report X-Codex-Balancer-Request-Id from response headers. Add -otel to export real traces to a configured OTLP HTTP collector:

OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4318 codex-balancer server -no-tui -json -otel

See OBSERVABILITY.md for trace configuration, privacy/buffering limits, and how to check account-switch boundaries and actual cached-token usage. Tracing is optional and does not change routing or retry behavior.

Routing

Routing logic is in ROUTING.md.