Quick Start

Use this guide to get from a fresh checkout to a local Pool API key you can put in a Codex or OpenAI-compatible client.

What You Need

Docker with Compose
openssl
A browser for the owner setup and admin UI
At least one Codex account credential to import when you create your first upstream

1. Start Codex Pooler

Clone the repository, generate local secrets, and start the app with Postgres.

git clone https://github.com/icoretech/codex-pooler.git
cd codex-pooler

scripts/self-host/generate-env.sh
docker compose pull
docker compose up -d

Open http://localhost:4000. The first page should take you to owner setup.

If the page does not load, check the containers and app logs:

docker compose ps
docker compose logs -f app

2. Create The Owner Account

Create the first account from the bootstrap screen. This account is the instance owner, so store the password somewhere safe.

After setup, sign in and keep these admin pages open as your first-run checklist:

Use separate operator accounts later for day-to-day work. Keep the bootstrap owner for instance-wide administration.

3. Create A Pool

Open Pools and create your first Pool.

A Pool is the capacity boundary your clients use. API keys attach to a Pool, and Codex Pooler chooses an eligible upstream account inside that Pool for each request.

For a local trial, one Pool is enough. Use a plain name such as local-dev or default.

4. Add An Upstream Account

Open Upstreams and import or connect a Codex account.

Treat imported Codex account material as owned by Codex Pooler after import. Do not keep the same credential active in other automation unless you accept that provider refresh-token rotation can force one copy to reauthenticate.

After import, assign the upstream to the Pool you created. The upstream should show as usable before you expect client requests to route successfully.

5. Create A Pool API Key

Open API keys and create a key for your Pool.

Copy the raw key immediately. Codex Pooler shows it only once. Store it in the client environment variable you plan to use, for example:

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

The Pool API key represents the Pool, not one upstream account. Do not use this key for /mcp; operator MCP tokens are separate.

6. Point Your First Client At The Gateway

For Codex backend clients, use the backend compatibility route:

Base URL: http://localhost:4000/backend-api/codex
Authorization: Bearer <pool-api-key>

For OpenAI-compatible SDK clients, use the narrow /v1 route:

Base URL: http://localhost:4000/v1
Authorization: Bearer <pool-api-key>

For trusted operator metadata tools, use /mcp with an operator MCP token, not a Pool API key:

MCP URL: http://localhost:4000/mcp
Authorization: Bearer <operator-mcp-token>

For deployed instances, replace http://localhost:4000 with your HTTPS host, for example https://pooler.example.com.

If Something Is Stuck

Use these checks only when the page or client path is not behaving as expected.

docker compose ps
docker compose logs -f app
curl -fsS http://localhost:4000/healthz
curl -fsS http://localhost:4000/readyz

If the app is running but client requests fail, check the Pool assignment first: the Pool needs an active API key, at least one usable upstream assignment, and a model the upstream account can serve.

To stop the local stack:

docker compose down

To remove the local database too:

docker compose down -v

Safety Notes

Give Pool API keys only to trusted clients. Keep MCP tokens separate from runtime credentials. Do not paste prompts, tokens, cookies, account secrets, or imported account material into support requests.