# 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](https://pi.dev/docs/latest/quickstart) using the official instructions for your operating system.
- Have a Codex Pooler URL reachable from the client.
- Create a [Pool API key](/getting-started/quick-start/) 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**
```bash
export CODEX_POOLER_API_KEY=""
```
**Windows PowerShell**
```powershell
$env:CODEX_POOLER_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:
```json title="models.json" frame="code"
{
"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`:
```json title="settings.json" frame="code"
{
"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**
```bash
pi --provider codex-pooler \
--model gpt-6-sol \
--no-session \
--no-context-files \
--tools bash \
-p 'Reply with exactly: pi ok'
```
**Windows PowerShell**
```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.