Pi on Codex Pooler

Pi should use Codex Pooler through a custom provider in ~/.pi/agent/models.json. Point that provider at the narrow OpenAI-compatible /v1 surface, keep the Pool API key in the environment, and choose openai-responses so Pi sends agent turns through the Responses route.

Before you start

• Pi installed and ready to use.
• A Codex Pooler URL reachable from the client.
• A Pool API key and a model available to that Pool.

Use a Pool API key for model requests. Operator MCP access is optional and uses a separate token.

Install

Use the current npm package:

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

--ignore-scripts matches Pi’s published install guidance and keeps dependency lifecycle scripts disabled during install.

Configure the connection

Set the Pool API key in the shell that starts the client:

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

Config file path

Pi docs use home-relative paths for global config and project-local .pi paths for overrides:

Path	Scope
~/.pi/agent/models.json	Global custom providers and models
~/.pi/agent/settings.json	Global defaults, UI behavior, resource paths, and project trust fallback
~/.pi/agent/trust.json	Saved project trust decisions
~/.pi/agent/sessions/	Saved sessions
.pi/settings.json	Project settings that override and merge with global settings

On Windows, use the same home-relative paths under the user profile, for example %USERPROFILE%\.pi\agent\models.json and %USERPROFILE%\.pi\agent\settings.json.

Provider shape

For a deployed instance, add:

~/.pi/agent/models.json

{
  "providers": {
    "codex-pooler": {
      "name": "Codex Pooler",
      "baseUrl": "https://codex-pooler.example.com/v1",
      "api": "openai-responses",
      "apiKey": "$CODEX_POOLER_API_KEY",
      "authHeader": true,
      "models": [
        {
          "id": "gpt-6-luna",
          "name": "GPT-6 Luna via Codex Pooler",
          "reasoning": true,
          "thinkingLevelMap": {
            "xhigh": "xhigh"
          },
          "input": ["text", "image"],
          "contextWindow": 828400,
          "maxTokens": 128000
        },
        {
          "id": "gpt-6-sol",
          "name": "GPT-6 Sol via Codex Pooler",
          "reasoning": true,
          "thinkingLevelMap": {
            "xhigh": "xhigh"
          },
          "input": ["text", "image"],
          "contextWindow": 828400,
          "maxTokens": 128000
        },
        {
          "id": "gpt-6-astra",
          "name": "GPT-6 Astra via Codex Pooler",
          "reasoning": true,
          "thinkingLevelMap": {
            "xhigh": "xhigh"
          },
          "input": ["text", "image"],
          "contextWindow": 828400,
          "maxTokens": 128000
        }
      ]
    }
  }
}

For local setup, change baseUrl to http://localhost:4000/v1.

authHeader: true makes Pi send the Pool API key as Authorization: Bearer .... Define only model ids your assigned Pool can serve.

Choose a model

Current Pi source still requires thinkingLevelMap.xhigh for Pi to expose xhigh for this custom model. Without it, Pi clamps --thinking xhigh and defaultThinkingLevel: "xhigh" down to high.

Pi accepts contextWindow and maxTokens for custom models; it has no contextTokens field. The 828400 values above are long-profile examples for models whose selected Pool catalog source reports an 872000-token raw ceiling. Provider accounts can temporarily report different ceilings for the same model; a selected 272000-token profile exposes 258400 instead. Use each model’s /v1/models.context_length as the authoritative contextWindow, not the raw ceiling. For the long-profile example, Pi compacts when usage exceeds contextWindow - reserveTokens; the 128000-token reserve leaves an explicit output budget and starts compaction at 700400 tokens.

Default model

If you want plain pi or pi -p ... to start on Codex Pooler, add the defaults to ~/.pi/agent/settings.json:

~/.pi/agent/settings.json

{
  "defaultProvider": "codex-pooler",
  "defaultModel": "gpt-6-sol",
  "defaultThinkingLevel": "xhigh",
  "enabledModels": [
    "codex-pooler/gpt-6-luna",
    "codex-pooler/gpt-6-sol",
    "codex-pooler/gpt-6-astra"
  ],
  "compaction": {
    "reserveTokens": 128000
  }
}

Verify the connection

Run a one-shot prompt from the repository you want Pi to inspect:

pi --provider codex-pooler \
  --model gpt-6-sol \
  --no-session \
  --no-context-files \
  --tools bash \
  -p 'Reply with exactly: pi ok'

--no-session keeps the check ephemeral. --no-context-files keeps it independent from local project instructions. For normal interactive use, omit those flags if you want Pi to load AGENTS.md, skills, sessions, and project settings.

In Codex Pooler’s request logs, match the request time, API key, model, and final status to your test. A reply alone does not confirm that the client used your Pooler instance.

Compatibility notes

Pi model requests use Codex Pooler’s narrow OpenAI-compatible /v1 support for selected SDK routes. Codex Pooler doesn’t provide full OpenAI API parity.

Pi does not ship built-in MCP support. Codex Pooler model use does not require MCP. If you need operator metadata from /mcp, use a separate MCP-capable host and authenticate it with an operator-owned MCP token, not the Pool API key.