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

# Pi setup

> Connect Pi to Pearl with a custom model provider.

## Before you start

Complete organization setup, make sure your account has inference credit, and create a key on the [API Keys page](https://platform.pearlresearch.ai/api-keys). Most coding agents need a tool-capable chat model; Aider's basic edit workflow does not require native tool calling. Image input and reasoning support depend on the model. These terminal examples use Bash or Zsh on macOS, Linux, or Windows through WSL.

Install Pi using its official quickstart. The installer adds \~/.pi/agent/bin to your shell profile, so open a new terminal before you run `pi --version`. The configuration below targets the models.json format documented by current Pi releases. [Installation instructions](https://pi.dev/docs/latest/quickstart).

```bash theme={null}
pi --version
```

## Get your connection settings

Open [Integrations](https://platform.pearlresearch.ai/integrations), select a model, then choose Pi. The screen uses your organization's region. The examples below use the public global endpoint; replace it with your regional endpoint and replace `YOUR_MODEL_ID` with the full model ID shown there. Choose one of the models listed for this integration.

Set your Pearl API key in the terminal where you run Pi:

```bash theme={null}
export PEARL_API_KEY="YOUR_PEARL_API_KEY"
```

## Configure Pi

Merge the pearl entry under providers in \~/.pi/agent/models.json. The API key uses environment interpolation. Pearl chat models support all three API formats. Choose Responses, Messages, or Chat Completions on the Integrations screen, then copy the matching configuration. Use one format for this provider entry and a model with tool calling.

```json ~/.pi/agent/models.json (merge providers) theme={null}
{
  "providers": {
    "pearl": {
      "baseUrl": "https://inference.pearlresearch.ai/v1",
      "api": "openai-completions",
      "apiKey": "${PEARL_API_KEY}",
      "authHeader": true,
      "models": [
        {
          "id": "YOUR_MODEL_ID",
          "name": "YOUR_MODEL_ID",
          "reasoning": true,
          "thinkingLevelMap": {
            "xhigh": "xhigh",
            "max": "max"
          },
          "input": [
            "text"
          ],
          "maxTokens": 8192,
          "compat": {
            "supportsStore": false,
            "thinkingFormat": "openrouter",
            "maxTokensField": "max_tokens",
            "supportsStrictMode": false
          }
        }
      ]
    }
  }
}
```

```bash Start Pi theme={null}
pi --provider pearl --model 'YOUR_MODEL_ID' --thinking high
```

## Choose another API format

Use exactly one provider configuration. Pearl chat models support all three API formats. Choose a format supported by your tool, and replace the provider entry when switching formats. Tool calling, reasoning, and image support vary by model.

**OpenAI Responses**

```json ~/.pi/agent/models.json (merge providers) theme={null}
{
  "providers": {
    "pearl": {
      "baseUrl": "https://inference.pearlresearch.ai/v1",
      "api": "openai-responses",
      "apiKey": "${PEARL_API_KEY}",
      "authHeader": true,
      "models": [
        {
          "id": "YOUR_MODEL_ID",
          "name": "YOUR_MODEL_ID",
          "reasoning": true,
          "thinkingLevelMap": {
            "xhigh": "xhigh",
            "max": "max"
          },
          "input": [
            "text"
          ],
          "maxTokens": 8192,
          "compat": {
            "supportsStrictMode": false
          }
        }
      ]
    }
  }
}
```

```bash Start Pi theme={null}
pi --provider pearl --model 'YOUR_MODEL_ID' --thinking high
```

**Anthropic Messages**

```json ~/.pi/agent/models.json (merge providers) theme={null}
{
  "providers": {
    "pearl": {
      "baseUrl": "https://inference.pearlresearch.ai",
      "api": "anthropic-messages",
      "apiKey": "${PEARL_API_KEY}",
      "models": [
        {
          "id": "YOUR_MODEL_ID",
          "name": "YOUR_MODEL_ID",
          "reasoning": true,
          "thinkingLevelMap": {
            "xhigh": "xhigh",
            "max": "max"
          },
          "input": [
            "text"
          ],
          "maxTokens": 8192,
          "compat": {
            "supportsStrictTools": false,
            "forceAdaptiveThinking": true
          }
        }
      ]
    }
  }
}
```

```bash Start Pi theme={null}
pi --provider pearl --model 'YOUR_MODEL_ID' --thinking high
```

## Start using Pi

Start Pi with the explicit Pearl provider and model. Opening /model reloads custom model configuration. Ask Pi to read a file and make a small edit, then follow up in the same conversation.

## Troubleshooting

A custom model is not selectable until Pi can resolve its credentials. Export PEARL\_API\_KEY in the same terminal that starts Pi. Reasoning is on in these examples. For Chat Completions, thinkingFormat openrouter sends Pearl's reasoning object instead of the rejected flat reasoning\_effort field. For Messages, forceAdaptiveThinking sends adaptive thinking with an effort, because Pearl rejects thinking budgets. The start command sets the level with `--thinking`; levels the model doesn't serve round up to the next one it does. thinkingLevelMap passes xhigh and max through unchanged, and on models that always reason it sends the lowest level for off, since turning thinking off returns 400.

* `401`: check the key and allow time for a newly created key to reach the inference gateway.
* `404`: copy the endpoint and exact model ID from Integrations. OpenAI base URLs end in `/v1`; the Anthropic SDK and Claude Code use the URL without that suffix.
* `402`: check your organization's credit and billing status.
* `429` or Anthropic `529`: respect retry instructions and reduce concurrency.
* For truncated output, check the output limit and reasoning budget. Increase limits only within the model's maximum output length.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.