# Kilo Code on Codex Pooler
Kilo Code should use a named OpenAI-compatible provider that points at Codex Pooler's `/v1` base URL. Kilo Code appends `/chat/completions` itself, so do not set `baseURL` to a full `/v1/chat/completions` endpoint.
## Before you start
- Kilo Code CLI 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](/getting-started/quick-start/) for model requests. Operator MCP access is optional and uses a separate token.
### Install
Use the current npm package:
```bash
npm install -g @kilocode/cli@latest
```
For one-off use without a global install, run `npx -y @kilocode/cli@latest`.
## Configure the connection
Set the Pool API key in the shell that starts the client:
```bash
export CODEX_POOLER_API_KEY=""
```
For a deployed instance, add `~/.config/kilo/kilo.jsonc`:
```jsonc title="~/.config/kilo/kilo.jsonc" frame="code"
{
"$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": "https://codex-pooler.example.com/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": 828400,
"input": 828400,
"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": 828400,
"input": 828400,
"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": 828400,
"input": 828400,
"output": 64000
}
},
"gpt-6-astra": {
"name": "GPT-6 Astra via Codex Pooler",
"tool_call": true,
"reasoning": true,
"temperature": false,
"attachment": true,
"modalities": {
"input": ["text", "image"],
"output": ["text"]
},
"limit": {
"context": 828400,
"input": 828400,
"output": 64000
}
}
}
}
},
"compaction": {
"reserved": 41420,
"threshold_percent": 95
}
}
```
For local setup, change `baseURL` to `http://localhost:4000/v1`.
`{env:CODEX_POOLER_API_KEY}` keeps the Pool API key outside the config file. Define only model ids your assigned Pool can serve. If you add Kilo Code permissions, use the object form such as `"permission": {"bash": "allow"}`; do not set `"permission": "ask"`, which is not a valid Kilo Code config shape.
## Choose a model
Set the top-level `model` to `codex-pooler/` followed by a model ID available to your Pool.
Kilo Code uses OpenCode-style `limit.{context,input,output}` fields but includes reasoning tokens in overflow accounting and supports `compaction.threshold_percent` for preflight compaction. 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` for `limit.context` and `limit.input`, not the raw ceiling. For the long-profile example, `compaction.reserved: 41420` and `threshold_percent: 95` make both safety checks meet at 786980 tokens. `limit.input` is the local pre-compaction boundary, not a simultaneous input-plus-output envelope.
For GPT-5 OpenAI-compatible models, Kilo Code suppresses the outgoing max-token request field to avoid incompatible `max_tokens`, so `limit.output` is still important for local context math and UI even when it is not forwarded.
## Verify the connection
Run a tool-using prompt from an isolated directory:
```bash
validation_dir="$(mktemp -d)"
cd "$validation_dir"
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'
```
`--pure` keeps external plugins out of the check. `--auto` is only for trusted isolated automation, because it lets Kilo Code approve tool permissions automatically.
Confirm that `kilo-ok.txt` contains the expected text. 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
### Route shape
Kilo Code is a chat-completions client. It sends model requests to `POST /v1/chat/completions`, and Codex Pooler translates supported chat-completions requests into Codex Responses work internally. Do not point Kilo Code at `/backend-api/codex`, `/v1/responses`, or `/v1/chat/completions` as the configured base URL.
### MCP boundary
Kilo Code model requests use Codex Pooler's narrow OpenAI-compatible `/v1` support for selected SDK routes. Codex Pooler doesn't provide full OpenAI API parity.
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.