pi Coding Agent API Setup

pi's official Custom Models mechanism loads gateways and custom models from ~/.pi/agent/models.json. TokenHub uses the openai-completions API type. There is no generic “Add Provider” form here; this configuration file is the supported entry point.

Step 1: prepare a credential for models.json

In the same terminal that launches pi, set:

export TOKENHUB_API_KEY="sk-..."

In models.json, the value must be "$TOKENHUB_API_KEY" to read an environment variable. pi's documentation notes that an uppercase string without $ is treated as a literal key, not an environment-variable name.

Step 2: edit ~/.pi/agent/models.json

{
  "providers": {
    "tokenhub": {
      "baseUrl": "__API_BASE_URL__/v1",
      "api": "openai-completions",
      "apiKey": "$TOKENHUB_API_KEY",
      "models": [
        {
          "id": "YOUR_TOKENHUB_MODEL_ID",
          "name": "TokenHub / YOUR_TOKENHUB_MODEL_ID",
          "reasoning": false,
          "input": ["text"],
          "contextWindow": 128000,
          "maxTokens": 8192
        }
      ]
    }
  }
}

Correct each field from the TokenHub model page:

• id is the model ID sent to the API and is required.
• Set reasoning to true only for a model that supports extended reasoning.
• input defaults to text. Use ["text", "image"] only for a model with image input.
• Although contextWindow has a default, declare the model's real context window.
• maxTokens is maximum output, not the context window.

TokenHub uses a Bearer token. If your pi version does not add the Authorization header automatically, add "authHeader": true at provider level.

Step 3: open /model to reload the file

Run /model inside a pi session. pi reloads models.json every time /model opens, so no restart is required. Choose tokenhub/YOUR_TOKENHUB_MODEL_ID, ask it to explain one file, and test tool calling only after that succeeds.

If the provider and model are displayed but not selectable, the file loaded but credentials did not resolve. Check the environment variable, or save the provider key with /login / auth.json.

Apply pi-specific compatibility overrides only when needed

Some OpenAI-compatible services reject the developer role or reasoning_effort. Add these flags only after the corresponding 400 error occurs:

"compat": {
  "supportsDeveloperRole": false,
  "supportsReasoningEffort": false
}

Do not disable capabilities preemptively. Once basic requests succeed, configure thinkingLevelMap, image input, sampling parameters, or pricing only for the exact model.

Troubleshoot according to pi's load behavior

• Provider entirely absent from /model: check the file path, JSON syntax, baseUrl, and api.
• Provider exists but model cannot be selected: $TOKENHUB_API_KEY did not resolve, or the provider lacks a saved credential.
• 401: confirm the pi process inherited the variable and set authHeader: true if required.
• 400 or early truncation: correct contextWindow, maxTokens, or compat; do not simply increase the numbers.
• Change does not appear: reopen /model instead of relying on the old selection shown in the current session.

Official references

• pi: Custom Models
• pi: Custom Providers Extension API