> ## 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 omp (oh-my-pi) with your own local model

> Add Tokios as a custom OpenAI-compatible provider in omp's models.yml so its terminal coding agent can reach a local model on Ollama, LM Studio, or vLLM.

omp (**oh-my-pi**) is a batteries-included, open-source terminal coding agent — a fork of [Pi](https://docs.tokios.com/guides/pi.md) that adds LSP integration, DAP-driven debugging, subagent orchestration, and per-role model routing across 40+ providers. Like Pi, it reads its providers from a config file, so you can add Tokios as a custom provider, point `baseUrl` at `https://api.tokios.com/v1`, and reach 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)
* omp installed:

```bash macOS / Linux theme={"theme":{"light":"github-light","dark":"css-variables"}}
curl -fsSL https://omp.sh/install | sh
```

```powershell Windows theme={"theme":{"light":"github-light","dark":"css-variables"}}
irm https://omp.sh/install.ps1 | iex
```

## Find your deployment name

omp 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.yml`.

> [!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 omp keeps its config

omp reads 2 files from a dot-prefixed `.omp` directory in your home folder:

| File | Purpose |
| - | - |
| `.omp/agent/models.yml` | Providers, and the models each provider serves |
| `.omp/agent/settings.yml` | Which model each role uses by default |

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

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

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

> [!WARNING]
>
> The directory is `.omp`, with a leading dot. omp does not read a file created at `omp/agent/models.yml` — it starts normally, and your provider simply never appears in `/model`.

## Configure a custom provider

Paste this into `models.yml` and replace the 2 placeholder values. It is a complete file, not a fragment:

```yaml models.yml 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 under `models` for each:

```yaml models.yml 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.yml` with a real key into version control.

> [!WARNING]
>
> `baseUrl` must include `/v1`, with no trailing slash. omp'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.

omp's config schema can shift between releases, so confirm the exact key names against your installed version (see `omp.sh/docs`). Start with the minimal block above — once omp lists your model under `/model`, add the optional fields below.

### Route a role to your model (optional)

omp maps named roles to models, each with an optional fallback chain. Point a role at your Tokios provider in `settings.yml` using `provider/model` syntax:

```yaml settings.yml theme={"theme":{"light":"github-light","dark":"css-variables"}}
modelRoles:
  default: tokios/gemma-tunnel
```

Otherwise, choose the provider and model at runtime with the `/model` command inside omp's TUI.

> [!TIP]
>
> Because roles are written as `provider/model`, a short, lowercase, hyphenated deployment name keeps this line unambiguous — the same naming [Register a model](https://docs.tokios.com/setup/register-model.md) recommends. If a deployment is registered under a name that itself contains a `/`, prefer selecting it with `/model` rather than pinning it to a role.

### Match the context window (optional)

omp 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 omp the real number:

```yaml theme={"theme":{"light":"github-light","dark":"css-variables"}}
      - id: gemma-tunnel
        input: [text]
        contextWindow: 32768
```

Set it too high and omp 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 omp starts sending whole files.

## Prefer the Anthropic surface? (optional)

omp can also speak 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.

```yaml theme={"theme":{"light":"github-light","dark":"css-variables"}}
    api: anthropic-messages
    baseUrl: https://api.tokios.com
```

## Pick a tool-capable model

omp'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 omp 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
>
> omp isn't reading your file. Confirm it sits at `~/.omp/agent/models.yml` — the directory is `.omp`, with a leading dot, and on Windows that resolves to `C:\Users\<you>\.omp\agent\models.yml`. Also confirm the file is valid YAML: `providers` is a mapping keyed by provider name, and `models` is a list.

> [accordion] 401 error
>
> The API key omp 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
>
> omp 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] [Pi](https://docs.tokios.com/guides/pi.md)
>
> omp is a fork of Pi — the upstream agent connects to 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 omp.


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