> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orq.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Pi | AI Gateway

> Route Orq.ai AI Gateway models through the Pi coding agent by registering Orq.ai as a custom provider in a single models.json file.

[Pi](https://pi.dev/) 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](/docs/ai-studio/organization/api-keys)

### Install Pi

<Tabs>
  <Tab title="Install script" icon="terminal">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    curl -fsSL https://pi.dev/install.sh | sh
    ```
  </Tab>

  <Tab title="npm" icon="cubes">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    npm install -g --ignore-scripts @earendil-works/pi-coding-agent
    ```
  </Tab>
</Tabs>

Confirm the install with `pi --version`.

## Setup

<Steps>
  <Step title="Register Orq.ai in models.json">
    Create `~/.pi/agent/models.json` and register **Orq.ai** as a custom provider:

    ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      "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](https://my.orq.ai/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.
  </Step>

  <Step title="Start Pi and select a model">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    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`.
  </Step>
</Steps>

<Warning>
  **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.
</Warning>

## 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](/docs/ai-studio/ai-gateway/supported-models) catalog. **Pi** only sees models listed under `models`, so add one entry per model:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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`.                                                          |

<Note>
  `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](/docs/ai-studio/ai-gateway/supported-models).
</Note>

## Troubleshooting

<AccordionGroup>
  <Accordion title="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`.
  </Accordion>

  <Accordion title="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`:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    unset OPENAI_API_KEY ANTHROPIC_API_KEY GEMINI_API_KEY
    ```
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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`.
  </Accordion>

  <Accordion title="Authentication errors">
    Confirm the key is a valid **Orq.ai** [API key](/docs/ai-studio/organization/api-keys) rather than an upstream provider key, and that it carries the permissions for the models in use.
  </Accordion>
</AccordionGroup>

## 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](/docs/ai-studio/observability/traces) with the model identifier, for example `anthropic/claude-sonnet-5`.