Pi Configuration

Pi is a terminal coding agent published as @earendil-works/pi-coding-agent. It ships with transports for several API dialects, so it can use CodeByAI with either the OpenAI-compatible or the Anthropic-compatible endpoint — the only thing you write by hand is one JSON file.

1. Install Pi

macOS or Linux:

Copy
1
curl -fsSL https://pi.dev/install.sh | sh

With npm (Node.js 22.19 or newer):

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

On Windows use powershell -c "irm https://pi.dev/install.ps1 | iex".

2. Create the model configuration

Pi keeps its configuration in ~/.pi/agent/ and reads custom endpoints from models.json:

• macOS / Linux: ~/.pi/agent/models.json
• Windows: C:\Users\YourUserName\.pi\agent\models.json

The folder may not exist yet; create it, then create models.json:

Copy
1
{
2
  "$schema": "https://pi.dev/schemas/models.schema.json",
3
  "providers": {
4
    "codebyai": {
5
      "name": "CodeByAI",
6
      "baseUrl": "https://www.codebyai.net/api/agent",
7
      "api": "openai-completions",
8
      "apiKey": "$CODEBYAI_API_KEY",
9
      "models": [
10
        {
11
          "id": "gpt-5.6-terra",
12
          "name": "GPT-5.6 Terra",
13
          "contextWindow": 200000,
14
          "maxTokens": 32768
15
        }
16
      ]
17
    },
18
    "codebyai-claude": {
19
      "name": "CodeByAI (Claude)",
20
      "baseUrl": "https://www.codebyai.net/api/agent",
21
      "api": "anthropic-messages",
22
      "apiKey": "$CODEBYAI_API_KEY",
23
      "models": [
24
        {
25
          "id": "claude-sonnet-5",
26
          "name": "Claude Sonnet 5",
27
          "contextWindow": 200000,
28
          "maxTokens": 32768
29
        }
30
      ]
31
    }
32
  }
33
}

What matters here:

• api is the wire protocol. openai-completions calls /chat/completions and carries the GPT family; anthropic-messages calls /v1/messages and carries the Claude family. One provider entry per protocol is the simplest arrangement.
• baseUrl stops at /api/agent. Do not append /v1: the gateway forwards the rest of the path upstream, so a call to /api/agent/v1/chat/completions answers 404 page not found.
• apiKey supports $VARIABLE and ${VARIABLE} interpolation, so no secret is stored in the file.
• models accepts any id from the Model Plaza. contextWindow and maxTokens only steer Pi's own budgeting; they are not sent upstream.

3. Provide the API Key

Copy
1
export CODEBYAI_API_KEY="sk-proj-xxxx"

Add it to ~/.zshrc or ~/.bashrc to keep it across sessions. Create the key itself on the API Keys page. Pi also accepts --api-key on the command line for a single run.

4. Start Pi

Copy
1
cd your-project
2
pi --model codebyai/gpt-5.6-terra

To use a Claude model through the Anthropic-compatible route:

Copy
1
pi --model codebyai-claude/claude-sonnet-5

To check what Pi can see before starting a session:

Copy
1
pi --list-models codebyai

5. Troubleshooting

• 404 page not found: baseUrl ends with /v1. Remove it.
• No models available, or the provider missing from pi --list-models: CODEBYAI_API_KEY is empty in the shell that launched Pi, so Pi skips the entry. An unknown model id is still listed, so a missing model is almost always a missing key.
• A reply that begins Hello! How can I help you with your software engineering tasks today? (HTTP 403): the gateway received no API key — the variable is empty in this shell. A second 403 reading Invalid key! means the key itself was deleted or mistyped.
• Insufficient balance: top up on the Wallet page.