> ## 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 Goose with your own local model

> Add Tokios as a custom OpenAI-compatible provider in Goose so its coding agent can reach a local model on Ollama, LM Studio, or vLLM — reachable anywhere.

Goose is Block's open-source, on-machine coding agent. Goose doesn't have a built-in Tokios provider, but it supports custom providers through a JSON file, so you can point it at `https://api.tokios.com/v1` and reach any model behind your connector.

## Prerequisites

* A running Tokios connector paired with your local model — see [Connector install](https://docs.tokios.com/setup/connector-install.md)
* A registered model deployment name — 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)
* Goose installed

## Configure a custom provider

Create a custom provider file for Goose. Custom-provider config has changed across Goose releases, so confirm the exact JSON schema (field names, required vs. optional keys, and whether a `models` array or a different structure is expected) against your installed version.

> [tab] macOS/Linux
>
> Create a JSON file in `~/.config/goose/custom_providers/`:
>
> ```json tokios.json theme={"theme":{"light":"github-light","dark":"css-variables"}}
> {
>   "name": "tokios",
>   "display_name": "Tokios",
>   "engine": "openai",
>   "base_url": "https://api.tokios.com/v1",
>   "api_key_env": "TOKIOS_API_KEY",
>   "models": ["gemma-tunnel"]
> }
> ```

> [tab] Windows
>
> Create a JSON file in `%APPDATA%\Block\goose\config\custom_providers\`:
>
> ```json tokios.json theme={"theme":{"light":"github-light","dark":"css-variables"}}
> {
>   "name": "tokios",
>   "display_name": "Tokios",
>   "engine": "openai",
>   "base_url": "https://api.tokios.com/v1",
>   "api_key_env": "TOKIOS_API_KEY",
>   "models": ["gemma-tunnel"]
> }
> ```

The file names an **environment variable** rather than holding the key itself, so export it before starting Goose:

```bash macOS / Linux theme={"theme":{"light":"github-light","dark":"css-variables"}}
export TOKIOS_API_KEY=sk-tok-YOUR_KEY
```

```powershell Windows theme={"theme":{"light":"github-light","dark":"css-variables"}}
$env:TOKIOS_API_KEY = "sk-tok-YOUR_KEY"
```

> [!NOTE]
>
> Replace `gemma-tunnel` with the **public deployment name** you registered on the [Models](https://tokios.com/console/models) tab — not the local model id your backend (Ollama, llama.cpp, vLLM, or LM Studio) uses. Because `api_key_env` stores only the variable name, this file is safe to commit; the key never enters it.

> [!WARNING]
>
> If requests 404, check how your Goose release interprets `base_url`. Goose's own custom-provider example writes the **full endpoint path** (`.../v1/chat/completions`) rather than just the `/v1` root, and the two forms are not interchangeable — try `https://api.tokios.com/v1/chat/completions` if `https://api.tokios.com/v1` fails.

## Alternative: the built-in OpenAI provider

If you'd rather not add a provider file, Goose's built-in `openai` provider accepts a custom host. Goose persists these to `~/.config/goose/config.yaml`:

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
export GOOSE_PROVIDER=openai
export GOOSE_MODEL=gemma-tunnel
export OPENAI_HOST=https://api.tokios.com
export OPENAI_API_KEY=sk-tok-YOUR_KEY
```

`OPENAI_HOST` is the host root and `OPENAI_BASE_PATH` is the request path, which defaults to `v1/chat/completions` — the path Tokios serves, so you normally leave it unset.

### Alternative: environment variable

Instead of a custom provider file, you can point Goose's OpenAI-compatible client at Tokios with the `OPENAI_HOST` environment variable. Confirm against your installed version whether `OPENAI_HOST` expects the bare host or the full `/v1` path, and whether it requires pairing with `OPENAI_API_KEY` for authentication.

```sh theme={"theme":{"light":"github-light","dark":"css-variables"}}
export OPENAI_HOST="https://api.tokios.com/v1"
export OPENAI_API_KEY="sk-tok-YOUR_KEY"
```

> [!NOTE]
>
> Goose treats Anthropic as a separate first-party provider, and a generic custom Anthropic base URL isn't available yet (tracked as an open feature request: [block/goose#3777](https://github.com/block/goose/issues/3777)). Use the OpenAI-compatible provider slot above to reach Tokios.

## Pick a tool-capable model

Goose'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 Goose 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] 401 error
>
> The API key Goose sent is missing, malformed, or has been revoked. Confirm `api_key` (or `OPENAI_API_KEY`) holds the full `sk-tok-…` key with no extra whitespace, and check its status on the [Keys](https://tokios.com/console/keys) tab.

> [accordion] 404 error
>
> The model name in `models` doesn't match a registered deployment. Confirm it exactly matches the public name on the [Models](https://tokios.com/console/models) tab — not your Ollama, llama.cpp, vLLM, or LM Studio local model id.

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

## Next steps

> [card] [Quickstart](https://docs.tokios.com/quickstart.md)
>
> Set up your connector, register a model, and create an API key from scratch.

> [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 wire it into Goose.


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