# 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.

:::note[Work in Progress]
No published release exists yet. Expect setup details and docs to change before the first release.
:::

## 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.

```bash
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](http://localhost:4000). The first page should take you to owner setup.

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

```bash
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:

- [Pools](http://localhost:4000/admin/pools)
- [Upstreams](http://localhost:4000/admin/upstreams)
- [API keys](http://localhost:4000/admin/api-keys)

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

## 3. Create A Pool

Open [Pools](http://localhost:4000/admin/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](http://localhost:4000/admin/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](http://localhost:4000/admin/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:

```bash
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:

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

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

```text
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:

```text
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.

```bash
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:

```bash
docker compose down
```

To remove the local database too:

```bash
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.