Skip to main content

Before you start

Complete organization setup, make sure your account has inference credit, and create a key on the API Keys page. 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.

Get your connection settings

Open 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:

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.
~/.pi/agent/models.json (merge providers)
Start Pi

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
~/.pi/agent/models.json (merge providers)
Start Pi
Anthropic Messages
~/.pi/agent/models.json (merge providers)
Start Pi

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.