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

# tokios-connector.json configuration reference

> Full reference for the Tokios Connector config file and CLI flags — ConnectorId, Token, Routes, Upstreams, logging, and running as a service.

The Tokios Connector reads its settings from a JSON config file. You pass the file with `--config`, and any setting can be overridden with a command-line flag at startup. The connector never reads environment variables, and it only ever forwards to the upstreams you define here — never to a URL supplied by the gateway.

> [!NOTE]
>
> Your `ConnectorId` and `Token` are issued by the Tokios console when you create a connector. The token is shown only once — paste it into your config file and store it somewhere safe.

Precedence:
`CLI flags`
›
`TOKIOS_* env vars`
›
`tokios-connector.json`
›
defaults

## The config file

A minimal config has a `Connector` section with your credentials and one local upstream:

```json tokios-connector.json theme={"theme":{"light":"github-light","dark":"css-variables"}}
{
  "Connector": {
    "ConnectorId": "con_your_connector_id",
    "Token": "ct-your-connector-token",
    "Models": ["gemma4:e4b"],
    "Upstream": {
      "BaseUrl": "http://127.0.0.1:11434/v1"
    }
  }
}
```

Start the connector pointing at that file:

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
tokios-connector --config tokios-connector.json
```

## `Connector` fields

**ConnectorId** `string` *required*

managed by pairing restart required

The connector's id from the console (e.g. `con_...`). Identifies this connector to the Tokios gateway.

**Token** `string` *required*

managed by pairing secret — redacted in logs

The connector token issued when you create the connector (e.g. `ct-...`), bound to your tenant. Shown only once in the console.

**ServerUrl** `string`

The `wss://` gateway endpoint the connector dials. Defaults to the hosted Tokios gateway, so you normally leave this unset. (Self-hosted deployments point it at their own server, e.g. `wss://your-server/connector/connect`.)

**ConcurrencyCap** `integer` (default: 8)

Maximum number of in-flight requests the connector forwards at once. Requests beyond the cap are rejected with `503 connector_busy` until a slot frees.

## Declaring what the connector serves

Pick **one** of two shapes — specifying both is rejected.

**Single upstream** — one local server serving one or more model ids:

```json tokios-connector.json theme={"theme":{"light":"github-light","dark":"css-variables"}}
"Connector": {
  "ConnectorId": "con_...",
  "Token": "ct-...",
  "Models": ["gemma4:e4b"],
  "Upstream": { "BaseUrl": "http://127.0.0.1:11434/v1" }
}
```

**Multiple upstreams** — route different model ids to different local servers:

```json tokios-connector.json theme={"theme":{"light":"github-light","dark":"css-variables"}}
"Connector": {
  "ConnectorId": "con_...",
  "Token": "ct-...",
  "Routes": [
    { "Model": "gemma4:e4b",    "UpstreamId": "ollama" },
    { "Model": "qwen2.5-coder", "UpstreamId": "lmstudio" }
  ],
  "Upstreams": {
    "ollama":   { "BaseUrl": "http://127.0.0.1:11434/v1" },
    "lmstudio": { "BaseUrl": "http://127.0.0.1:1234/v1" }
  }
}
```

The ids in `Models` / `Routes[].Model` are the model ids your local server uses — what you'd send it directly (e.g. `gemma4:e4b` in Ollama). You expose one under a public API name (e.g. `gemma-tunnel`) by registering a **deployment** in the console; that public name is what clients send in the `"model"` field, and the gateway rewrites it to the upstream id before forwarding it down the tunnel. See [Model Routing](https://docs.tokios.com/guides/model-routing.md).

## Upstream fields

Each upstream — the single `Upstream`, or each entry under `Upstreams` — accepts:

**BaseUrl** `string` *required*

required

The base URL of your model server, **including the `/v1` segment** — e.g. `http://127.0.0.1:11434/v1`. The connector appends the request path (`/chat/completions`) to it. Your server must expose an OpenAI-compatible Chat Completions API. See [Backends](https://docs.tokios.com/setup/supported-backends.md).

**AllowedHosts** `string[]`

Optional host pin. Empty (the default): the connector trusts the host in `BaseUrl` as-is — local and remote upstreams need no extra setting. Non-empty: the `BaseUrl` host must appear in the list, so a later `BaseUrl` edit that points somewhere else fails at startup instead of silently sending traffic (and the upstream's `ApiKey`) to the new host.

**AllowedPaths** `string[]`

Request paths the connector may forward. Defaults to `["/chat/completions"]`.

> [!NOTE]
>
> To reach a model on another machine on your network, point `BaseUrl` at it — for example `http://192.168.1.50:11434/v1`. No opt-in setting is needed: the connector forwards only to hosts named in its own config file, never to a URL supplied by the gateway. Older configs may still contain `AllowLan`; the connector ignores it.

### Authenticating to a remote upstream

To forward to a hosted, OpenAI-compatible provider instead of a local server, point `BaseUrl` at the provider and supply credentials on the upstream:

**ApiKey** `string`

The key injected into the upstream request.

**ApiKeyHeader** `string` (default: Authorization)

The header the key is sent in. Use `x-api-key` for Anthropic-style providers, `api-key` for Azure OpenAI.

**ApiKeyPrefix** `string` (default: Bearer )

Prefix prepended to the key. Set to an empty string for raw-key schemes (e.g. `x-api-key`, `api-key`).

**Headers** `object`

Static headers added to every upstream request.

**QueryParams** `object`

Static query-string parameters appended to the upstream URL (e.g. Azure OpenAI's `api-version`).

## Command-line flags

| Flag | Description |
| - | - |
| `--config <path>` | Path to the config file. A relative path is searched from the current directory upward, then next to the binary. If omitted, the connector looks for `appsettings.json`. A specified-but-missing file fails loudly. |
| `--version` | Print the connector version and exit. Aliases: `--ver`, `-v`. |

Any config value can also be overridden on the command line using its full key path:

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
tokios-connector --config tokios-connector.json --Logging:LogLevel:Default=Debug
```

> [!NOTE]
>
> There is no `--log-level` flag. Set verbosity through the `Logging` section (below) or the `--Logging:LogLevel:Default=...` override shown above.

## Logging

The connector always logs to the console. Control verbosity and turn on optional rolling daily files with a top-level `Logging` section — a sibling of `Connector`:

```json tokios-connector.json theme={"theme":{"light":"github-light","dark":"css-variables"}}
{
  "Logging": {
    "LogLevel": { "Default": "Information" },
    "Directory": "logs",
    "RetainedDays": 7
  },
  "Connector": {
    "ConnectorId": "con_...",
    "Token": "ct-...",
    "Models": ["gemma4:e4b"],
    "Upstream": { "BaseUrl": "http://127.0.0.1:11434/v1" }
  }
}
```

**Logging:LogLevel:Default** `string` (default: Information)

Verbosity: `Trace`, `Debug`, `Information`, `Warning`, or `Error`. Set to `Debug` to capture per-request routing, the `cid`, and upstream detail when troubleshooting.

**Logging:Directory** `string`

Turn on rolling daily log files in this directory (created if missing). Empty (the default) means console only. A **relative** path resolves next to the connector binary — not the working directory — so logs land predictably even when the connector is launched by double-click.

**Logging:RetainedDays** `integer` (default: 14)

Number of daily log files to keep.

This writes `logs/tokios-connector-YYYYMMDD.log`.

## Complete example

> [tab] macOS
>
> Config path: `~/Library/Application Support/tokios/tokios-connector.json`
>
> ```json theme={"theme":{"light":"github-light","dark":"css-variables"}}
> {
>   "Connector": {
>     "ConnectorId": "<generated-during-pairing>",
>     "Token": "<generated-during-pairing>",
>     "Models": ["gemma4:e4b"],
>     "Upstream": {
>       "BaseUrl": "http://127.0.0.1:11434/v1"
>     }
>   }
> }
> ```

> [tab] Linux
>
> Config path: `/etc/tokios/tokios-connector.json`
>
> ```json theme={"theme":{"light":"github-light","dark":"css-variables"}}
> {
>   "Connector": {
>     "ConnectorId": "<generated-during-pairing>",
>     "Token": "<generated-during-pairing>",
>     "Models": ["gemma4:e4b"],
>     "Upstream": {
>       "BaseUrl": "http://127.0.0.1:11434/v1"
>     }
>   }
> }
> ```

> [tab] Windows
>
> Config path: `%APPDATA%\tokios\tokios-connector.json`
>
> ```json theme={"theme":{"light":"github-light","dark":"css-variables"}}
> {
>   "Connector": {
>     "ConnectorId": "<generated-during-pairing>",
>     "Token": "<generated-during-pairing>",
>     "Models": ["gemma4:e4b"],
>     "Upstream": {
>       "BaseUrl": "http://127.0.0.1:11434/v1"
>     }
>   }
> }
> ```

## Running as a background service

> [!TIP]
>
> For development, running in a terminal window is fine. For always-on use, run the connector as a system service so it restarts automatically on reboot.

> [tab] macOS (launchd)
>
> Create a plist file at `~/Library/LaunchAgents/com.tokios.connector.plist`:
>
> ```xml ~/Library/LaunchAgents/com.tokios.connector.plist theme={"theme":{"light":"github-light","dark":"css-variables"}}
> <?xml version="1.0" encoding="UTF-8"?>
> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
>   "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
> <plist version="1.0">
> <dict>
>   <key>Label</key>
>   <string>com.tokios.connector</string>
>   <key>ProgramArguments</key>
>   <array>
>     <string>/usr/local/bin/tokios-connector</string>
>     <string>--config</string>
>     <string>/etc/tokios/tokios-connector.json</string>
>   </array>
>   <key>RunAtLoad</key>
>   <true/>
>   <key>KeepAlive</key>
>   <true/>
>   <key>StandardOutPath</key>
>   <string>/var/log/tokios-connector.log</string>
>   <key>StandardErrorPath</key>
>   <string>/var/log/tokios-connector.log</string>
> </dict>
> </plist>
> ```
>
> Load and start the service:
>
> ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
> launchctl load ~/Library/LaunchAgents/com.tokios.connector.plist
> launchctl start com.tokios.connector
> ```

> [tab] Linux (systemd)
>
> Create a unit file at `/etc/systemd/system/tokios-connector.service`:
>
> ```ini /etc/systemd/system/tokios-connector.service theme={"theme":{"light":"github-light","dark":"css-variables"}}
> [Unit]
> Description=Tokios Connector
> After=network.target
>
> [Service]
> ExecStart=/usr/local/bin/tokios-connector --config /etc/tokios/tokios-connector.json
> Restart=always
> RestartSec=5
> StandardOutput=journal
> StandardError=journal
>
> [Install]
> WantedBy=multi-user.target
> ```
>
> Enable and start the service:
>
> ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
> sudo systemctl daemon-reload
> sudo systemctl enable tokios-connector
> sudo systemctl start tokios-connector
> ```

> [tab] Windows (Service)
>
> On Windows, use [NSSM (Non-Sucking Service Manager)](https://nssm.cc/) or Task Scheduler to run the connector as a background service.
>
> **Using NSSM:**
>
> ```powershell theme={"theme":{"light":"github-light","dark":"css-variables"}}
> nssm install TokiosConnector "C:\Program Files\Tokios\tokios-connector.exe"
> nssm set TokiosConnector AppParameters "--config C:\ProgramData\Tokios\tokios-connector.json"
> nssm set TokiosConnector Start SERVICE_AUTO_START
> nssm start TokiosConnector
> ```
>
> **Using Task Scheduler:**
>
> Create a new task, set the trigger to **At startup**, and point the action at `tokios-connector.exe` with `--config <path>` as the argument. Enable **Run whether user is logged on or not** to keep it running in the background.

## Related errors

| Code | Meaning |
| - | - |
| E1401 | Invalid or revoked connector token |
| E1404 | Route points at an unknown upstream model |
| E1502 | Upstream unreachable — check `BaseUrl` includes `/v1` |

See [Troubleshooting](https://docs.tokios.com/reference/troubleshooting.md) for resolution steps.


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