Codex Pooler: A self-hosted gateway that turns one Codex account into a team-scale pool

What Codex Pooler actually solves

Codex Pooler solves a credential and routing problem that appears once more than one person or agent talks to a Codex backend. Instead of handing out raw Codex account tokens, an operator creates a Pool and issues a stable Pool API key. Clients point at that key, and the gateway decides which upstream account should serve each request. The README is explicit that the Pool key stays stable while upstream assignments, lifecycle state, reset policy, and capacity change behind it. That matters for teams where accounts get added, removed, or hit quota limits mid-day. The intended audience is operators who manage multiple accounts and want a single control plane for pools, keys, saved resets, routing, and request accounting. It is also aimed at agent harnesses that speak the Codex backend protocol or the OpenAI-compatible /v1 surface.

Routing on eligibility, not just load

The routing mechanism is more specific than a round-robin load balancer. According to the README, Codex Pooler selects an eligible account based on model support, quota evidence, limits, session continuity, routing policy, and health. That means a request for a model that only one account supports will not land on an account that cannot serve it. Quota evidence is used to avoid sending requests to an account that is out of capacity. Session continuity matters for resumable Codex sessions: the gateway keeps websocket reconnects attached to the same upstream account. The README also describes a transient prompt_cache_key that prefers the same eligible account for repeat stateless requests, which improves provider-side cache locality without storing prompts locally. This is a deliberate design choice: the gateway does not cache prompts, it only tries to keep repeat requests on the same upstream so the provider's own cache can hit.

Two client surfaces: Codex backend and OpenAI-compatible

Codex Pooler exposes two ways for clients to connect. One is the native Codex backend protocol, which preserves responses, compacting, usage, files, audio, images, and backend websocket flows. The other is an OpenAI-compatible /v1 surface, which lets tools that only speak OpenAI REST use Codex capacity. The README lists a long set of clients with dedicated documentation pages: OpenCode, Codex CLI, OpenClaw, Hermes, Pi, OMP, Kilo, Trae, Aider, Continue, Cline, Goose, Windmill, OpenHands, and generic OpenAI-compatible SDKs. The OpenAI-compatible route is described as translated and routed to help contain API spend, which suggests the gateway is doing request translation, not just proxying. This dual surface is the core of the project: one pool boundary, many client protocols.

Getting it running: Docker Compose and Helm

The README points to a quick start with Docker Compose and a Helm chart for Kubernetes. The Compose path is the fastest way to get a local instance. The Helm chart separates web, worker, scheduler, and migration roles, which is meant for multinode growth. The project runs on Elixir/Erlang's runtime, so the deployment artifact is a BEAM VM, not a single binary. Configuration is done through the admin UI, not code changes, for pool policy, gateway defaults, diagnostics, model support, limits, and operational settings. For harness configuration, the README advises keeping Pool API keys in environment variables when the harness supports secret expansion. There is also an optional /mcp endpoint for operator-only metadata inspection, which runtime clients do not need. The README warns that if a desktop harness persists remote MCP headers in its own private settings, you should use a different approach, though the truncated text cuts off the exact recommendation.

Privacy and observability without storing content

A recurring theme in the README is that Codex Pooler stores metadata, not content. It stores request, routing, and audit metadata without storing prompts, file bodies, audio, images, bearer tokens, cookies, raw Codex account tokens, or raw API keys. That is a meaningful privacy boundary for teams that want to know who called what model and how much it cost, without retaining the actual conversation. The per-key Observatory is a read-only dashboard for any Pool API key holder, showing only that key's usage, models, latency, cache, and spend. It has no operator controls and cannot see other keys. The operator dashboard covers pools, accounts, API keys, invites, saved resets, usage, request logs, audit logs, MCP access, and owner-only jobs and settings. This split between operator and per-key views is a practical way to give agents or individual developers visibility into their own spend without exposing the whole fleet.

Saved resets and alerting: operational features that go beyond a proxy

Codex Pooler includes two features that are rare in a simple gateway. Saved reset management surfaces reported saved reset capacity on upstream accounts, shows informational expirations when available, and lets operators queue account-level recovery or opt into a guarded auto-redemption policy. This is about handling the Codex saved reset system, which can be opaque to end users. The other feature is operator alerting: rules for capacity, upstream health, saved reset events, and delivery failures, with notifications through admin incidents, email, or webhooks. The README stresses that alerts do not expose raw request content. These features suggest the project is aimed at operators who treat Codex accounts as a finite resource to be monitored and recovered, not just a connection to proxy.

A real limitation: the license is unverified

The repository license is marked NOASSERTION, which means the project does not declare a standard open source license. That is a genuine adoption blocker for many teams. You can run it under a personal evaluation, but you cannot legally redistribute or build a product on it without clarifying the terms with the maintainers. The README does not address licensing at all. This is the first thing to verify before any deeper technical evaluation. The second limitation is operational complexity. Running an Elixir service with a database, scheduler, and worker roles is heavier than a single-purpose proxy. If you only need to share one account with two people, Codex Pooler is overkill. The README also notes that the runtime ingress firewall is optional, which means the default deployment may be more permissive than a security-conscious team wants.

Alternatives and the difference in approach

The obvious alternative is running multiple Codex CLI instances directly against upstream accounts, or using a plain reverse proxy like nginx to forward requests to a single account. The difference is that a reverse proxy has no concept of eligibility, quota, session continuity, or saved resets. It can only forward traffic. Another alternative is a commercial API gateway that supports OpenAI-compatible endpoints, but those do not understand the Codex backend protocol or the saved reset lifecycle. Codex Pooler's approach is to be Codex-aware: it models accounts as resources with quota evidence and health, and it keeps websocket sessions pinned to the correct upstream. That is the core difference. If you only need HTTP forwarding, you do not need this project. If you need routing based on Codex-specific state, you do.

Maintenance and upgrade cost

The release cadence is active. The latest release, v0.6.12, was pushed on 2026-08-28, and v0.6.11 and v0.6.10 came the day before and two days before that. That is a rapid iteration pace, which means bug fixes and features land quickly, but it also means you should expect frequent upgrades. The project uses a versioned release scheme with tags like codex-pooler-v0.6.12. Upgrading likely involves pulling a new Docker image or Helm chart version and running migrations, since the architecture separates web, worker, scheduler, and migration roles. The README does not provide a migration guide, so you will need to check the docs site for each release. The cost of maintenance is not trivial: you are running a stateful service with a database, not a stateless proxy. Operators should budget time for monitoring the gateway itself, not just the upstream accounts.

Editorial conclusion

Adopt Codex Pooler if you run a team or fleet of Codex-compatible agents and need one stable credential, quota-aware routing, and an audit trail that never stores prompts or raw tokens. Skip it if you only need a single-user proxy or cannot commit to operating an Elixir service with its own database and scheduler. Before deploying, verify the license terms, since the repository declares NOASSERTION, and confirm that the documented Docker Compose or Helm paths match your network and ingress firewall needs.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes