Connect Pi Coding Agent to NixAPI with models.json

Pi is an extensible terminal agent. This recipe was checked against its official repository on October 30, 2026. It adapts the documented custom-provider interface to NixAPI; actual compatibility depends on your model and key permissions.

1. Install Pi

The current README requires Node.js 22.19 or newer:

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

The official package name has changed. Older instructions using @mariozechner/pi-coding-agent should not be assumed current.

2. Set your key

Create a key in the NixAPI console and copy a tool-capable chat model ID from models and pricing.

On macOS or Linux:

export NIXAPI_API_KEY='YOUR_NIXAPI_API_KEY'

On Windows PowerShell:

$env:NIXAPI_API_KEY = 'YOUR_NIXAPI_API_KEY'

Replace the placeholder and launch Pi from that same terminal.

3. Add a custom provider

Create or edit ~/.pi/agent/models.json. Merge the nixapi entry into existing providers instead of replacing your whole configuration:

{
  "providers": {
    "nixapi": {
      "baseUrl": "https://api.nixapi.com/v1",
      "api": "openai-completions",
      "apiKey": "${NIXAPI_API_KEY}",
      "authHeader": true,
      "models": [
        {
          "id": "NIXAPI_MODEL_ID",
          "name": "NixAPI coding model",
          "contextWindow": 32768,
          "maxTokens": 4096
        }
      ]
    }
  }
}

Replace NIXAPI_MODEL_ID. The context and output numbers illustrate the structure; set them to the real limits of your selected model. baseUrl uses a lowercase l. The key uses ${NIXAPI_API_KEY} interpolation, and authHeader enables Bearer authentication. See the field reference.

4. Verify chat and tools

From a test project, replacing the model placeholder, run:

pi --provider nixapi --model NIXAPI_MODEL_ID

First request a short text response. Then ask Pi to read package.json and summarize its scripts without changing files. A restricted read-only check is:

pi --provider nixapi --model NIXAPI_MODEL_ID --no-mcp --tools read --print \
  'Read package.json using the read tool and summarize the scripts. Do not modify files.'

The CLI reference documents these flags. Inspect the tool result: text chat alone does not verify an agent’s tool-call round trip.

5. Troubleshoot

• Provider missing: check your JSON and file location; /model reloads model configuration according to the models guide.
• 401: check the environment variable in the terminal launching Pi and the interpolation syntax.
• 404: use https://api.nixapi.com/v1 without appending the complete Chat Completions path.
• Unknown model or failed tools: verify the exact ID, key permissions, and tool support. Increasing declared limits does not add model capabilities.