> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokios.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Tokios exposes private local models through https://api.tokios.com using an outbound-only connector tunnel.
> Use 'connector' for the local tokios-connector process.
> Use 'deployment' for the public model name in the API model field.
> Use 'upstream model id' for the model served by Ollama, llama.cpp, vLLM, LM Studio, or another local backend.
> API keys use the prefix sk-tok-. Connector tokens use the prefix ct-tok-.

# Use Pi with your own local model

> Add Tokios as an OpenAI-compatible provider in Pi's models.json so its terminal coding agent can reach a local model on Ollama, LM Studio, llama.cpp, or vLLM.

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](https://docs.tokios.com/setup/connector-install.md)
* A registered deployment — see [Register a model](https://docs.tokios.com/setup/register-model.md)
* A Tokios API key (`sk-tok-…`) — see [API keys](https://docs.tokios.com/setup/api-keys.md)
* 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:

```bash macOS / Linux theme={"theme":{"light":"github-light","dark":"css-variables"}}
curl https://api.tokios.com/v1/models \
  -H "Authorization: Bearer sk-tok-YOUR_KEY"
```

```powershell Windows theme={"theme":{"light":"github-light","dark":"css-variables"}}
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`.

> [!TIP]
>
> Run this even if your model already answers in the [Playground](https://tokios.com/console/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 |

```bash macOS / Linux theme={"theme":{"light":"github-light","dark":"css-variables"}}
~/.pi/agent/models.json
```

```powershell Windows theme={"theme":{"light":"github-light","dark":"css-variables"}}
C:\Users\<you>\.pi\agent\models.json
```

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

> [!WARNING]
>
> 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`).

```json ~/.pi/agent/models.json theme={"theme":{"light":"github-light","dark":"css-variables"}}
{
  "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:

```json ~/.pi/agent/models.json theme={"theme":{"light":"github-light","dark":"css-variables"}}
{
  "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"] }
      ]
    }
  }
}
```

> [!NOTE]
>
> 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.

> [!WARNING]
>
> `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:

```json theme={"theme":{"light":"github-light","dark":"css-variables"}}
{ "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`:

```json ~/.pi/agent/settings.json theme={"theme":{"light":"github-light","dark":"css-variables"}}
{
  "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.

```json theme={"theme":{"light":"github-light","dark":"css-variables"}}
"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](https://docs.tokios.com/guides/model-by-task.md) for guidance on matching a model to agentic coding work.

## Troubleshooting

> [accordion] 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.

> [accordion] 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](https://tokios.com/console/keys) tab. A working Playground session does not rule this out — the Playground doesn't use your API key.

> [accordion] 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.

> [accordion] 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](https://tokios.com/console/keys) tab.

> [accordion] 503 error
>
> The connector for that deployment is offline or at its concurrency cap. Check the [Connectors](https://tokios.com/console/connectors) tab — the connector needs to show as **Online**, and the machine running it needs to still be up and reachable.

> [accordion] 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.

## Next steps

> [card] [omp (oh-my-pi)](https://docs.tokios.com/guides/omp.md)
>
> Prefer the batteries-included fork? Wire up omp against Tokios the same way.

> [card] [Choose a model by task](https://docs.tokios.com/guides/model-by-task.md)
>
> Match a local model to agentic coding work before you commit it to Pi.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.