Use Pi with your own local model

Pi is an open-source, BYOK (“bring your own key”) terminal coding agent from earendil-works. It speaks the OpenAI chat-completions protocol and reads its providers from a JSON config file, so you can add Tokios as a custom provider, point baseUrl at https://api.tokios.com/v1, and drive any model behind your connector — without that model’s port ever being exposed.

Prerequisites

A running Tokios connector paired with your local model — see Connector install
A registered deployment — see Register a model
A Tokios API key (sk-tok-…) — see API keys
Pi installed — npm install -g @earendil-works/pi-coding-agent

Find your deployment name

Pi sends the deployment name — the public name you registered in the console — not the upstream model id your local backend uses. The 2 are often different strings, and confusing them is the most common cause of a 404. List the deployments your API key can reach:

curl https://api.tokios.com/v1/models \
  -H "Authorization: Bearer sk-tok-YOUR_KEY"

curl.exe https://api.tokios.com/v1/models `
  -H "Authorization: Bearer sk-tok-YOUR_KEY"

Every id in the response is a value you can use in models.json.

Run this even if your model already answers in the Playground. The Playground authenticates with your signed-in browser session, so a successful test there does not prove your sk-tok-… key is valid or scoped to that deployment. GET /v1/models is the first call that exercises the key itself.

Where Pi keeps its config

Pi reads 2 files from a dot-prefixed .pi directory in your home folder:

File	Purpose
`.pi/agent/models.json`	Providers, and the models each provider serves
`.pi/agent/settings.json`	Default provider and model

~/.pi/agent/models.json

C:\Users\<you>\.pi\agent\models.json

Create the directory and the file if they aren’t there yet.

The directory is .pi, with a leading dot. Pi does not read a file created at pi/agent/models.json — it starts normally, and your provider simply never appears in /model.

Configure a custom provider

Paste this into models.json and replace the 2 placeholder values. It is a complete file, not a fragment. Pi’s config schema can shift between releases, so confirm the exact key names against your installed version (see pi.dev/docs).

~/.pi/agent/models.json

{
  "providers": {
    "tokios": {
      "baseUrl": "https://api.tokios.com/v1",
      "api": "openai-completions",
      "apiKey": "sk-tok-YOUR_KEY",
      "models": [
        {
          "id": "gemma-tunnel",
          "input": ["text"]
        }
      ]
    }
  }
}

One provider block can serve every deployment on your account. Add an entry to the models array for each:

~/.pi/agent/models.json

{
  "providers": {
    "tokios": {
      "baseUrl": "https://api.tokios.com/v1",
      "api": "openai-completions",
      "apiKey": "sk-tok-YOUR_KEY",
      "models": [
        { "id": "gemma-tunnel", "input": ["text"] },
        { "id": "qwen3-coder-tunnel", "input": ["text"] }
      ]
    }
  }
}

Replace gemma-tunnel with a deployment name from GET /v1/models — not the upstream model id your backend (Ollama, llama.cpp, vLLM, or LM Studio) serves, and not the Routes[].Model value in your connector config, which is the upstream id. Replace sk-tok-YOUR_KEY with your own key, and avoid committing models.json with a real key into version control.

baseUrl must include /v1, with no trailing slash. Pi’s openai-completions provider builds request paths relative to this URL, so https://api.tokios.com misses the Tokios API surface and https://api.tokios.com/v1/ can produce a doubled separator.

Match the context window (optional)

Pi sizes its prompts from the model’s context window. Ollama, llama.cpp, LM Studio, and vLLM each serve the context length the model was loaded with, not the model’s theoretical maximum, so tell Pi the real number:

{ "id": "gemma-tunnel", "input": ["text"], "contextWindow": 32768 }

Set it too high and Pi packs a prompt your local server rejects — an error that arrives through Tokios but originates on your own machine. Short prompts hide the mismatch, so it typically appears only once Pi starts sending whole files. Confirm the key name against your installed version.

Make it the default (optional)

To launch Pi straight onto your Tokios deployment instead of picking it each session, set a default in ~/.pi/agent/settings.json:

~/.pi/agent/settings.json

{
  "defaultProvider": "tokios",
  "defaultModel": "gemma-tunnel"
}

Otherwise, choose the provider and model at runtime with the /model command inside Pi’s TUI.

Prefer the Anthropic surface? (optional)

Pi also speaks the Anthropic messages protocol. To route through Tokios’s Anthropic surface instead, set api to anthropic-messages and drop the /v1 from baseUrl — Anthropic-style clients use the root base. Confirm the exact api value your Pi version expects.

"api": "anthropic-messages",
"baseUrl": "https://api.tokios.com"

Pick a tool-capable model

Pi’s agent relies on tool calling to read files, run commands, and edit code. Not every local model handles tool calls reliably — pick a deployment backed by a model with strong tool-calling support before you rely on Pi for real edits. See Choose a model by task for guidance on matching a model to agentic coding work.

Troubleshooting

Tokios doesn't appear in /model

Pi isn’t reading your file. Confirm it sits at ~/.pi/agent/models.json — the directory is .pi, with a leading dot, and on Windows that resolves to C:\Users\<you>\.pi\agent\models.json. Also confirm the file is valid JSON, with providers as an object keyed by provider name and models as an array.

401 error

The API key Pi sent is missing, malformed, or has been revoked. Confirm apiKey holds the full sk-tok-… key with no extra whitespace, and check its status on the Keys tab. A working Playground session does not rule this out — the Playground doesn’t use your API key.

404 error

The model id under models doesn’t match a registered deployment. Run GET /v1/models and copy an id from the response exactly. A common near-miss is using the upstream model id from your connector’s Routes[].Model instead of the deployment name.

403 error

The key exists but isn’t scoped to the deployment you configured, or your account is suspended. Check the key’s model patterns on the Keys tab.

503 error

The connector for that deployment is offline or at its concurrency cap. Check the Connectors tab — the connector needs to show as Online, and the machine running it needs to still be up and reachable.

Long sessions fail, short ones work

Pi is sending more context than your backend loaded. Set contextWindow on the model entry to the context length your server is actually serving, and confirm the load-time setting in Ollama, llama.cpp, LM Studio, or vLLM.

Hardware & fit

Serve & connect your runtime

Connect a client or app

Compare

Use Pi with your own local model

Prerequisites

Find your deployment name

Where Pi keeps its config

Configure a custom provider

Match the context window (optional)

Make it the default (optional)

Prefer the Anthropic surface? (optional)

Pick a tool-capable model

Troubleshooting

Next steps

omp (oh-my-pi)

Choose a model by task

​Prerequisites

​Find your deployment name

​Where Pi keeps its config

​Configure a custom provider

​Match the context window (optional)

​Make it the default (optional)

​Prefer the Anthropic surface? (optional)

​Pick a tool-capable model

​Troubleshooting

​Next steps

omp (oh-my-pi)

Choose a model by task

Prerequisites

Find your deployment name

Where Pi keeps its config

Configure a custom provider

Match the context window (optional)

Make it the default (optional)

Prefer the Anthropic surface? (optional)

Pick a tool-capable model

Troubleshooting

Next steps