codex-lb: a load balancer for pooled ChatGPT accounts

What codex-lb pools, and who ends up running it

The README describes codex-lb as a "Load balancer for ChatGPT accounts" that lets you "Pool multiple accounts, track usage, manage API keys, view everything in a dashboard." The problem it targets is account-level rate limiting. If a single ChatGPT account throttles you mid-session, an OpenAI-compatible client pointed at that account stops working. codex-lb sits between the client and upstream, spreads requests across the accounts you have added, and records what each one consumed.

The audience is narrower than the feature list suggests. You need more than one ChatGPT account, and you need a client that speaks the OpenAI wire format. The README lists Codex CLI and IDE extensions, OpenCode, OpenClaw, Hermes Agent, and the OpenAI Python SDK, each with its own endpoint and guide. A developer running one account gains nothing from the proxy layer; the pooling is the whole point.

There is a second audience the README does not frame as primary: people who want the usage numbers. The dashboard reports per-account tokens, cost, and 28-day trends. That is a reporting feature that happens to ship inside a routing tool, and it is the part that makes the data directory worth backing up.

How routing, keys and usage tracking fit together

The runtime is a FastAPI application. The repository layout shows a Python backend under app/, a frontend/ directory built with Bun, and a Rust workspace under crates/ with members named codex-lb-egress, codex-lb-egress-worker, codex-lb-protocol and codex-lb-responses. The Dockerfile builds that Rust egress worker in a separate stage and copies the resulting binary into the Python runtime image, so the outbound HTTP path is native code rather than the Python HTTP stack. The README does not explain what the egress worker does differently; the crate names are the only signal, and they suggest connection handling for the responses API and websocket support.

State lives in a database. SQLite is the default backend, and PostgreSQL is optional through CODEX_LB_DATABASE_URL. Migrations are handled by Alembic, which appears in the dependency list alongside SQLAlchemy and aiosqlite. Accounts are added through the dashboard, which means the account credentials and the usage records sit in the same store.

Access control has two layers. Dashboard authentication is password-based with optional TOTP, and proxy routes are protected by API keys created from the dashboard. The README notes that remote clients need an API key, so the key layer is not optional once you leave localhost. Per-key limits can be set by token count, cost, window, and model according to the feature table.

Models are not hardcoded. The README lists auto model sync, with available models fetched from upstream. That matters because the client config example pins a model name, and a pinned name that upstream no longer serves is the kind of failure that looks like a codex-lb bug.

Installing codex-lb and pointing Codex CLI at it

The README marks Docker as the recommended path. It creates a named volume and a network first, then runs the container with two published ports: 2455 for the service and 1455 for the OAuth callback.

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

After that, the README says to open localhost:2455, add an account, and you are done. If you reach the dashboard remotely for the first time, you need a one-time bootstrap token, which the getting started page documents.

There are two alternatives to Docker. uvx codex-lb runs it from a Python environment, and nix run github:Soju06/codex-lb runs it from the flake. The storage path differs by install method: local and uvx use ~/.codex-lb/, while Docker uses /var/lib/codex-lb/.

For Codex CLI, the README gives a config block for ~/.codex/config.toml. Note the comment about the provider name, which must be lowercase.

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

Other clients use a different base URL. OpenCode, OpenClaw and Hermes Agent point at http://127.0.0.1:2455/v1, and the OpenAI Python SDK uses the same /v1 prefix. Getting the prefix wrong is the most likely first-run failure, because the Codex CLI path is /backend-api/codex and everything else is /v1.

The single-writer limit and other ways it breaks

The docker-compose.yml opens with a warning that is worth reading before any deployment planning. It states that the file defines a single-replica topology, that docker compose up --scale server=N should not be used, and that the SQLite default supports only one writer while the published host ports collide. Multi-replica deployments require the Helm chart with PostgreSQL and leader election, which lives under deploy/helm/codex-lb.

That is a real ceiling, not a footnote. Anyone who assumes a load balancer is horizontally scalable will be wrong about this one. The load balancing happens upstream of the accounts, not across codex-lb instances.

A second failure mode is client configuration drift. The README's own TOML comment warns that the provider name must be lowercase and that the older capitalized form stops resolving a specific model. Configuration that worked against an earlier Codex release can stop resolving model names without any change to codex-lb itself. The auto model sync feature does not help here, because the problem is in the client's provider block.

A third case where codex-lb is the wrong tool: a single account. The proxy adds a hop, a database, a dashboard password, and API key management. With one account there is nothing to balance, and the usage dashboard is the only remaining benefit. Even then, the same token and cost numbers are visible in the upstream account tooling.

Finally, note the classifier in pyproject.toml: Development Status :: 3 - Alpha. The recent releases are all v1.25.0 beta builds. The version string in pyproject.toml is 1.25.0-beta.9, matching the newest release. Treat upgrade churn as expected.

codex-lb against a plain reverse proxy

The obvious alternative is nginx or Caddy in front of a single upstream, with account switching done by hand. The difference is where the decision lives. A reverse proxy routes by hostname, path, or a static upstream list; it has no concept of an account pool, no per-account quota state, and no way to react when one account is throttled. You would edit the config and reload whenever you wanted to switch accounts.

codex-lb moves that decision into the application. Accounts are rows in a database, added through the dashboard, and the routing strategy decides which one serves a request. The README links a routing guide that describes strategies, so the selection logic is configurable rather than fixed. The trade-off is that you now run a stateful service with migrations, a dashboard login, and a data directory to back up, where nginx is a stateless config file.

A second alternative is the per-client account switcher pattern: keep several credential profiles in the client and switch manually. That avoids running anything, and it fails the moment you want two clients sharing the same pool, or want to know how much each account consumed over the last 28 days. The usage tracking is the feature a switcher cannot replicate.

One search phrase people use is codex lb for claude. Nothing in the README or the repository metadata mentions Anthropic or Claude, so codex-lb should be read as a ChatGPT and Codex tool only.

Maintenance, upgrades and what the MIT licence covers

The repository is not archived, and the last push was on 2026-09-14. Releases have been frequent and close together: v1.25.0-beta.9 on 2026-09-14, v1.25.0-beta.8 on 2026-09-12, and v1.25.0-beta.7 on 2026-09-10. A three-release cadence inside a week tells you the project moves quickly, and it also tells you that pinning a version is a reasonable default for a service that holds account credentials.

Upgrade cost has three parts. The Python package version, which the Docker image tag follows; the database schema, which Alembic migrations handle and which is the reason to back up the data directory before pulling a new image; and the Rust egress worker, which is compiled into the image and therefore only changes when you change the image. The README's development section shows docker compose watch for the container path, and uv sync plus a Bun install for local work, with the backend on port 2455 and the frontend dev server on 5173.

Licensing is MIT, declared both in the README metadata and in the Cargo workspace. MIT permits commercial use, modification, and redistribution provided the copyright notice and permission notice are preserved. That is a permissive baseline, and it does not tell you anything about the terms attached to the ChatGPT accounts you pool or to the upstream API you proxy to. Those are separate agreements between you and the account provider, and nothing in the codex-lb licence changes them. This is a description of the licence text, not legal advice; if the pooling arrangement has contractual implications for your organization, that question goes to whoever handles those agreements.

Editorial conclusion

Adopt codex-lb if you have several ChatGPT accounts and one or more OpenAI-compatible clients that need a single base URL, and you are comfortable running a single-replica service with a backup of the data directory. Do not adopt it if you need horizontal scale-out, because the Compose file states the SQLite default supports one writer and multi-replica deployments require the Helm chart with PostgreSQL and leader election. Before pointing anything at it, check the routing documentation for the strategy you want, confirm the bootstrap token path for remote dashboard access, and decide whether CODEX_LB_DATABASE_URL should stay on SQLite.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. Soju06/codex-lb on GitHub