Pi on Codex Pooler

Pi is an extensible coding agent that works in your terminal. Use it to explore a project, edit files and run commands, with extensions and settings to adapt the workflow. Connect it to Codex Pooler to make your Pool’s models available in Pi’s model picker and coding sessions.

Before you start

• Install Pi using the official instructions for your operating system.
• Have a Codex Pooler URL reachable from the client.
• Create a Pool API key and choose a model available to that Pool.

Configure the connection

Use the commands for the terminal that starts the client. Environment-variable assignments below apply to that terminal; desktop apps and services need the variables in their own launch environment.

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

macOS / Linux / WSL

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

Windows PowerShell

$env:CODEX_POOLER_API_KEY = "<pool-api-key>"

Config file path

Global providers and models

OS	Default config file
macOS	~/.pi/agent/models.json
Linux	~/.pi/agent/models.json
Windows	%USERPROFILE%\.pi\agent\models.json

Global defaults and preferences

OS	Default config file
macOS	~/.pi/agent/settings.json
Linux	~/.pi/agent/settings.json
Windows	%USERPROFILE%\.pi\agent\settings.json

Saved project trust decisions

OS	Default config file
macOS	~/.pi/agent/trust.json
Linux	~/.pi/agent/trust.json
Windows	%USERPROFILE%\.pi\agent\trust.json

Saved sessions

OS	Default config folder
macOS	~/.pi/agent/sessions/
Linux	~/.pi/agent/sessions/
Windows	%USERPROFILE%\.pi\agent\sessions\

These are the default locations. On Windows, paste the %USERPROFILE%, %APPDATA% or %LOCALAPPDATA% path into File Explorer’s address bar. For a client installed inside WSL, use the Linux paths and commands inside WSL. Keep any custom configuration folder or profile you already use.

Project overrides belong in .pi/settings.json inside the project on every platform. If you set PI_CODING_AGENT_DIR, use that folder for the global files instead.

Provider shape

For a deployed instance, add:

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 settings.json in the same folder as models.json:

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:

macOS / Linux / WSL

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

Windows PowerShell

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.