I wrote this README by hand, no LLM :)
Balancing usage across several ChatGPT Codex accounts.
go install github.com/supabitapp/codex-balancer@latestcodex-balancer server # serve the proxy with a TUI at
The server runs at http://127.0.0.1:8317
/v1/responses— HTTPPOST(SSE or JSON) and WebSocketGET/codex/responsesand/v1/codex/responses— equivalent HTTPPOSTand WebSocketGETaliases for pi/v1/alpha/search,/v1/images/generationsand/v1/images/edits— unaryPOSTproxies for Codex's standalone web search and image tools, sent with a pool account's credentials/v1/audio/transcriptions— OpenAI-compatible dictationPOST(multipart/form-datawithfileand optionallanguage, returns{"text": …}), transcribed by ChatGPT with a pool account; see ROUTING.md/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.
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 normalPaused 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-laptopkeys list includes the input, cached, output, and total tokens attributed to
each key.
State lives in ~/.codex-balancer/state.db.
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.
Merge these settings into ~/.codex/config.toml, keeping existing table entries:
model_provider = "balancer"
[features]
standalone_web_search = true
[model_providers.balancer]
name = "OpenAI"
base_url = "http://127.0.0.1:8317/v1"
model_catalog_url = "http://127.0.0.1:8317/v1/models"
env_key = "CODEX_BALANCER_API_KEY"
requires_openai_auth = true
supports_websockets = true
supports_standalone_web_search = trueThese keys are defined in Codex 0.161.0's configuration schema.
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"
}
}
}OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4318 codex-balancer server -no-tui -json -otelSee 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 logic is in ROUTING.md.