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

# Install and pair the Tokios Connector

> Run the Tokios Connector next to your model and pair it with a one-time claim code via WebSocket — no inbound ports, public IP, or hand-edited tokens.

The Tokios Connector is a small console app you run on the machine next to your model. It dials out to Tokios over a single WebSocket and forwards requests to your local model — no inbound ports, no public IP, no firewall changes.

You install and pair it from the console's **[Setup wizard](https://tokios.com/console/setup)** with a one-time **claim code**. For the basic path you don't hand-edit a config file — the connector receives its token securely over the tunnel after you approve the device.

## 1. Get a claim code

In the console's **Setup** tab, click **Start pairing** (step 1). Tokios shows a claim code like `TKS-XXXX-XXXX`, valid for about 15 minutes. Keep the tab open.

## 2. Install and run the connector

On the machine next to your model, run the one-liner the console shows for your OS.

> [tab] Windows
>
> Windows 10 & 11 (x64). In PowerShell:
>
> ```powershell theme={"theme":{"light":"github-light","dark":"css-variables"}}
> irm https://tokios.com/downloads/install/windows | iex; tokios-install -Code 'TKS-XXXX-XXXX'
> ```

> [tab] macOS
>
> Apple Silicon (arm64). Copy the **macOS** one-liner shown in the Setup tab and run it in your terminal — it embeds your claim code.

> [tab] Linux
>
> Linux (x64). Copy the **Linux** one-liner shown in the Setup tab and run it in your terminal — it embeds your claim code.

Already have `tokios-connector` installed? Skip the installer and pass the claim code directly:

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
tokios-connector TKS-XXXX-XXXX
```

## 3. Approve the device

The connector dials out and appears in the console. In the **Setup** tab (or the [Connectors](https://tokios.com/console/connectors) tab), **approve** the device. Tokios then delivers the connector's token over the tunnel — it is never shown on screen or pasted into a file.

> [!NOTE]
>
> The connector only dials out; it never listens on a port, so your firewall needs no inbound rules.

Once it's connected, [register your model](https://docs.tokios.com/setup/register-model.md) and [create an API key](https://docs.tokios.com/setup/api-keys.md).

## Advanced: expose multiple models with a config file

To serve several models through one connector, run the connector with a JSON config that defines each upstream instead of pairing a single model. See [Connector Config](https://docs.tokios.com/reference/connector-config.md).

## What the installer changes on your machine

* **Install directory.** The connector binary and its `tokios-connector.json` live together in `~/.tokios/connector` (macOS and Linux) or `%LOCALAPPDATA%\Tokios\connector` (Windows). Pass `--dir` / `-InstallDir` to choose another folder.
* **PATH.** On macOS and Linux the installer symlinks the binary into `~/.local/bin` and, if that folder is not on your `PATH`, appends 1 line marked `# tokios-connector PATH` to your shell profile (`.zshrc`, `.bashrc`, or `.profile`). It never adds the line twice, prints what it did, and the line stays on uninstall because other tools may use the same folder. To undo, delete that line. On Windows it adds the default install folder to your user `Path`; `tokios-install -Uninstall` removes it. Pass `--no-path` / `-NoPath` to skip all of this.
* **Nothing else.** No system services, no `sudo`, no firewall rules.

## Run the connector at boot

The installer starts the connector in the foreground, or in the background with `--detach` / `-Detach`. Neither survives a reboot. To keep your model reachable after a restart, run the connector under your platform's service manager. The connector allows 1 running instance per install directory, so stop a detached process first:

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
kill $(cat ~/.tokios/connector/tokios-connector.pid)
```

> [tab] Linux (systemd user service)
>
> ```ini ~/.config/systemd/user/tokios-connector.service theme={"theme":{"light":"github-light","dark":"css-variables"}}
> [Unit]
> Description=Tokios connector
> After=network-online.target
> Wants=network-online.target
>
> [Service]
> ExecStart=%h/.tokios/connector/tokios-connector --config %h/.tokios/connector/tokios-connector.json
> Restart=on-failure
> RestartSec=5
>
> [Install]
> WantedBy=default.target
> ```
>
> ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
> systemctl --user daemon-reload
> systemctl --user enable --now tokios-connector
> loginctl enable-linger "$USER"   # start at boot even when you are not logged in
> journalctl --user -u tokios-connector -f
> ```

> [tab] macOS (launchd)
>
> ```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>/Users/YOU/.tokios/connector/tokios-connector</string>
>     <string>--config</string>
>     <string>/Users/YOU/.tokios/connector/tokios-connector.json</string>
>   </array>
>   <key>RunAtLoad</key><true/>
>   <key>KeepAlive</key><true/>
>   <key>StandardOutPath</key><string>/Users/YOU/.tokios/connector/tokios-connector-stdout.log</string>
>   <key>StandardErrorPath</key><string>/Users/YOU/.tokios/connector/tokios-connector-stderr.log</string>
> </dict></plist>
> ```
>
> ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
> launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.tokios.connector.plist
> ```
>
> Replace `YOU` with your user name; launchd does not expand `~`.

> [tab] Windows (Task Scheduler)
>
> A Windows service installer is on the roadmap. Until then, a logon task keeps the connector running for your account:
>
> ```powershell theme={"theme":{"light":"github-light","dark":"css-variables"}}
> $bin = Join-Path $env:LOCALAPPDATA 'Tokios\connector\tokios-connector.exe'
> $cfg = Join-Path $env:LOCALAPPDATA 'Tokios\connector\tokios-connector.json'
> schtasks /Create /TN TokiosConnector /SC ONLOGON /RL LIMITED /TR "`"$bin`" --config `"$cfg`"" /F
> schtasks /Run /TN TokiosConnector
> ```

The connector keeps its pairing in `tokios-connector.json`, so a service start after a reboot reconnects without a new claim code.


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