Codex Pooler

The full featured self-hosted Codex gateway, for teams, agents and you. Works with:

English · 简体中文

Quick start · Harness · Configuration · Deployment

Upstreams

Pools

Request logs

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

• 🔑 Stable Pool API keys: give clients one Pool credential whether the Pool currently has one upstream account or several, without distributing raw Codex account material
• 🎯 Eligibility-aware routing: route each request to an account with compatible model support, usable quota evidence, matching health, session state, and Pool policy
• 🧩 Codex backend compatibility: point Codex-compatible clients at Codex Pooler and keep responses, compacting, usage, files, audio, images, and backend websocket flows working through assigned accounts
• 🔌 OpenAI-compatible SDK surface: let /v1-only apps and agent tools use Codex capacity through the same Pool boundary, with supported requests translated and routed to help contain API spend
• 🔁 Session-aware websockets: keep resumable Codex sessions and websocket reconnects attached to the right upstream account without translating backend websocket traffic through an HTTP compatibility layer
• ⚡ Prompt-cache locality: use a transient prompt_cache_key to prefer the same eligible upstream account for repeat stateless requests, improving provider-side cache locality without storing prompts or responses locally
• 🗜️ Per-Pool request compression: optionally compress upstream-bound Responses tool outputs before dispatch on supported request routes. The option is disabled by default, request-side only, and records safe aggregate savings without storing raw outputs.
• 🏦 Saved reset management: surface reported saved reset capacity on upstream accounts, show informational expirations when available, and let operators queue account-level recovery or opt into guarded auto-redemption policy
• 🚨 Operator alerting: define Pool-aware rules for capacity, upstream health, saved reset events, and delivery failures, then notify operators through admin incidents, email, or webhooks without exposing raw request content
• 🖥️ Operator dashboard: manage Pool-scoped accounts, API keys, invites, saved resets, usage, request logs, audit logs, MCP access, and the owner-only jobs, operators, and system settings surfaces
• 🔭 Per-key Observatory: switch on read-only Observatory access for any Pool API key and its holder gets a live, self-service dashboard of just that key's usage, models, latency, cache, and spend — a monitor-friendly view to keep on a second screen, with no operator controls or other keys in reach
• 🛡️ Privacy-minded observability: store request, routing, and audit metadata without storing prompts, file bodies, audio, images, bearer tokens, cookies, raw Codex account tokens, or raw API keys
• 🧱 Runtime ingress firewall: optionally restrict incoming runtime traffic to approved client networks for an extra deployment-level security boundary
• ⚙️ Configurable without code changes: tune Pool policy, gateway defaults, diagnostics, model support, limits, and operational settings from the admin UI
• 🐳 Built for self-hosting: run on Elixir/Erlang's fault-tolerant runtime, start locally with Docker Compose, or deploy the Helm chart with separate web, worker, scheduler, and migration roles for Kubernetes-friendly, multinode growth

Harness Configuration

Keep Pool API keys in environment variables when the harness supports secret expansion. The /mcp endpoint is an optional operator-only add-on for metadata inspection; Codex Pooler runtime clients do not need it. If a desktop harness persists remote MCP headers in its own private settings, use a dedicated operator-scoped MCP token. For a local instance, the URLs are:

Codex backend base URL:      http://localhost:4000/backend-api/codex
OpenAI SDK base URL:         http://localhost:4000/v1
Optional operator MCP URL:   http://localhost:4000/mcp

For a deployed instance, replace http://localhost:4000 with your deployed host, for example https://codex-pooler.example.com.

{
  "$schema": "https://opencode.ai/config.json",
  "small_model": "openai/gpt-5.6-luna",
  "compaction": {
    "auto": true,
    "reserved": 7080
  },
  "provider": {
    "openai": {
      "npm": "@ai-sdk/openai",
      "name": "Codex Pooler",
      "options": {
        "baseURL": "http://localhost:4000/v1",
        "apiKey": "{env:CODEX_POOLER_API_KEY}"
      },
      "models": {
        "gpt-5.6-luna": {
          "id": "gpt-5.6-luna",
          "name": "GPT-5.6 Luna",
          "family": "gpt",
          "attachment": true,
          "reasoning": true,
          "tool_call": true,
          "temperature": false,
          "options": {
            "reasoningEffort": "high",
            "reasoningSummary": "auto",
            "textVerbosity": "medium",
            "include": ["reasoning.encrypted_content"],
            // Optional: priority processing may cost more than the default tier.
            // "serviceTier": "priority"
          },
          "modalities": {
            "input": ["text", "image"],
            "output": ["text"]
          },
          "limit": {
            "context": 258400,
            "input": 252560,
            "output": 64000
          }
        },
        "gpt-5.6-terra": {
          "id": "gpt-5.6-terra",
          "name": "GPT-5.6 Terra",
          "family": "gpt",
          "attachment": true,
          "reasoning": true,
          "tool_call": true,
          "temperature": false,
          "options": {
            "reasoningEffort": "high",
            "reasoningSummary": "auto",
            "textVerbosity": "medium",
            "include": ["reasoning.encrypted_content"],
            // Optional: priority processing may cost more than the default tier.
            // "serviceTier": "priority"
          },
          "modalities": {
            "input": ["text", "image"],
            "output": ["text"]
          },
          "limit": {
            "context": 258400,
            "input": 252560,
            "output": 64000
          }
        },
        "gpt-5.6-sol": {
          "id": "gpt-5.6-sol",
          "name": "GPT-5.6 Sol",
          "family": "gpt",
          "attachment": true,
          "reasoning": true,
          "tool_call": true,
          "temperature": false,
          "options": {
            "reasoningEffort": "high",
            "reasoningSummary": "auto",
            "textVerbosity": "medium",
            "include": ["reasoning.encrypted_content"],
            // Optional: priority processing may cost more than the default tier.
            // "serviceTier": "priority"
          },
          "modalities": {
            "input": ["text", "image"],
            "output": ["text"]
          },
          "limit": {
            "context": 258400,
            "input": 252560,
            "output": 64000
          }
        }
      }
    }
  },
  // Optional operator-only MCP metadata add-on. Omit for normal model/runtime use.
  "mcp": {
    "codex_pooler": {
      "type": "remote",
      "url": "http://localhost:4000/mcp",
      "oauth": false,
      "headers": {
        "Authorization": "Bearer {env:CODEX_POOLER_MCP_KEY}"
      },
      "enabled": true,
      "timeout": 30000
    }
  }
}

model_provider = "codex-pooler-ws"

[model_providers.codex-pooler-ws]
name = "OpenAI"
base_url = "http://localhost:4000/backend-api/codex"
env_key = "CODEX_POOLER_API_KEY"
wire_api = "responses"
supports_websockets = true
requires_openai_auth = true

model_provider = "codex-pooler-http"

[model_providers.codex-pooler-http]
name = "OpenAI"
base_url = "http://localhost:4000/backend-api/codex"
env_key = "CODEX_POOLER_API_KEY"
wire_api = "responses"
supports_websockets = false
requires_openai_auth = true

[mcp_servers.codex_pooler]
url = "http://localhost:4000/mcp"
bearer_token_env_var = "CODEX_POOLER_MCP_KEY"

if [ -d "$HOME/.codex/sessions" ]; then find "$HOME/.codex/sessions" -type f -name '*.jsonl' -exec perl -0pi -e 's/("model_provider"\s*:\s*)"openai"/$1"codex-pooler-ws"/g' {} +; fi

for db in "$HOME"/.codex/state_*.sqlite(N); do sqlite3 "$db" "UPDATE threads SET model_provider = 'codex-pooler-ws' WHERE model_provider = 'openai';"; done

if [ -d "$HOME/.codex/sessions" ]; then find "$HOME/.codex/sessions" -type f -name '*.jsonl' -exec perl -0pi -e 's/("model_provider"\s*:\s*)"openai"/$1"codex-pooler-ws"/g' {} +; fi

for db in "$HOME"/.codex/state_*.sqlite; do [ -e "$db" ] || continue; sqlite3 "$db" "UPDATE threads SET model_provider = 'codex-pooler-ws' WHERE model_provider = 'openai';"; done

$ErrorActionPreference = "Stop"

$FromProvider = "openai"
$ToProvider = "codex-pooler-ws"
$CodexHome = Join-Path $HOME ".codex"

$FromJson = '"model_provider":"' + $FromProvider + '"'
$ToJson = '"model_provider":"' + $ToProvider + '"'

Get-ChildItem -Path (Join-Path $CodexHome "sessions") -Recurse -Filter "*.jsonl" |
  ForEach-Object {
    $Path = $_.FullName
    $TempPath = "$Path.tmp"
    $Reader = [System.IO.StreamReader]::new($Path)
    $Writer = [System.IO.StreamWriter]::new(
      $TempPath,
      $false,
      [System.Text.UTF8Encoding]::new($false)
    )

    try {
      while (($Line = $Reader.ReadLine()) -ne $null) {
        $Writer.WriteLine($Line.Replace($FromJson, $ToJson))
      }
    } finally {
      $Reader.Dispose()
      $Writer.Dispose()
    }

    Move-Item -Force $TempPath $Path
  }

Get-ChildItem -Path $CodexHome -Filter "state_*.sqlite" |
  ForEach-Object {
    sqlite3 $_.FullName `
      "UPDATE threads SET model_provider = '$ToProvider' WHERE model_provider = '$FromProvider';"
  }

{
  agents: {
    defaults: {
      model: {
        primary: "openai/gpt-5.6-terra",
        list: [
          {
            id: "background",
            model: "openai/gpt-5.6-luna",
          },
        ],
      },
      compaction: { reserveTokens: 20000 },
    },
  },
  models: {
    mode: "merge",
    providers: {
      openai: {
        baseUrl: "http://localhost:4000/v1",
        apiKey: "${CODEX_POOLER_API_KEY}",
        api: "openai-responses",
        agentRuntime: { id: "openclaw" },
        timeoutSeconds: 300,
        models: [
          {
            id: "gpt-5.6-luna",
            name: "GPT-5.6 Luna via Codex Pooler",
            reasoning: true,
            input: ["text", "image"],
            contextWindow: 272000,
            contextTokens: 258400,
            maxTokens: 128000,
          },
          {
            id: "gpt-5.6-terra",
            name: "GPT-5.6 Terra via Codex Pooler",
            reasoning: true,
            input: ["text", "image"],
            contextWindow: 272000,
            contextTokens: 258400,
            maxTokens: 128000,
          },
          {
            id: "gpt-5.6-sol",
            name: "GPT-5.6 Sol via Codex Pooler",
            reasoning: true,
            input: ["text", "image"],
            contextWindow: 272000,
            contextTokens: 258400,
            maxTokens: 128000,
          },
        ],
      },
    },
  },
  // Optional operator-only MCP metadata add-on. Omit for normal model/runtime use.
  mcp: {
    servers: {
      codex_pooler: {
        url: "http://localhost:4000/mcp",
        transport: "streamable-http",
        headers: {
          Authorization: "Bearer ${CODEX_POOLER_MCP_KEY}",
        },
      },
    },
  },
}

OPENAI_API_KEY=<pool-api-key>
OPENAI_BASE_URL=http://localhost:4000/v1
# Optional operator-only MCP metadata add-on:
CODEX_POOLER_MCP_KEY=<operator-mcp-token>

model:
  default: gpt-5.6-terra
  provider: openai-api
  base_url: http://localhost:4000/v1
  api_mode: codex_responses
  context_length: 258400
  supports_vision: true

agent:
  image_input_mode: native

image_gen:
  provider: openai
  model: gpt-image-2-medium

compression:
  threshold: 0.95

auxiliary:
  compression:
    timeout: 900

# Optional operator-only MCP metadata add-on. Omit for model/runtime use.
mcp_servers:
  codex_pooler:
    url: http://localhost:4000/mcp
    headers:
      Authorization: "Bearer ${CODEX_POOLER_MCP_KEY}"
    enabled: true
    timeout: 120
    connect_timeout: 15

hermes -z 'Reply with exactly: hermes openai api ok' --ignore-rules

HERMES_CODEX_BASE_URL=http://localhost:4000/v1
# Optional operator-only MCP metadata add-on:
CODEX_POOLER_MCP_KEY=<operator-mcp-token>

model:
  default: gpt-5.6-terra
  provider: openai-codex
  base_url: http://localhost:4000/v1
  context_length: 258400
  supports_vision: true

agent:
  image_input_mode: native

compression:
  threshold: 0.95

auxiliary:
  compression:
    timeout: 900

# Optional operator-only MCP metadata add-on. Omit for model/runtime use.
mcp_servers:
  codex_pooler:
    url: http://localhost:4000/mcp
    headers:
      Authorization: "Bearer ${CODEX_POOLER_MCP_KEY}"
    enabled: true
    timeout: 120
    connect_timeout: 15

{
  "active_provider": "openai-codex",
  "credential_pool": {
    "openai-codex": [
      {
        "label": "codex-pooler",
        "auth_type": "api_key",
        "priority": -10,
        "source": "manual",
        "access_token": "<pool-api-key>",
        "base_url": "http://localhost:4000/v1"
      }
    ]
  }
}

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

{
  "providers": {
    "codex-pooler": {
      "name": "Codex Pooler",
      "baseUrl": "http://localhost:4000/v1",
      "api": "openai-responses",
      "apiKey": "$CODEX_POOLER_API_KEY",
      "authHeader": true,
      "models": [
        {
          "id": "gpt-5.6-luna",
          "name": "GPT-5.6 Luna via Codex Pooler",
          "reasoning": true,
          "thinkingLevelMap": {
            "xhigh": "xhigh"
          },
          "input": ["text", "image"],
          "contextWindow": 258400,
          "maxTokens": 128000
        },
        {
          "id": "gpt-5.6-terra",
          "name": "GPT-5.6 Terra via Codex Pooler",
          "reasoning": true,
          "thinkingLevelMap": {
            "xhigh": "xhigh"
          },
          "input": ["text", "image"],
          "contextWindow": 258400,
          "maxTokens": 128000
        },
        {
          "id": "gpt-5.6-sol",
          "name": "GPT-5.6 Sol via Codex Pooler",
          "reasoning": true,
          "thinkingLevelMap": {
            "xhigh": "xhigh"
          },
          "input": ["text", "image"],
          "contextWindow": 258400,
          "maxTokens": 128000
        }
      ]
    }
  }
}

{
  "defaultProvider": "codex-pooler",
  "defaultModel": "gpt-5.6-terra",
  "defaultThinkingLevel": "xhigh",
  "enabledModels": [
    "codex-pooler/gpt-5.6-luna",
    "codex-pooler/gpt-5.6-terra",
    "codex-pooler/gpt-5.6-sol"
  ],
  "compaction": {
    "reserveTokens": 12920
  }
}

export CODEX_POOLER_API_KEY=<pool-api-key>
pi --provider codex-pooler \
  --model gpt-5.6-terra \
  --no-session \
  --no-context-files \
  --tools bash \
  -p 'Reply with exactly: pi ok'

bun install -g @oh-my-pi/pi-coding-agent

providers:
  codex-pooler:
    baseUrl: http://localhost:4000/v1
    api: openai-responses
    apiKey: CODEX_POOLER_API_KEY
    authHeader: true
    remoteCompaction:
      enabled: true
      api: openai-codex-responses
      endpoint: http://localhost:4000/backend-api/codex/responses/compact
      v2StreamingEnabled: true
      v2Endpoint: http://localhost:4000/backend-api/codex/responses
    models:
      - id: gpt-5.6-terra
        name: GPT-5.6 Terra via Codex Pooler
        reasoning: true
        input:
          - text
          - image
        compat:
          streamIdleTimeoutMs: 300000
        contextWindow: 258400
        maxTokens: 128000
      - id: gpt-5.6-luna
        name: GPT-5.6 Luna via Codex Pooler
        reasoning: true
        input:
          - text
          - image
        compat:
          streamIdleTimeoutMs: 300000
        contextWindow: 258400
        maxTokens: 128000
      - id: gpt-5.6-sol
        name: GPT-5.6 Sol via Codex Pooler
        reasoning: true
        input:
          - text
          - image
        compat:
          streamIdleTimeoutMs: 300000
        contextWindow: 258400
        maxTokens: 128000

startup:
  setupWizard: false
defaultThinkingLevel: xhigh
enabledModels:
  - codex-pooler/gpt-5.6-luna
  - codex-pooler/gpt-5.6-terra
  - codex-pooler/gpt-5.6-sol
modelProviderOrder:
  - codex-pooler
modelRoles:
  default: codex-pooler/gpt-5.6-terra:xhigh
  smol: codex-pooler/gpt-5.6-luna:low
  tiny: codex-pooler/gpt-5.6-luna:minimal
  slow: codex-pooler/gpt-5.6-sol:xhigh
  plan: codex-pooler/gpt-5.6-sol:xhigh
  task: codex-pooler/gpt-5.6-terra:high
  vision: codex-pooler/gpt-5.6-terra:high
  advisor: codex-pooler/gpt-5.6-terra:medium
  commit: codex-pooler/gpt-5.6-luna:minimal
  designer: codex-pooler/gpt-5.6-sol:high
compaction:
  thresholdPercent: 95
  reserveTokens: 128000
  remoteEnabled: true
  remoteStreamingV2Enabled: true
  midTurnEnabled: true
  handoffSaveToDisk: true

export CODEX_POOLER_API_KEY=<pool-api-key>
omp --model codex-pooler/gpt-5.6-terra:xhigh \
  --no-session \
  --tools bash \
  -p 'Reply with exactly: omp ok'

npm install -g @kilocode/cli@latest

{
  "$schema": "https://app.kilo.ai/config.json",
  "model": "codex-pooler/gpt-5.6-terra",
  "enabled_providers": ["codex-pooler"],
  "provider": {
    "codex-pooler": {
      "options": {
        "apiKey": "{env:CODEX_POOLER_API_KEY}",
        "baseURL": "http://localhost:4000/v1"
      },
      "models": {
        "gpt-5.6-luna": {
          "name": "GPT-5.6 Luna via Codex Pooler",
          "tool_call": true,
          "reasoning": true,
          "temperature": false,
          "attachment": true,
          "modalities": {
            "input": ["text", "image"],
            "output": ["text"]
          },
          "limit": {
            "context": 258400,
            "input": 258400,
            "output": 64000
          }
        },
        "gpt-5.6-terra": {
          "name": "GPT-5.6 Terra via Codex Pooler",
          "tool_call": true,
          "reasoning": true,
          "temperature": false,
          "attachment": true,
          "modalities": {
            "input": ["text", "image"],
            "output": ["text"]
          },
          "limit": {
            "context": 258400,
            "input": 258400,
            "output": 64000
          }
        },
        "gpt-5.6-sol": {
          "name": "GPT-5.6 Sol via Codex Pooler",
          "tool_call": true,
          "reasoning": true,
          "temperature": false,
          "attachment": true,
          "modalities": {
            "input": ["text", "image"],
            "output": ["text"]
          },
          "limit": {
            "context": 258400,
            "input": 258400,
            "output": 64000
          }
        }
      }
    }
  },
  "compaction": {
    "reserved": 12920,
    "threshold_percent": 95
  }
}

validation_dir="$(mktemp -d)"
cd "$validation_dir"

export CODEX_POOLER_API_KEY=<pool-api-key>
kilo run \
  --model codex-pooler/gpt-5.6-terra \
  --pure \
  --auto \
  --format json \
  --dir "$PWD" \
  'Use your tools to create kilo-ok.txt containing exactly: kilo ok. After the file exists, reply with exactly: kilo ok'

Custom Request URL:
https://codex-pooler.example.com/v1

Full URL:
off

curl -sS -X POST \
  -H "Authorization: Bearer $CODEX_POOLER_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "model": "gpt-5.6-terra",
    "messages": [
      { "role": "user", "content": "Reply with exactly: trae ok" }
    ],
    "stream": false,
    "max_completion_tokens": 16
  }' \
  https://codex-pooler.example.com/v1/chat/completions

# ~/.aider.conf.yml or <repo>/.aider.conf.yml
model: openai/gpt-5.6-terra
openai-api-base: http://localhost:4000/v1

// .aider.model.metadata.json
{
  "openai/gpt-5.6-luna": {
    "max_tokens": 258400,
    "max_input_tokens": 130400,
    "max_output_tokens": 128000,
    "litellm_provider": "openai",
    "mode": "chat",
    "supports_function_calling": true,
    "supports_vision": true,
    "supports_reasoning": true
  },
  "openai/gpt-5.6-terra": {
    "max_tokens": 258400,
    "max_input_tokens": 130400,
    "max_output_tokens": 128000,
    "litellm_provider": "openai",
    "mode": "chat",
    "supports_function_calling": true,
    "supports_vision": true,
    "supports_reasoning": true
  },
  "openai/gpt-5.6-sol": {
    "max_tokens": 258400,
    "max_input_tokens": 130400,
    "max_output_tokens": 128000,
    "litellm_provider": "openai",
    "mode": "chat",
    "supports_function_calling": true,
    "supports_vision": true,
    "supports_reasoning": true
  }
}

export OPENAI_API_KEY="$CODEX_POOLER_API_KEY"

aider \
  --message 'Create a file named aider-ok.txt containing exactly: aider ok. After the file exists, reply with exactly: aider ok' \
  --yes-always \
  --no-auto-commits \
  --no-git \
  --no-browser \
  --no-gui \
  --no-analytics

name: Codex Pooler
version: 1.0.0
schema: v1

models:
  - name: GPT-5.6 Terra via Codex Pooler
    provider: openai
    model: gpt-5.6-terra
    apiBase: http://localhost:4000/v1
    apiKey: "${{ secrets.CODEX_POOLER_API_KEY }}"
    contextLength: 258400
    defaultCompletionOptions:
      maxTokens: 128000
    roles:
      - chat
      - edit
      - apply
      - summarize
    capabilities:
      - tool_use
      - image_input

# Optional operator-only MCP metadata add-on. Omit for model/runtime use.
mcpServers:
  - name: codex_pooler
    type: streamable-http
    url: http://localhost:4000/mcp
    requestOptions:
      timeout: 30000
      headers:
        Authorization: "Bearer ${{ secrets.CODEX_POOLER_MCP_KEY }}"

export CODEX_POOLER_API_KEY=<pool-api-key>
npx -y @continuedev/cli@latest -p \
  --config ~/.continue/config.yaml \
  --silent \
  'Reply with exactly: continue ok'

cline auth \
  --provider openai \
  --apikey "$CODEX_POOLER_API_KEY" \
  --baseurl http://localhost:4000/v1 \
  --modelid gpt-5.6-terra

cline --provider openai \
  --model gpt-5.6-terra \
  --json \
  --auto-approve false \
  'Reply with exactly: cline ok'

{
  "mcpServers": {
    "codex_pooler": {
      "url": "http://localhost:4000/mcp",
      "headers": {
        "Authorization": "Bearer <operator-mcp-token>"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

GOOSE_PROVIDER: openai
GOOSE_MODEL: gpt-5.6-terra
OPENAI_HOST: http://localhost:4000
OPENAI_BASE_PATH: v1/chat/completions
GOOSE_CONTEXT_LIMIT: 258400
GOOSE_MAX_TOKENS: 128000
GOOSE_AUTO_COMPACT_THRESHOLD: 0.95

export OPENAI_API_KEY="$CODEX_POOLER_API_KEY"
goose run \
  --no-session \
  --provider openai \
  --model gpt-5.6-terra \
  --with-builtin developer \
  --text 'Use your developer tool to create goose-ok.txt containing exactly: goose ok. Then reply with exactly: goose ok'

# Optional operator-only MCP metadata add-on. Omit for model/runtime use.
extensions:
  codex_pooler:
    enabled: true
    type: streamable_http
    name: codex_pooler
    uri: http://localhost:4000/mcp
    headers:
      Authorization: "Bearer <operator-mcp-token>"
    timeout: 300
    bundled: null
    available_tools: []

wmill variable add '<pool-api-key>' \
  u/<owner>/codex_pooler_windmill_codegen \
  --workspace <workspace>

description: Codex Pooler API credentials for Windmill AI
value:
  api_key: '$var:u/<owner>/codex_pooler_windmill_codegen'
  base_url: http://localhost:4000/v1
  headers: {}
resource_type: customai

providers:
  customai:
    resource_path: u/<owner>/codex_pooler_windmill_codegen
    models:
      - gpt-5.6-luna
      - gpt-5.6-terra
      - gpt-5.6-sol
default_model:
  provider: customai
  model: gpt-5.6-terra
metadata_model:
  provider: customai
  model: gpt-5.6-terra

export LLM_API_KEY=<pool-api-key>
export LLM_BASE_URL=http://localhost:4000/v1
export LLM_MODEL=openai/gpt-5.6-terra

uvx --python 3.12 --from openhands openhands \
  --headless \
  --override-with-envs \
  -t 'Check the repository and summarize what you can do.'

import os

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["CODEX_POOLER_API_KEY"],
    base_url="http://localhost:4000/v1",
)

response = client.responses.create(
    model="gpt-5.6-terra",
    input="Write a one-sentence status update.",
)

print(response.output_text)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.CODEX_POOLER_API_KEY,
  baseURL: "http://localhost:4000/v1",
});

const response = await client.responses.create({
  model: "gpt-5.6-terra",
  input: "Write a one-sentence status update.",
});

console.log(response.output_text);

import { createOpenAI } from "@ai-sdk/openai";
import { generateText } from "ai";

const pooler = createOpenAI({
  apiKey: process.env.CODEX_POOLER_API_KEY,
  baseURL: "http://localhost:4000/v1",
});

const { text } = await generateText({
  model: pooler.responses("gpt-5.6-terra"),
  prompt: "Write a one-sentence status update.",
});

console.log(text);

Quick Start With Docker Compose

This runs the published release image with a local Postgres database. It is the fastest way to try Codex Pooler on a laptop or small server. For normal use, run a versioned, tagged stable release from GitHub Releases. The latest image tag follows the most recently published release, but a version tag keeps the installation reproducible; run from source only in Local Development.

Prerequisites:

• Docker with Compose
• Git, if you are cloning the repository
• openssl

Start Codex Pooler:

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

# Run the latest tagged stable release. Find its version at
# https://github.com/icoretech/codex-pooler/releases, then substitute it here.
export CODEX_POOLER_IMAGE_TAG=<release-tag>

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

The first run pulls the app and Postgres images, waits for Postgres health, runs the migration container, then starts the web app.

Open http://localhost:4000. On the first visit, create the owner account at /bootstrap, then sign in and start with /admin/pools.

To verify the first-run redirect before opening a browser:

curl -sS -D - -o /dev/null http://localhost:4000/ | grep -i '^location: /bootstrap'
curl -fsS http://localhost:4000/bootstrap/status

The status endpoint should return {"status":"ok","bootstrap":"pending"} on a fresh database.

Useful commands:

docker compose ps
docker compose logs -f app
docker compose down

To upgrade an existing Compose install, set CODEX_POOLER_IMAGE_TAG in .env to the target tagged stable release, then run:

docker compose pull
docker compose up -d

The Compose stack has a one-shot migrate service. It waits for Postgres, runs release migrations, imports the bundled pricing snapshot, and exits before the web app starts. Normal app boot does not migrate the database by itself. If a failed migration needs to be rerun after fixing configuration or database access, run:

docker compose up -d db
docker compose run --rm migrate
docker compose up -d app

Use http://localhost:4000 for the default Compose stack even if the Phoenix startup banner prints an endpoint URL such as https://localhost; the Compose port mapping is the local URL to open. The release image includes the OS timezone database used for operator timezone display.

To remove the local database too:

docker compose down -v

First Runtime Setup

After bootstrap:

1. Create a Pool in /admin/pools
2. Link, import, or invite one or more Codex accounts in /admin/upstreams
3. Create a Pool API key in /admin/api-keys
4. Point Codex or SDK clients at one of the runtime base URLs:

One upstream account is enough for a working setup. Additional upstreams expand the same Pool into shared capacity without changing client credentials.

Prefer OAuth in /admin/upstreams for new operator-managed upstream accounts when browser authorization is practical. The admin dialog links the account, stores resulting credential material through encrypted upstream secret storage, and stays metadata-only after completion. Use Import only when an existing Codex auth.json is the right source of credentials.

Treat an imported Codex auth.json as owned by Codex Pooler after import. Do not keep using the same auth.json from another Codex install, machine, or automation unless you accept that provider refresh-token rotation can invalidate one copy and move the account to reauth_required.

Hosted invite onboarding and the OAuth device-code fallback use OpenAI's Codex device-code authorization. This setup is only needed for hosted invites and the OAuth device-code fallback; browser OAuth linking does not depend on it. For a personal ChatGPT account, open chatgpt.com, go to Settings > Security, and enable Enable device code authorization for Codex. For workspace-managed accounts, ask a workspace admin to enable device-code login for Codex in the workspace permissions. OpenAI's Codex authentication docs describe device-code login. The invite or fallback flow can fail at the OpenAI approval step when device-code authorization is off.

Codex backend base URL: http://localhost:4000/backend-api/codex
OpenAI SDK base URL:    http://localhost:4000/v1

Use the generated Pool API key as the bearer token. That key represents the Pool, not a single Codex account, so Codex Pooler can pick the best eligible account for each request. Raw API keys are shown only once when created or rotated.

Operator Roles

The first bootstrap account is an instance_owner. Owners have instance-wide administration access: they create Pools, assign operators to Pools, manage operators, inspect global jobs, and change system settings.

Additional operators can be owners or instance_admins. Instance admins are Pool-scoped: they can work only with active Pools assigned to them and metadata derived from those Pools. If no Pools are assigned, the admin UI shows empty Pool-scoped states instead of exposing global data. Archiving or deleting a Pool removes future instance-admin visibility for that Pool; historical request and audit rows for archived or deleted Pools remain owner-only.

Runtime Compatibility

Use the client guides when wiring a specific tool. At a glance, clients pick one of two public shapes:

• Codex backend clients use /backend-api/codex for Codex-native behavior such as sessions, compacting, files, audio, images, and backend websockets.
• OpenAI-compatible clients use /v1 for supported SDK-style Responses, chat, files, audio, image, and model-list calls.

Both paths authenticate with Pool API keys and route through the same Pool policy, account health, model support, quota evidence, session continuity, and metadata-only accounting. Codex Pooler is intentionally not a wildcard OpenAI proxy; unsupported API areas fail predictably. For exact route details, use the Runtime Routes reference and the OpenAI-compatible client guide.

Operator MCP Service

Codex Pooler includes an optional metadata-only MCP endpoint at /mcp for trusted operators who want an MCP host to inspect Pools, upstream accounts, Pool API key metadata, operators, invites, request logs, audit logs, and MCP service status. This operator add-on is not required for Codex Pooler runtime clients. The service is read-only and has no mutation tools. It uses the same owner vs assigned-Pool visibility model as the admin UI, but connected MCP hosts can read the metadata visible to that operator, so only connect hosts you trust with that view.

MCP access uses operator-owned bearer MCP tokens, not Pool API keys, browser sessions, cookies, query tokens, invite tokens, upstream tokens, or custom headers. Operators manage their own MCP account gate and tokens from /admin/settings?tab=account; the instance-wide service gate is managed from /admin/system. Both gates must be enabled before a token works. Raw MCP tokens are shown only once when created, and per-key usage tracking, counters, last IP, and user-agent history are intentionally not stored.

The /mcp route inherits the runtime ingress IP allowlist and trusted-proxy settings. If the allowlist is empty, the firewall is off; if it is configured, the resolved client IP must match before MCP authentication or tool dispatch.

Configuration

scripts/self-host/generate-env.sh writes a local .env with generated secrets and local defaults. Keep that file private and don't reuse generated values between public installs.

Environment variables are only for values the release needs before it can read the database:

• CODEX_POOLER_IMAGE and CODEX_POOLER_IMAGE_TAG, the release image to run
• CODEX_POOLER_HTTP_PORT, the local host port, default 4000
• DATABASE_URL, the Postgres connection used by the app
• SECRET_KEY_BASE, Phoenix signing and encryption secret
• PHX_HOST, PORT, and PHX_SERVER, HTTP endpoint boot settings
• OBAN_MODE and OBAN_JOBS_QUEUE_LIMIT, release role and queue topology
• DNS_CLUSTER_QUERY, plus release distribution variables when clustering is on
• CODEX_POOLER_TOTP_ENCRYPTION_KEY and CODEX_POOLER_TOTP_KEY_VERSION, TOTP encryption root and version
• CODEX_POOLER_UPSTREAM_SECRET_KEY and CODEX_POOLER_UPSTREAM_SECRET_KEY_VERSION, upstream secret encryption root and version; the key must be 32 raw bytes or base64-encoded 32 bytes

Operational controls such as file limits, ingress trust, gateway diagnostics, route-class admission, circuit thresholds, metrics auth, operator email, model metadata, upstream timeouts, the OpenAI pricing catalog URL, and SMTP delivery live in DB-managed Instance Settings under /admin/system. Live settings apply to new runtime work through the settings cache. Cached settings reload after save through PubSub invalidation; existing leases, in-flight requests, and open streams keep the values they started with. The exception is an already-open Responses websocket: after a locally applied runtime-firewall settings snapshot, it re-evaluates the client IP captured during its handshake.

Secret Instance Settings stay write-only in the UI. The metrics bearer token is stored only as a keyed HMAC digest, fingerprint, and key version. The SMTP password is stored encrypted with key version metadata and is recovered only for mail send or credential-test paths.

Deployment

Choose the deployment path that matches how you want to operate Codex Pooler:

The Kubernetes path uses the icoretech/codex-pooler chart from the iCoreTech Helm repository. The chart runs one release image as separate web, worker, scheduler, and migration roles. For a real install, pin the chart --version; the chart defaults image.tag to the matching appVersion.

Need more Codex?

👉 codex-action runs OpenAI Codex CLI non-interactively in GitHub Actions workflows

👉 codex-docker provides a multi-arch OpenAI Codex CLI Docker image built from official upstream releases

Local Development

Local development runs Phoenix on the host and Postgres through the dev compose file:

make dev

make dev starts Postgres, prepares the database, imports the vendored OpenAI pricing feed, and starts the Phoenix server on http://localhost:4000. Logs are written to the local development server log.

Development seeds are optional and only run through the explicit seed task. To create a compact idempotent operator baseline with one owner plus four example operators, run:

mix dev.seed compact

All seeded operators use dev-password-123.

To recreate a fuller fake dataset for exercising admin UI states without real accounts or real request data, run:

mix dev.seed full

The full seed is idempotent and replaces only deterministic dev-* fake rows owned by the development seed namespace. It includes active/disabled pools, active/paused/revoked API keys, upstream accounts in active/refresh/reauth/paused states, quota windows, request logs, invites, audit events, and job rows.

Common checks:

mix precommit
mix quality
docker compose -f docker-compose.dev.yml config
docker build .

Helm chart validation lives with the published chart in the iCoreTech Helm repository when Kubernetes deployment behavior or values change.

mix test and mix precommit serialize database-backed test runs with a PostgreSQL advisory lock keyed by the configured test database, so concurrent local runs wait instead of deadlocking the shared sandbox database.