You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
description: Run Codex Pooler locally, create the first owner, and issue a first Pool API key.
3
+
description: Start Codex Pooler locally, create the first owner, and issue a Pool API key.
4
4
---
5
5
6
-
This quick start runs Codex Pooler locally with Docker Compose and a local Postgres database. It is meant for first evaluation, local smoke checks, and small self-hosted trials.
6
+
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.
7
7
8
8
:::note[Work in Progress]
9
9
No published release exists yet. Expect setup details and docs to change before the first release.
10
10
:::
11
11
12
-
## Prerequisites
12
+
## What You Need
13
13
14
14
- Docker with Compose
15
15
-`openssl`
16
-
- A browser for the owner bootstrap and admin UI
16
+
- A browser for the owner setup and admin UI
17
+
- At least one Codex account credential to import when you create your first upstream
17
18
18
-
## Start The Local Stack
19
+
## 1. Start Codex Pooler
19
20
20
-
Clone the repository, generate local secrets, and start the Compose stack.
21
+
Clone the repository, generate local secrets, and start the app with Postgres.
Use separate operator accounts later for day-to-day work. Keep the bootstrap owner for instance-wide administration.
52
52
53
-
-`http://localhost:4000/admin/pools`
54
-
-`http://localhost:4000/admin/upstreams`
55
-
-`http://localhost:4000/admin/api-keys`
53
+
## 3. Create A Pool
56
54
57
-
The bootstrap account is the instance owner. Keep its credentials private and create separate operator accounts for day-to-day access.
55
+
Open [Pools](http://localhost:4000/admin/pools)and create your first Pool.
58
56
59
-
## Health Checks
57
+
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.
60
58
61
-
Check that the web process answers before creating runtime credentials.
59
+
For a local trial, one Pool is enough. Use a plain name such as `local-dev` or `default`.
62
60
63
-
```bash
64
-
curl -fsS http://localhost:4000/healthz
65
-
curl -fsS http://localhost:4000/readyz
66
-
```
61
+
## 4. Add An Upstream Account
67
62
68
-
Both checks should return a successful response. If they don't, inspect the app logs with `docker compose logs -f app`.
63
+
Open [Upstreams](http://localhost:4000/admin/upstreams) and import or connect a Codex account.
69
64
70
-
## Create Your First Pool And API Key
65
+
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.
71
66
72
-
1. Create a Pool in `/admin/pools`.
73
-
2. Add or import an upstream account in `/admin/upstreams`.
74
-
3. Create a Pool API key in `/admin/api-keys`.
75
-
4. Copy the raw key once and store it in your client or secret manager.
67
+
After import, assign the upstream to the Pool you created. The upstream should show as usable before you expect client requests to route successfully.
76
68
77
-
The Pool API key represents the Pool, not a single upstream account. Codex Pooler can then choose an eligible upstream for each request.
69
+
## 5. Create A Pool API Key
78
70
79
-
Treat imported Codex account material as owned by Codex Pooler after import. Don't keep the same account credential active in other automation unless you accept that provider refresh-token rotation can force one copy to reauthenticate.
71
+
Open [API keys](http://localhost:4000/admin/api-keys) and create a key for your Pool.
80
72
81
-
## Point A Client At The Local Gateway
73
+
Copy the raw key immediately. Codex Pooler shows it only once. Store it in the client environment variable you plan to use, for example:
82
74
83
-
For Codex backend clients, use the Codex backend compatibility route:
75
+
```bash
76
+
export CODEX_POOLER_API_KEY="<pool-api-key>"
77
+
```
78
+
79
+
The Pool API key represents the Pool, not one upstream account. Do not use this key for `/mcp`; operator MCP tokens are separate.
80
+
81
+
## 6. Point Your First Client At The Gateway
82
+
83
+
For Codex backend clients, use the backend compatibility route:
84
84
85
85
```text
86
86
Base URL: http://localhost:4000/backend-api/codex
87
87
Authorization: Bearer <pool-api-key>
88
88
```
89
89
90
-
For selected OpenAI-style SDK clients, use the narrow OpenAI-compatible `/v1`surface:
90
+
For OpenAI-compatible SDK clients, use the narrow `/v1`route:
91
91
92
92
```text
93
93
Base URL: http://localhost:4000/v1
94
94
Authorization: Bearer <pool-api-key>
95
95
```
96
96
97
-
For trusted operator metadata tools, use the operator MCP endpoint with an operator MCP token, not a Pool API key:
97
+
For trusted operator metadata tools, use `/mcp` with an operator MCP token, not a Pool API key:
98
98
99
99
```text
100
100
MCP URL: http://localhost:4000/mcp
101
101
Authorization: Bearer <operator-mcp-token>
102
102
```
103
103
104
-
For deployed examples, replace the local host with `https://pooler.example.com`, such as `https://pooler.example.com/v1`.
104
+
For deployed instances, replace `http://localhost:4000` with your HTTPS host, for example `https://pooler.example.com`.
105
+
106
+
## If Something Is Stuck
107
+
108
+
Use these checks only when the page or client path is not behaving as expected.
109
+
110
+
```bash
111
+
docker compose ps
112
+
docker compose logs -f app
113
+
curl -fsS http://localhost:4000/healthz
114
+
curl -fsS http://localhost:4000/readyz
115
+
```
116
+
117
+
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.
118
+
119
+
To stop the local stack:
120
+
121
+
```bash
122
+
docker compose down
123
+
```
124
+
125
+
To remove the local database too:
105
126
106
-
## Support Boundary
127
+
```bash
128
+
docker compose down -v
129
+
```
107
130
108
-
The quick start checks that Codex Pooler starts, accepts owner setup, and can issue a Pool API key. It does not prove your upstream account is permitted for every model, that every SDK route is supported, or that your deployment is production-ready.
131
+
## Safety Notes
109
132
110
-
For responsible operation, give Pool API keys only to trusted clients, keep MCP tokens separate from runtime credentials, and don't paste prompts, tokens, cookies, or account secrets into support requests.
133
+
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.
0 commit comments