Pi | AI Gateway - Orq.ai Documentation

Pi is a minimal, extensible CLI coding agent. A single ~/.pi/agent/models.json file registers Orq.ai as a custom provider, so one session can mix models from any provider in the AI Gateway catalog, all routed through the AI Gateway for unified tracing, cost tracking, and access controls.

Prerequisites

Active Orq.ai account
Orq.ai API key

Install Pi

Install script
npm

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

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

Confirm the install with pi --version.

Setup

Create ~/.pi/agent/models.json and register Orq.ai as a custom provider:

{
  "providers": {
    "orq": {
      "baseUrl": "https://api.orq.ai/v3/router",
      "api": "openai-completions",
      "apiKey": "<ORQ_API_KEY>",
      "models": [
        {
          "id": "anthropic/claude-sonnet-5",
          "name": "Claude Sonnet 5 via Orq",
          "reasoning": true,
          "input": ["text", "image"]
        },
        {
          "id": "openai/gpt-5.6-sol",
          "name": "GPT-5.6 Sol via Orq",
          "reasoning": true,
          "input": ["text", "image"]
        },
        {
          "id": "google/gemini-3.6-flash",
          "name": "Gemini 3.6 Flash via Orq",
          "reasoning": true,
          "input": ["text", "image"]
        }
      ]
    }
  }
}

Replace <ORQ_API_KEY> with a key from Workspace Settings → API Keys. To avoid storing the key in plain text, use "apiKey": "$ORQ_API_KEY" and export the variable in the shell that launches Pi.~/.pi/agent/models.json is global, so the provider is available in every project without per-project configuration.

Start Pi and select a model

pi

Use /model to switch between registered models. The status bar shows the active provider and model, for example (orq) google/gemini-3.6-flash.

Pi ships built-in catalogs for Anthropic, OpenAI, and Google. When a credential such as OPENAI_API_KEY exists in the environment or in auth.json, those models are listed alongside the Orq.ai ones, and requests sent to them bypass the AI Gateway. The same model can appear in both lists. Check the provider column in pi --list-models: entries under orq route through the AI Gateway, entries under openai, anthropic, or google do not. The status bar shows (orq) while a routed model is active.

Configuration reference

Registering more models

The models in the example above are a starting point, not a fixed list. Any model enabled in the workspace can be registered, from any provider in the supported models catalog. Pi only sees models listed under models, so add one entry per model:

{
  "id": "<provider>/<model-name>",
  "name": "<label shown in Pi>",
  "reasoning": true,
  "input": ["text", "image"]
}

Pi reloads models.json each time /model opens, so models can be added mid-session without restarting.

Model fields

Field	Required	Description
`id`	Yes	AI Gateway model identifier in `provider/model-name` format. Sent verbatim as the `model` field.
`name`	No	Label shown in the Pi model picker. Defaults to `id`. Display only, with no effect on routing.
`reasoning`	No	Set to `true` for models that support extended thinking. Defaults to `false`.
`input`	No	Accepted input types. Include `"image"` for models that accept images. Defaults to `["text"]`.
`contextWindow`	No	Context window in tokens. Defaults to `128000`, which under-reports most AI Gateway models.
`maxTokens`	No	Maximum output tokens. Defaults to `16384`.

contextWindow and maxTokens fall back to Pi defaults that are smaller than the real limits of most routed models, which causes sessions to compact earlier than necessary and caps output length. Set both explicitly per model using the values in supported models.

Troubleshooting

Models do not appear in /model

Pi loads models.json regardless of credentials, then hides models that have no usable key. Confirm the apiKey value resolves: a literal key must be present in the file, and $ORQ_API_KEY must exist in the shell that launches Pi. Credentials resolve in this order: the --api-key flag, then auth.json, then environment variables, then the apiKey value in models.json.

Requests bypass the AI Gateway

A built-in Pi provider served the request. Run pi --list-models and confirm the target model is listed under the orq provider rather than openai, anthropic, or google. Unset the conflicting shell credentials and remove the matching entries from ~/.pi/agent/auth.json:

unset OPENAI_API_KEY ANTHROPIC_API_KEY GEMINI_API_KEY

No Traces appearing in Orq.ai

Confirm baseUrl is https://api.orq.ai/v3/router, api is openai-completions, and the status bar shows (orq) with the active model. Traces are recorded against the workspace and project that own the API key, not the workspace currently open in the UI. Traces are also ingested asynchronously, so reload the view before treating an empty result as a failure.

Edits to models.json have no effect

Reopen /model after saving, which reloads the file. A malformed file prevents the whole provider from loading, so validate it with jq . ~/.pi/agent/models.json.

Authentication errors

Confirm the key is a valid Orq.ai API key rather than an upstream provider key, and that it carries the permissions for the models in use.

Verification

Start a Pi session, select a registered model with /model, and send a prompt. The response appears in the session, the status bar shows (orq) with the active model, and the trace appears in Orq.ai Traces with the model identifier, for example anthropic/claude-sonnet-5.

AI Providers

Coding Assistants

Frameworks

Automations

Pi | AI Gateway

Prerequisites

Install Pi

Setup

Configuration reference

Registering more models

Model fields

Troubleshooting

Verification

​Prerequisites

​Install Pi

​Setup

​Configuration reference

​Registering more models

​Model fields

​Troubleshooting

​Verification

Prerequisites

Install Pi

Setup

Configuration reference

Registering more models

Model fields

Troubleshooting

Verification