codex-pooler

Codex Pooler is a self-hosted gateway for running Codex-compatible agents, tools, and automation through stable Pool API keys. It works with one upstream Codex account for credential isolation, client normalization, metadata-only operations, and saved reset visibility; add more accounts when you want shared capacity and routing across eligible accounts.

Clients send familiar Codex backend or OpenAI-compatible requests; Codex Pooler selects an eligible account based on model support, quota evidence, limits, session continuity, routing policy, and health. The Pool key stays stable while upstream assignments, lifecycle state, reset policy, and capacity change behind it.

Operators get one place to manage Pools, accounts, API keys, saved resets, routing, request accounting, audit logs, and health without storing prompts, files, audio, images, bearer tokens, or raw Codex secrets. Instance owners keep the global administration surface, while instance admins work only with their assigned Pools.

Highlights

• 🧩 Use the tools you already know: connect Codex, OpenCode and other supported coding agents, plus apps built with OpenAI-compatible SDKs
• 🔑 One key for your apps: connect tools with a Pool API key that stays the same when you add or replace Codex accounts, without sharing account credentials
• ⚡ High cache reuse across protocols: over 95% cached input observed on HTTP/SSE and WebSockets, backed by cache-aware routing and connection reuse
• 🎯 Automatic account selection: send requests to accounts that can serve the chosen model, with available quota and account health taken into account
• 📏 Control how much each key can use: set request limits and daily or weekly AI usage allowances
• 🚀 Give agents more room to work: let them use several tools at once in Full mode, with Lite compatibility when needed
• 🖼️ Images and voice, too: generate and edit images or transcribe audio through supported apps, using the same Pool API key
• 🛡️ Keep conversation content private: track usage and troubleshoot requests without saving prompts, replies, uploaded files, images or audio
• 🔁 Keep conversations together: keep supported sessions linked to the right account when a client reconnects
• 🔭 Let users track their own usage: enable a personal Observatory dashboard for each key, showing activity, response times and estimated costs
• 🏦 Put saved resets to use: see available reset credits and use them to restore account quota, manually or automatically when enabled
• 🖥️ Manage everything in one place: add accounts, manage keys and invites, check usage and change settings from a browser
• 👥 Organize teams and projects: group accounts into Pools with their own access rules and model choices
• 🤝 Connect accounts by invitation: let account owners join a Pool through a guided browser flow, without sending you credential files
• 🚨 Know when attention is needed: receive alerts about low capacity, account problems and reset events in the dashboard, by email or through webhooks
• 🔎 Spot model downgrades: see when the provider reports a different model from the one sent, or changes the model name during a response
• 🧷 Fill in missing continuity: derive stable session identities from cache keys or conversation IDs when a harness does not send them directly
• 🧱 Choose who can connect: optionally allow requests only from approved networks
• 🐳 Run it on your own infrastructure: start with Docker Compose or deploy on Kubernetes as your needs grow

Harness Configuration

Start with a running Codex Pooler instance, a Pool API key, and an installed client. The examples include gpt-6-luna, gpt-6.1-sol and gpt-6-astra, with Sol selected by default. Keep the models available to your Pool. Replace <pool-api-key> with your key and run the command for your terminal before starting the client.

macOS / Linux / Windows WSL (bash or zsh)

export CODEX_POOLER_API_KEY="<pool-api-key>"

Windows PowerShell

$env:CODEX_POOLER_API_KEY = "<pool-api-key>"

These commands set the key for the current terminal. For desktop apps, follow the linked guide to save the key for the app.

The paths below are defaults. On macOS/Linux, ~ is your home folder. On Windows, paste paths starting with %USERPROFILE%, %APPDATA% or %LOCALAPPDATA% into File Explorer's address bar. If you installed a client inside WSL, use its Linux paths and commands inside WSL. Custom configuration folders or profiles take precedence over these defaults.

For a local instance:

For a deployed instance, replace http://localhost:4000 with your instance's host, such as https://codex-pooler.example.com. Merge snippets into existing configurations. The examples use the large 828,400-token context for GPT-6. Codex CLI and Desktop read the available context size automatically from your Pool.

Each entry covers the basic connection. Its full setup & extras link covers installation, advanced options and troubleshooting. Operator MCP is optional and uses a separate token; see Operator MCP Service.