Configuration
Codex Pooler keeps boot-time release settings in environment variables and day-to-day operator settings in the database-backed admin UI.
Local Defaults
Section titled “Local Defaults”For Docker Compose, scripts/self-host/generate-env.sh writes a local .env file with generated secrets and local defaults. Keep that file private. Don’t reuse generated values across public installs.
The local web URL is http://localhost:4000.
Release Environment Variables
Section titled “Release Environment Variables”Set release environment variables for values the app needs before it can read database settings.
| Variable | Purpose |
|---|---|
CODEX_POOLER_IMAGE | Release image name used by the Compose flow |
CODEX_POOLER_IMAGE_TAG | Release image tag used by the Compose flow |
CODEX_POOLER_HTTP_PORT | Local host port, default 4000 |
DATABASE_URL | Postgres connection URL |
SECRET_KEY_BASE | Phoenix signing and encryption secret |
PHX_HOST | Public host used by the Phoenix endpoint |
PORT | HTTP port inside the release container |
PHX_SERVER | Set to true so the release serves HTTP |
OBAN_MODE | Release role, such as web, worker, scheduler, or all |
OBAN_JOBS_QUEUE_LIMIT | Job queue limit for the release role |
DNS_CLUSTER_QUERY | DNS clustering query when clustering is enabled |
CODEX_POOLER_TOTP_ENCRYPTION_KEY | TOTP encryption root key |
CODEX_POOLER_TOTP_KEY_VERSION | TOTP key version |
CODEX_POOLER_UPSTREAM_SECRET_KEY | Upstream secret encryption root key |
CODEX_POOLER_UPSTREAM_SECRET_KEY_VERSION | Upstream secret key version |
The upstream secret key must decode to 32 raw bytes. The TOTP and upstream key versions let operators rotate encrypted secret roots deliberately.
Admin-Managed Settings
Section titled “Admin-Managed Settings”After the app boots, manage operational settings from the admin UI instead of editing code. Instance settings cover areas such as file limits, ingress trust, gateway diagnostics, route-class admission, circuit thresholds, metrics auth, operator email, model metadata, upstream timeouts, pricing catalog settings, and SMTP delivery.
Secret settings stay write-only in the UI. For example, metrics bearer material is stored as a keyed digest and SMTP credentials are stored encrypted for mail delivery and credential checks.
Runtime URLs
Section titled “Runtime URLs”Use only the surface that matches your client.
| Client type | Local URL | Deployed example |
|---|---|---|
| Codex backend client | http://localhost:4000/backend-api/codex | https://pooler.example.com/backend-api/codex |
| Narrow OpenAI-compatible SDK client | http://localhost:4000/v1 | https://pooler.example.com/v1 |
| Operator MCP host | http://localhost:4000/mcp | https://pooler.example.com/mcp |
Use Authorization: Bearer <pool-api-key> for /backend-api and /v1. Use Authorization: Bearer <operator-mcp-token> for /mcp.
The operator MCP endpoint is metadata-only and read-only. It doesn’t accept Pool API keys, browser sessions, cookies, invite tokens, upstream tokens, or query tokens.
Health And Readiness
Section titled “Health And Readiness”Use these checks for a local instance:
curl -fsS http://localhost:4000/healthzcurl -fsS http://localhost:4000/readyzFor a deployed instance, use the same paths on https://pooler.example.com.
Support And Responsible Operation
Section titled “Support And Responsible Operation”The support boundary is intentionally narrow. Public docs can help you start the service, configure supported route surfaces, and understand metadata-only behavior. They can’t decide whether your organization may use a provider account, share a Pool, or connect a given MCP host.
For responsible operation:
- Operate only accounts you are allowed to use
- Keep Pool API keys separate from operator MCP tokens
- Rotate exposed credentials immediately
- Connect MCP only to hosts you trust with operator metadata
- Don’t send raw prompts, request bodies, response bodies, file bytes, audio, images, cookies, bearer tokens, Pool API keys, MCP tokens, upstream secrets, or
auth.jsonmaterial in support messages
Compatibility Notes
Section titled “Compatibility Notes”The Codex backend compatibility route is rooted at /backend-api/codex/*. The /v1 surface provides narrow OpenAI-compatible support for selected SDK routes, then routes supported requests through the same Pool policy and accounting path.
It does not provide full OpenAI API parity. OpenAI Realtime SDK websocket and session routes are not supported. GET /v1/responses is narrow Responses websocket compatibility, not /v1/realtime support.