codex-lb: a ChatGPT account pool in front of Codex CLI and OpenCode

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." That sentence is the whole product in one line. If you hold two or more ChatGPT accounts and you drive Codex CLI or an OpenAI-compatible client, you otherwise pick an account by hand and watch quota by hand. codex-lb sits between the client and upstream, keeps the accounts in a pool, and exposes one base URL.

The intended audience is narrow and technical. You are expected to be comfortable with Docker volumes, environment variables with a CODEX_LB_ prefix, and a .env.local file. The feature table names four things that matter to that audience: account pooling, per-account tokens and cost with 28-day trends, API keys with rate limits by token, cost, window and model, and auto model sync where available models are fetched from upstream. The dashboard itself is protected by a password with optional TOTP.

One design choice is worth flagging early. The repository ships a Rust workspace under crates/ (codex-lb-egress, codex-lb-egress-worker, codex-lb-protocol, codex-lb-responses) and the Dockerfile builds a codex-lb-native-egress binary from it before the Python stage. So the network path is not pure Python, even though the project is listed as Python and the top-level service is FastAPI. The README does not explain what that binary does at runtime, which is a gap if you plan to audit traffic.

Routing, endpoints and the two ports codex-lb exposes

The proxy answers on port 2455. The README maps each client to an endpoint path: Codex CLI and the IDE extension use http://127.0.0.1:2455/backend-api/codex, while OpenCode, OpenClaw, Hermes Agent and the OpenAI Python SDK all use http://127.0.0.1:2455/v1. The second published port, 1455, appears in both the docker run example and docker-compose.yml but the README does not say what it serves.

For Codex CLI the configuration is a TOML provider block, and the README attaches two warnings to it. The provider name must be the lowercase openai, because "older \"OpenAI\" stops resolving gpt-5.5" as of Codex 2026-05-23, and that name is what "enables remote /responses/compact". The requires_openai_auth flag is marked "required for codex app".

model = "gpt-5.6-sol"
model_reasoning_effort = "xhigh"
model_provider = "codex-lb"

[model_providers.codex-lb]
name = "openai"
base_url = "http://127.0.0.1:2455/backend-api/codex"
wire_api = "responses"
supports_websockets = true
requires_openai_auth = true

Account selection is where the documentation goes quiet. The README links a routing page described as a "strategy guide" but does not state the default algorithm, nor what happens when every account in the pool is rate limited. Related searches like "codex lb routing strategy" and "codex lb warmup" suggest people ask about exactly this, and the README cannot answer them. Treat routing as something you read up on at soju06.github.io/codex-lb/routing/ before you rely on it.

Installing codex-lb and adding a first account

Three install paths are documented: Docker, which the README calls recommended, uvx, and nix. The Docker path creates a named volume and a network first, so the container has persistent storage at /var/lib/codex-lb.

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

The shorter alternatives are uvx codex-lb and nix run github:Soju06/codex-lb. With uvx the data directory is ~/.codex-lb/ instead of the Docker path, and the README tells you to back that directory up to preserve your data.

Once it is running, open localhost:2455, choose Add account, and the README says you are done. There is one wrinkle: if you are reaching the dashboard remotely for the first time, you need a one-time bootstrap token, which the README defers to the getting started page. Remote clients also need an API key created from the dashboard before they can use the proxy routes.

Configuration is environment variables prefixed with CODEX_LB_ or a .env.local file. SQLite is the default database backend, and PostgreSQL is optional through CODEX_LB_DATABASE_URL. The .env.example file is the reference the README points at, and the configuration guide is the place to look for anything not listed there.

The single-writer limit and other cases where codex-lb is the wrong tool

The most concrete constraint is written directly into docker-compose.yml: "Do not use docker compose up --scale server=N, the SQLite default supports only one writer and the published host ports collide." The same comment states that multi-replica deployments require the Helm chart with PostgreSQL and leader election. That is a real architectural boundary, not a tuning note. If your plan is to run codex-lb as a horizontally scaled shared service behind your own load balancer, the Compose path will not get you there.

There are softer limits too. The pool only helps if you actually have several accounts; with one account, codex-lb adds a process, a database and a dashboard without changing anything about quota. The project is published as v1.25.0-beta.9 and pyproject.toml carries the classifier "Development Status :: 3 - Alpha", so you are adopting pre-1.0 software that has been moving through beta releases every couple of days. The README also does not document rollback, migration between beta versions, or what a database schema change does to an existing SQLite file; alembic is a dependency, so migrations exist, but the README is silent on the upgrade procedure.

Finally, the README does not address whether pooling accounts conflicts with the upstream provider's terms. Searches like "codex-lb ban" show the question is asked. Nothing in the repository answers it, and this article will not guess.

How codex-lb differs from a plain OpenAI-compatible gateway

A generic gateway such as LiteLLM or a self-written FastAPI shim also gives you one base URL in front of many upstreams, so the comparison is fair. The difference is what is being pooled. Those tools generally route between providers and API keys you own, and they assume a standard API key is the credential. codex-lb pools ChatGPT accounts reached through OAuth, which is why the topics list includes oauth and why the pyproject comments discuss ID token verification and the PyJWT versions that fixed crit-header and key-confusion issues. The credential model, not the proxying, is the distinguishing part.

The second difference is the accounting layer. codex-lb ships per-account token and cost tracking with 28-day trends, per-key rate limits by token, cost, window and model, and a model list synced from upstream. A generic gateway typically leaves usage accounting to your observability stack. The repository also lists four independent community companions (a macOS status bar app, a SwiftBar monitor, an Ubuntu tray monitor, and an Omarchy bar plugin) that consume the dashboard API, which is a sign the dashboard API is treated as a stable surface by outside maintainers.

Where a generic gateway wins is deployment shape. Most of them are stateless and scale by adding replicas. codex-lb, as configured in the repository, is a single-writer service with a database and a dashboard, and the Compose file explicitly forbids scaling it that way.

Licence, maintenance and what an upgrade actually costs

codex-lb is MIT licensed, both in the repository LICENSE file referenced by pyproject.toml and in the Cargo workspace manifest, which sets license = "MIT" for the Rust crates. MIT is permissive, so embedding it in a commercial internal deployment is unproblematic in the usual case. Two things to keep in mind without treating this as legal advice: the project bundles or depends on third-party code under its own terms, and the dashboard authentication you configure (password plus optional TOTP) is your responsibility, not something the licence governs.

The last push to the repository was on 2026-09-14, and the most recent release is v1.25.0-beta.9 from the same day, following beta.8 on 2026-09-12 and beta.7 on 2026-09-10. That cadence means the upgrade cost is mostly about frequency rather than difficulty: you are tracking a fast-moving beta line, and the README does not describe a supported upgrade path or a rollback procedure. The Docker image is tagged latest, so a restart can pull a different build than the one you validated.

Operationally, the cheap insurance is the data directory. Back up ~/.codex-lb/ for uvx installs or the codex-lb-data volume for Docker, because that is where the README says your data lives. If you need PostgreSQL, note that the README's database page is titled around a "Postgres 16 to 18 upgrade", so the supported major-version path is documented there rather than in the README.

Editorial conclusion

Adopt codex-lb if you already run several ChatGPT accounts and want one local endpoint on port 2455 that Codex CLI, OpenCode, OpenClaw, Hermes Agent or the OpenAI Python SDK can point at, with per-key limits and a usage dashboard. Do not adopt it if you need more than one replica behind a load balancer: the Compose file states that the SQLite default supports only one writer, and multi-replica deployments require the Helm chart with PostgreSQL and leader election. Skip it as well if you want a stable release, since the published version is 1.25.0-beta.9 and pyproject.toml classifies the project as Development Status 3 - Alpha. Verify first that your clients work against the documented endpoints, /backend-api/codex for Codex CLI and /v1 for the rest, and check the routing page before assuming a particular account-selection strategy.

Frequently asked questions

Official sources

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