models.json. This guide uses BetterToken: set an API key, match the Base URL to the protocol, and specify a Model ID. For another service, use its URL, credentials, and model IDs.
Key settings
Prerequisites
- Node.js 22.19 or newer.
- Create a BetterToken API Key and choose a model with tool calling from the model plaza.
- On native Windows, install Git for Windows for Pi’s Bash tool, or run Pi inside WSL.
Install
Use Pi’s current official npm installation command:Manual setup
Set the API key
In the terminal that will start Pi, replaceYOUR_API_KEY with your key:
- macOS / Linux
- Windows PowerShell
Get models and generate configuration
Click Get model list to fetch BetterToken’s current public catalog without entering an API key. Choose an API and models with tool calling, then copy a Model ID or download a generatedmodels.json.
If models.json already exists, merge the generated bettertoken entry into your current configuration instead of replacing the file. The configuration uses the $BETTERTOKEN_API_KEY variable set above; add any other model-specific settings you need manually.
Pi supports several protocols; choose one supported by both your model and endpoint. For this setup, we recommend Anthropic Messages for Claude, Responses for GPT when supported by the endpoint, and Chat Completions for other OpenAI-compatible models. The picker defaults to Chat Completions and filters by the APIs declared in the public catalog. If Responses does not list your model, use the manual example below for models with confirmed Responses support.
Add the URL and model
Create~/.pi/agent/models.json. On Windows, the default path is %USERPROFILE%\.pi\agent\models.json. If the file exists, merge the bettertoken entry into its existing providers object.
As an alternative to the generated configuration, fill in this Responses API example manually. Replace YOUR_MODEL_ID with a model plaza ID; keep $BETTERTOKEN_API_KEY as the environment-variable reference:
baseUrl and api using a matching pair:
Choose an API that supports tool calling for your model. For example, GPT-6.1 Sol uses Responses. Keep the Base URL as shown; Pi appends the request path.
Start Pi
From your project directory, use the Model ID you configured:Verify the connection
Runpi --list-models and confirm that bettertoken and your model appear. Then start Pi and send:
PI_OK, try a small read-only task to verify tool calling.
Switch models
Add model entries to themodels array, then run /model in Pi. Pi reloads models.json. Select a model and press Ctrl+S to save it as the default for new sessions. Use different local names for endpoints with different protocols, each with its own api and baseUrl.
Common errors
Advanced setup
For images, reasoning levels, or longer context, setinput, reasoning, contextWindow, and maxTokens according to the model’s actual capabilities. See the model selection guide.
Technical details
providers and --provider are Pi client configuration fields; bettertoken is the local name used here. Pi checks a CLI --api-key first, then saved auth.json credentials, then apiKey in models.json. If that local name has old saved credentials, remove the corresponding entry through /logout in Pi before reconnecting.