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

# Troubleshoot connecting clients to Tokios

> Fix the four most common reasons a client can't connect to Tokios — wrong base URL, wrong model, offline connector, unsupported feature — and error codes.

Most client connection problems come down to one of four things: the **base URL** is missing (or has) `/v1` when your client expects the opposite, the `model` field isn't your registered **deployment** name, the connector for that deployment isn't online, or the model itself doesn't support what the client is asking for (like tool calling). Work through this page top to bottom before assuming something deeper is wrong.

## Which base URL does my client use?

Pick the base URL by the API shape your client speaks. The client itself appends the rest of the path (`/chat/completions`, `/responses`, or `/messages`) — you only set the root.

| Client style | Base URL | Examples |
| - | - | - |
| OpenAI style | `https://api.tokios.com/v1` | Codex, OpenAI SDKs, Cursor, Cline, Continue, Aider, Roo Code, LangChain, LlamaIndex, Vercel AI SDK, Pydantic AI |
| Anthropic style | `https://api.tokios.com` (no `/v1`) | Claude Code |

> [!TIP]
>
> If you're not sure which style a client uses, check whether it asks for `ANTHROPIC_BASE_URL` (or an Anthropic SDK) — that's the no-`/v1` case. Everything else that takes an OpenAI-style `base_url` or `OPENAI_BASE_URL` wants the `/v1` suffix.

## Works with curl but fails in my agent

If a plain `curl` request succeeds but the same call fails from inside a client, framework, or agent, check these in order:

> [accordion] The base URL includes the full request path
>
> Some clients want just the root (`https://api.tokios.com/v1`) and append `/chat/completions` themselves; others want the full path pasted in. If you copied a URL that already ends in `/chat/completions`, `/responses`, or `/messages` into a field that also appends its own path, you'll get a doubled or malformed path. Set the base URL to the root shown in the table above and let the client add the rest.

> [accordion] The client requires tool calling and the model doesn't support it
>
> Agent frameworks and coding assistants often send a `tools` array on every request, even for simple prompts. Tokios passes the `tools` structure straight through to your model, but the model itself has to support function calling — if it doesn't, the request can fail or the model can ignore the tools silently. Confirm the underlying model supports tool calling before debugging the client further.

> [accordion] The model name isn't the deployment name
>
> The `model` field must be the **public deployment name** you registered in the console's [Models](https://tokios.com/console/models) tab (for example, `gemma-tunnel`) — not the upstream model id your backend serves (for example, `gemma:7b`). A curl request with the correct deployment name will work while a client still configured with the backend's local id returns a `404`.

## What each error code means

| Status | Meaning | Fix |
| - | - | - |
| `400` | Malformed request body | Check the JSON shape against [API endpoints](https://docs.tokios.com/reference/api-endpoints.md) for that surface. |
| `401` | Missing or invalid API key | Confirm the `Authorization: Bearer sk-tok-…` header is present and the key hasn't been rotated or deleted in the **Keys** tab. |
| `403` | The key isn't allowed to use this model, or the account is suspended | Check the key's model-pattern scope in the **Keys** tab, or create a key scoped to include this deployment. |
| `404` | Model deployment not found | Verify the `model` value matches a registered deployment name exactly, including case. |
| `503` | Connector offline or at capacity (`connector_unavailable` / `connector_busy`) | Start the connector and confirm it shows **Online** in the **Connectors** tab; if it's `connector_busy`, requests exceeded the connector's `ConcurrencyCap`. |

## Confirm the tunnel independently

Before you keep debugging client-side config, isolate whether the problem is the client or the model/connector itself. Open the console's [Playground](https://tokios.com/console/playground) and send a test prompt to the same deployment — it runs against your signed-in session, so you don't need an API key. If the Playground works, the tunnel and model are fine and the issue is in your client's base URL, model value, or request shape. If the Playground also fails, the problem is upstream of the client — check the connector and deployment instead.

## Next steps

> [card] [Compatible clients](https://docs.tokios.com/guides/compatible-clients.md)
>
> Base URL and API key settings for each supported client, in one table.

> [card] [Claude Code](https://docs.tokios.com/guides/claude-code.md)
>
> Environment variables and model flag for Anthropic-style setup.

> [card] [SDKs & frameworks](https://docs.tokios.com/guides/frameworks.md)
>
> LangChain, LlamaIndex, Vercel AI SDK, and Pydantic AI configuration.

> [card] [API endpoints](https://docs.tokios.com/reference/api-endpoints.md)
>
> Full request and response schemas for every surface.


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