# Goose on Codex Pooler

Goose is an open-source AI agent for coding and other tasks on your computer. Its desktop app and CLI can work with files and tools to carry out multi-step workflows. Connect Goose to Codex Pooler to use your Pool's models in those sessions.

![Codex Pooler Goose integration](/codex-pooler-goose.webp)

## Before you start

- Install [Goose](https://goose-docs.ai/docs/getting-started/installation/) 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.

### Config file path

Put persistent Goose provider and extension settings in `config.yaml`:

| OS | Config file |
| --- | --- |
| macOS | `~/.config/goose/config.yaml` |
| Linux | `~/.config/goose/config.yaml` |
| Windows | `%APPDATA%\Block\goose\config\config.yaml` |

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.

If you set `GOOSE_PATH_ROOT`, the configuration folder is its `config` subfolder.

Goose also keeps related files in the same config area: `permission.yaml` for tool permission levels, `secrets.yaml` when file-based secret storage is used, `permissions/tool_permissions.json` for runtime permission decisions, and `prompts/` for prompt templates. Direct edits usually require restarting existing Goose sessions; `goose info -v` shows the active settings.

You can also manage settings from Goose Desktop **Settings** or by running `goose configure` in Goose CLI. Environment variables have higher precedence than the config file, so `OPENAI_API_KEY` can stay outside YAML.

Set `CODEX_POOLER_API_KEY` to your Pool API key, then export `OPENAI_API_KEY` in the shell that starts Goose, or use Goose's secret storage:

**macOS / Linux / WSL**

```bash
export OPENAI_API_KEY="$CODEX_POOLER_API_KEY"
```

**Windows PowerShell**

```powershell
$env:OPENAI_API_KEY = "$env:CODEX_POOLER_API_KEY"
```

Add the provider settings to `config.yaml`:

```yaml title="config.yaml" frame="code"
GOOSE_PROVIDER: openai
GOOSE_MODEL: gpt-6-sol
OPENAI_HOST: https://codex-pooler.example.com
OPENAI_BASE_PATH: v1/responses
GOOSE_CONTEXT_LIMIT: 828400
GOOSE_MAX_TOKENS: 128000
GOOSE_AUTO_COMPACT_THRESHOLD: 0.95
```

For local setup, change `OPENAI_HOST` to `http://localhost:4000`.

## Choose a model

Set `GOOSE_MODEL` to a model available to your Pool.

Goose reads `GOOSE_CONTEXT_LIMIT` and `GOOSE_MAX_TOKENS` into its model config. The `828400` value above is a long-profile example for a model 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 `/v1/models.context_length` as the authoritative `GOOSE_CONTEXT_LIMIT`, not the raw ceiling. For the long-profile example, Goose's `0.95` auto-compaction threshold starts compaction at 786980 tokens.

## Verify the connection

Check the headless CLI path with tool access enabled:

**macOS / Linux / WSL**

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

**Windows PowerShell**

```powershell
$env:OPENAI_API_KEY = "$env:CODEX_POOLER_API_KEY"
goose run --no-session --provider openai --model gpt-6-sol --with-builtin developer --text 'Use your developer tool to create goose-ok.txt containing exactly: goose ok. Then reply with exactly: goose ok'
```

Confirm that `goose-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.

## Operator MCP (optional)

For optional operator MCP metadata access, add a remote Streamable HTTP extension. Codex Pooler model use does not require this. Goose stores remote extension headers in its config, so use a dedicated MCP token.

```yaml title="config.yaml" frame="code"
# Optional operator-only MCP metadata add-on. Omit for model/runtime use.
extensions:
  codex_pooler:
    enabled: true
    type: streamable_http
    name: codex_pooler
    uri: https://codex-pooler.example.com/mcp
    headers:
      Authorization: "Bearer <operator-mcp-token>"
    timeout: 300
    bundled: null
    available_tools: []
```

For local MCP setup, change the extension `uri` to `http://localhost:4000/mcp`.

Use a Pool API key for OpenAI-compatible model requests and an operator MCP token for `/mcp`. Do not reuse the Pool API key for MCP.

## Compatibility notes

This client uses Codex Pooler's narrow OpenAI-compatible `/v1` surface. For shared route support and limits, see [OpenAI-compatible SDKs](/clients/openai-compatible/).