Use Poolside models in Pi

Watch the setup video

Prerequisites

You have Pi installed. Run pi --version to confirm the installation. For other installation options, including npm and Windows, see the Pi Quickstart.
You have one of the following:
- A Poolside Platform API key. To create one, go to platform.poolside.ai.
- The base URL for your self-managed model endpoint, and its API key if the endpoint requires one.
- An OpenRouter API key with access to Poolside models. To create one, go to OpenRouter API keys.

Steps

Poolside Platform
Self-managed Poolside inference
OpenRouter

Pi finds custom providers in ~/.pi/agent/models.json.

Make your Poolside Platform API key available as an environment variable. Add it to your shell profile.
export POOLSIDE_API_KEY="<api-key>"

Create or open ~/.pi/agent/models.json and add Poolside as a provider. To find model IDs for your access method, see List available models.

~/.pi/agent/models.json

{
  "providers": {
    "poolside": {
      "baseUrl": "https://inference.poolside.ai/v1",
      "api": "openai-completions",
      "apiKey": "$POOLSIDE_API_KEY",
      "models": [
        {
          "id": "<poolside-model-id>",
          "name": "Poolside model",
          "reasoning": <supports-reasoning>,
          "contextWindow": <context-window>,
          "maxTokens": <max-tokens>
        }
      ]
    }
  }
}

Replace <supports-reasoning>, <context-window>, and <max-tokens> with the values for the model you selected. See Supported models and Custom Models.

In your terminal, run pi.
pi
Run /model.
/model
Select the Poolside model you added.
Send a codebase question to confirm Pi responds with the selected Poolside model.

If you run Poolside model inference on your own infrastructure, use the model’s OpenAI-compatible endpoint at https://<model-hostname>/v1. Use the API key configured for the endpoint, if it requires one.

Pi finds custom providers in ~/.pi/agent/models.json.

Make the API key for your model endpoint available as an environment variable in your shell profile. If the endpoint does not validate API keys, use any non-empty value, such as local-test.
export POOLSIDE_API_KEY="<api-key>"

Create or open ~/.pi/agent/models.json and add Poolside as a provider. To find model IDs for your access method, see List available models.

~/.pi/agent/models.json

{
  "providers": {
    "poolside": {
      "baseUrl": "https://<model-hostname>/v1",
      "api": "openai-completions",
      "apiKey": "$POOLSIDE_API_KEY",
      "models": [
        {
          "id": "<poolside-model-id>",
          "name": "Poolside model",
          "reasoning": <supports-reasoning>,
          "contextWindow": <context-window>,
          "maxTokens": <max-tokens>
        }
      ]
    }
  }
}

Replace <supports-reasoning>, <context-window>, and <max-tokens> with the values configured for your model. Reasoning support depends on the deployed model and serving configuration. See Custom Models.

In your terminal, run pi.
pi
Run /model.
/model
Select the Poolside model you added.
Send a codebase question to confirm Pi responds with the selected Poolside model.

In your terminal, run pi.
pi
Run /login.
/login
Select OpenRouter.
Select Sign in with OpenRouter, then complete the OAuth authorization flow in your browser. This creates a user-controlled API key billed through your OpenRouter account. To use an existing API key instead, select Use an API key and paste the key.
Run /model.
/model
Search for a Poolside model served through OpenRouter. OpenRouter may offer free and paid Poolside models. To see current availability, see Poolside models on OpenRouter.
Select the model you want to use. Pi ships with a generated model snapshot, so recently released models may not appear in /model on older Pi versions. To add a model yourself, see Custom Models in the Pi documentation.
Send a codebase question to confirm Pi responds with the selected Poolside model.

​Watch the setup video

​Prerequisites

​Steps

​Related resources

Watch the setup video

Prerequisites

Steps

Related resources