Connect Pi Agent to Router One with models.json

Install Pi and export a dedicated gateway key

Pi 0.86.1 requires Node.js 22.19.0 or newer. Check the Node version before installing the pinned package below. Create a dedicated Router One key with a maxSpend cap, then export it in the terminal where Pi will run. ROUTER_ONE_API_KEY is the variable used by this guide; Pi reads it because models.json explicitly references it.

node --version
npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.86.1
pi --version
export ROUTER_ONE_API_KEY="sk-your-router-one-key"

Configure Pi Agent to use the Router One base URL

Add router-one inside the providers object of ~/.pi/agent/models.json, preserving any other providers already in that file. If PI_CODING_AGENT_DIR is set, use models.json in that directory instead. apiKey uses the dollar-prefixed environment syntax of Pi 0.86.1. The provider name router-one is a local label; model.id is the complete Router One catalog ID. The example uses a current chat model, keeps reasoning off and sets a 4096-token output cap for the first test. Replace the ID with another current chat model from /models when needed. The compat settings omit store, developer-role and reasoning-effort options in this introductory configuration; they do not declare that every model lacks those features.

{
  "providers": {
    "router-one": {
      "baseUrl": "https://api.router.one/v1",
      "api": "openai-completions",
      "apiKey": "$ROUTER_ONE_API_KEY",
      "compat": {
        "supportsStore": false,
        "supportsDeveloperRole": false,
        "supportsReasoningEffort": false
      },
      "models": [
        {
          "id": "anthropic/claude-sonnet-5",
          "reasoning": false,
          "input": [
            "text"
          ],
          "maxTokens": 4096
        }
      ]
    }
  }
}

Select the exact model, then test one text response

Run --list-models to check that Pi loaded the provider; this lists local configuration and does not prove the key or endpoint works. Run the text test below from an empty directory. It disables tools, session saving, extensions and project context, while the model request can still incur usage charges. Match the response with Dashboard → Logs by model, time and request_id, then start a normal interactive coding session. Keep --provider and --model separate so a slash inside the catalog ID remains unambiguous. After editing models.json during a session, reopen /model to reload it. Exporting a new environment variable in another shell does not change the environment of an already-running Pi process.

pi --list-models router-one
pi --provider router-one --model anthropic/claude-sonnet-5 \
  --no-tools --no-session --no-extensions --no-context-files \
  -p -- "Reply with one short greeting."

# Start normal interactive use after the text test succeeds
pi --provider router-one --model anthropic/claude-sonnet-5

Match the API type to its base URL

Pi chooses the request adapter from api; changing only the URL does not translate protocols. Use separate provider entries if you want both Chat Completions and a native protocol. Do not include the final /chat/completions, /messages or /responses segment in baseUrl.

Treat local token and cost settings as client configuration

Pi does not populate this custom provider from Router One’s /models endpoint. Add each model ID yourself and update contextWindow, maxTokens, input and reasoning for the selected model. contextWindow defaults to 128000 in Pi 0.86.1; maxTokens limits output, so it is not the context-window field. This example caps output at 4096 and permits text input only. Copy current capabilities from the model detail page before enabling image input or thinking. Omitted cost values default to zero, which can make Pi show zero estimated cost even when Router One bills the request. Router One’s settled Logs are the billing record; Pi’s cost rates are local estimates and do not automatically include account discounts, subscription rules or long-context tiers. Tool turns, retries and context compaction can produce additional model calls.

Which model ID should Pi Agent send?

Copy the exact model ID from /models, preserving case, hyphens, and version suffixes; do not substitute a display name. Open its detail page and match the supported API endpoints, context window, and capabilities such as tool calling to the provider and features selected in Pi Agent. A catalog listing does not mean the client can use every feature of that model. Give each tool a dedicated API key with a maxSpend cap.

Which API protocol is Pi Agent using?

OpenAI-compatible describes an interface format; it does not make Chat Completions (/v1/chat/completions), Responses (/v1/responses), and Anthropic Messages (/v1/messages) interchangeable. Check the installed client version, provider configuration, and actual request path against the model detail page and API compatibility fact sheet. A successful plain-text chat does not establish support for hosted tools, conversation state, or file-editing features.

Verify the Pi Agent call in your request trace

Send a simple text request from Pi Agent, then match its trace in Dashboard → Logs by time, model, and request_id: tokens, cost, latency, and status. Next, test streaming, tool calls, and multi-turn history separately. For failures, retain the actual request path, full error message, and request_id. If there is no matching log, check client configuration and connectivity before attributing the error to the gateway or upstream.

FAQ