Use Pi with Models Hub: models.json Custom Provider

Edit Pi (pi-mono)'s ~/.pi/agent/models.json to add Models Hub as a custom OpenAI-compatible provider, with verification and error troubleshooting.

Pi (package name pi-mono, CLI command pi) is a minimal, highly extensible terminal coding framework with TypeScript extensions, skills, and prompt templates, configured through ~/.pi/agent/models.json for custom model providers. Add Models Hub there, and every chat and code edit inside pi uses your Models Hub balance for the model you choose. This page covers the connection only, not how to use Pi itself.

Three things you need

A Models Hub API key, the base URL https://modelsok.com/v1, and a model name. There's no one-click setup — Pi isn't one of the targets the Models Hub CLI supports.

Prerequisites

Pi installed. Run npm install -g @earendil-works/pi-coding-agent; pi --version should print a version afterward. See the GitHub repository for details.
A Models Hub API key, created on the Tokens page. The token's group must have access to the models you plan to use.

Recommended models

Use case	Model	Pricing	Live status
Everyday coding	`claude-sonnet-4-6`	Price	Availability and latency
Harder reasoning and long tasks	`gpt-5.5`	Price	Availability and latency
Cheap and fast for small edits	`gpt-5.4-mini`	Price	Availability and latency

Model names are authoritative on the pricing page.

Setup

Step 1 — Set the environment variable

export MODELSOK_API_KEY="your-models-hub-api-key"

Step 2 — Edit models.json

Create or edit ~/.pi/agent/models.json:

{
  "providers": {
    "modelsok": {
      "baseUrl": "https://modelsok.com/v1",
      "api": "openai-completions",
      "apiKey": "$MODELSOK_API_KEY",
      "models": [
        {
          "id": "claude-sonnet-4-6",
          "name": "Claude Sonnet 4.6",
          "reasoning": true,
          "input": ["text", "image"],
          "contextWindow": 200000,
          "maxTokens": 128000
        },
        {
          "id": "gpt-5.4-mini",
          "name": "GPT-5.4 Mini",
          "contextWindow": 128000,
          "maxTokens": 16384
        }
      ]
    }
  }
}

Key fields

Field	Description
`baseUrl`	The base URL, ending in `/v1`
`api`	Protocol type; `openai-completions` for the OpenAI-compatible protocol — Pi also supports `anthropic-messages` and others
`apiKey`	References an environment variable with `$VAR_NAME` syntax, avoiding a hardcoded key in the file
`models[].id`	Must exactly match the model name in the Models Hub console
`models[].reasoning`	Marks whether the model supports reasoning; omit for non-reasoning models

models replaces the whole list

Once you set a models array for a provider, it replaces all of that provider's built-in models rather than appending to them. List any models you want to keep in the same array.

Verify

Launch Pi and type /model to open the model picker — it reloads models.json every time you open it. Pick a model under the modelsok provider and send a test message; a normal reply means you're connected. Then open Usage logs in the Models Hub console; a request under your configured model name appears within seconds.

Common errors

Symptom	Cause	Fix
No models under `modelsok` in `/model`	`~/.pi/agent/models.json` isn't valid JSON, or the path is wrong	Run `cat ~/.pi/agent/models.json` to check the file and confirm it's valid JSON
`401 Unauthorized`	`MODELSOK_API_KEY` isn't exported in the current shell	Check the environment variable, reopen the terminal, and retry
Model not found	`models[].id` doesn't match the Models Hub console	Check the name on the pricing page
Config changes have no effect	Pi only rereads the file when you open `/model`	Reopen the model picker
Other built-in models disappeared	The `models` array replaced them instead of appending	Include the models you want to keep in the same array

FAQ

How is it billed? Per input and output token actually consumed, at the price on each model's pricing page; every request is itemized in usage logs.

How is this different from using the official APIs directly? Pi sends requests to the Models Hub gateway over the openai-completions protocol — you don't need a separate account with each vendor, and one key covers every model.

How do I switch models? Type /model inside Pi to open the picker and select your target model; after editing models.json, reopening the picker picks up the change.

CLI one-command setup: Claude Code, Codex, Gemini CLI and OpenClaw support one-click configuration
Model pricing and model status
Oh My Pi setup, Crush setup

Use Pi with Models Hub: models.json Custom Provider

On this page