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

# Let a coding agent set up Tokios for you

> Hand Claude Code, Codex, or any coding agent an automation token and this page. It pairs the connector, publishes your model, mints an API key, and verifies the path unattended.

This page has 2 readers. The first section is for you. Everything from [Instructions for the agent](#instructions-for-the-agent) onward is written for the agent to read and execute.

> [!NOTE]
>
> **If you are an agent:** fetch the raw markdown of this page with your shell, not a browser tool, so commands and JSON shapes reach you verbatim:
>
> ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
> curl -fsSL https://docs.tokios.com/guides/agent-setup.md
> ```
>
> Then follow [Instructions for the agent](#instructions-for-the-agent). Every page on this site is available as markdown by appending `.md` to its URL, and the whole site is in `https://docs.tokios.com/llms-full.txt`.

## Before you start

**1. Mint an automation token**

In the dashboard, open **[Settings](https://tokios.com/console/settings)**, then **Automation tokens**, then **Create token**. Use the **Setup** preset and a **1 hour** expiry. Copy the token once. See [Automation tokens](/setup/automation-tokens.md).

**2. Run the agent on the machine that serves your model**

The agent has to run the connector install command on that machine. Make sure Ollama, LM Studio, llama.cpp, or vLLM is already running there on its default port.

**3. Put the token in a shell variable**

Set the variable, then start the agent from the same shell so the secret never enters the conversation.

**Windows PowerShell**

```powershell theme={"theme":{"light":"github-light","dark":"css-variables"}}
$env:TOKIOS_CONSOLE="https://tokios.com"
$env:TOKIOS_TOKEN="at-tok-YOUR_TOKEN"
claude
```

**Windows CMD**

```cmd theme={"theme":{"light":"github-light","dark":"css-variables"}}
set TOKIOS_CONSOLE=https://tokios.com
set TOKIOS_TOKEN=at-tok-YOUR_TOKEN
claude
```

**macOS & Linux**

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
export TOKIOS_CONSOLE=https://tokios.com
export TOKIOS_TOKEN=at-tok-YOUR_TOKEN
claude
```

**4. Send the agent 1 message**

```text theme={"theme":{"light":"github-light","dark":"css-variables"}}
Read https://docs.tokios.com/guides/agent-setup and follow it. The console base URL is in the TOKIOS_CONSOLE variable and the automation token is in TOKIOS_TOKEN. Never print the token. My model server is Ollama on this machine. When you are done, give me the final report described on that page.
```

Replace `Ollama` with your backend. For Codex, the same message works. Add "Make the connector start at boot." if you want the agent to install a service; otherwise it only tells you that the connector will not survive a reboot.

While it runs, watch the **Connectors** tab: a pending device appears, then turns active with announced models. Rows the agent creates carry a **via token** badge. When the agent reports back, revoke the token in **Settings**.

> [!NOTE]
>
> Coding agents refuse to pipe a downloaded script into a shell, so the agent does not use the install one-liner. It downloads the connector binary through the gateway, verifies the checksum, and starts it itself. If your agent stops and asks about a blocked installer command, point it back at this page.

## Instructions for the agent

You are setting up a Tokios workspace unattended: pair the connector on this machine, publish the local model, mint an API key for coding clients, and verify the whole path. You act through the workspace's management API with 1 credential, an automation token.

### What you have

* `TOKIOS_CONSOLE`: the console base URL, normally `https://tokios.com`. Every call below is `TOKIOS_CONSOLE` + `/account/...`.
* `TOKIOS_TOKEN`: the automation token, `at-tok-…`. Send it as `Authorization: Bearer <token>` on every call. It has the Setup scopes and expires soon.
* A model server already running on this machine on loopback: Ollama on port 11434, LM Studio on 1234, llama.cpp on 8080, or vLLM on 8000. The connector detects these by itself.

### Rules

1. **Never print, log, or write the token anywhere** except the `Authorization` header. Read it from the shell variable each time: `$TOKIOS_TOKEN` in bash, `$env:TOKIOS_TOKEN` in PowerShell, `%TOKIOS_TOKEN%` in cmd. The API key you mint in step 5 is different: hand that one to the human in your final report.
2. The token works only on `TOKIOS_CONSOLE/account/*`. Do not try `/admin`, `/auth`, `/v1`, or `/portal` with it.
3. **List before you create.** Re-use a pending connector of the same name and a deployment of the same public name. Never create a second API key because a retry failed. Creates are plain POSTs and are not idempotent.
4. Errors are JSON: `{"error":{"message":"…","type":"…","scope":"…"}}`.
   * `401`: the token is invalid, expired, or revoked. Stop and report.
   * `403` with `scope`: the token lacks that scope. Stop and report which scope is missing.
   * `403` "only available from the console": the action is reserved for a signed-in human. Do not work around it.
   * `409` on approve: re-read the connector row and retry as described in step 3.
   * `429`: wait 60 seconds, then retry.
5. Do not change passwords, reveal or share keys, touch request logging, or create other tokens. You cannot, and you must not try.
6. Report every step's outcome. If a step fails or is skipped, say so plainly.

The examples use bash. In Windows cmd, double-quote the URL and the JSON and escape the inner quotes, for example `-d "{\"name\":\"gpu-box\"}"`.

### Step 1: start pairing

First list existing connectors:

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
curl -s "$TOKIOS_CONSOLE/account/connectors" -H "Authorization: Bearer $TOKIOS_TOKEN"
```

If a row with your intended name already has `"status":"pending_pair"`, re-use it with a fresh claim code:

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
curl -s -X POST "$TOKIOS_CONSOLE/account/connectors/CONNECTOR_ID/claim-code" -H "Authorization: Bearer $TOKIOS_TOKEN"
```

Otherwise create one:

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
curl -s -X POST "$TOKIOS_CONSOLE/account/connectors" \
  -H "Authorization: Bearer $TOKIOS_TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"gpu-box"}'
```

Both return:

```json theme={"theme":{"light":"github-light","dark":"css-variables"}}
{
  "connector_id": "con_…",
  "claim_code": "TKS-XXXX-XXXX",
  "claim_code_expires_at": "2026-…",
  "server_url": "wss://…/connector/connect",
  "install_oneliner": {
    "macos": "curl -fsSL https://tokios.com/downloads/install/macos | sh -s -- --code TKS-XXXX-XXXX",
    "linux": "curl -fsSL https://tokios.com/downloads/install/linux | sh -s -- --code TKS-XXXX-XXXX",
    "windows": "irm https://tokios.com/downloads/install/windows | iex; tokios-install -Code 'TKS-XXXX-XXXX'"
  }
}
```

The claim code is valid for 15 minutes. Keep `claim_code` and `server_url`; ignore `install_oneliner` (it pipes a script into a shell, which you must not do — see step 2). There is no connector token in this response, and there never will be: the connector receives its own credential over the tunnel after approval.

### Step 2: install and start the connector on this machine, detached

Agent safety rules refuse to pipe a downloaded script into a shell (`curl … | sh`, `irm … | iex`), and saving the
script and running it is the same thing in disguise. Do not do either, and do not ask the human to approve it.
Use path A. It executes no downloaded script: you download the connector binary itself through the gateway's
redirect, verify it against the release's `SHA256SUMS`, and start it in the background with the claim code and
`server_url` from step 1.

**Path A (use this): download the binary, verify it, run it.**

Pick the asset for this machine: `linux/x64` → `tokios-connector-linux-x64`, `linux/arm64` →
`tokios-connector-linux-arm64`, `macos/arm64` → `tokios-connector-osx-arm64`, `windows/x64` →
`tokios-connector-win-x64.exe`, `windows/arm64` → `tokios-connector-win-arm64.exe`.

Linux and macOS (shown for `linux/x64`; on macOS use `shasum -a 256` instead of `sha256sum`):

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
mkdir -p ~/.tokios/connector && cd ~/.tokios/connector
curl -fsSL -o tokios-connector "$TOKIOS_CONSOLE/downloads/connector/linux/x64"
curl -fsSL -o SHA256SUMS https://github.com/tokiosAI/tokios-connector/releases/latest/download/SHA256SUMS
expected=$(grep -E '\*?tokios-connector-linux-x64$' SHA256SUMS | awk '{print $1}')
actual=$(sha256sum tokios-connector | awk '{print $1}')
[ -n "$expected" ] && [ "$expected" = "$actual" ] || { echo "checksum mismatch"; exit 1; }
chmod +x tokios-connector
nohup ./tokios-connector TKS-XXXX-XXXX --Connector:ServerUrl "SERVER_URL" > tokios-connector-stdout.log 2>&1 < /dev/null &
echo $! > tokios-connector.pid
```

Windows, in PowerShell (shown for `windows/x64`):

```powershell theme={"theme":{"light":"github-light","dark":"css-variables"}}
$dir = Join-Path $env:LOCALAPPDATA 'Tokios\connector'
New-Item -ItemType Directory -Force -Path $dir | Out-Null
Set-Location $dir
Invoke-WebRequest "$env:TOKIOS_CONSOLE/downloads/connector/windows/x64" -OutFile tokios-connector.exe
Invoke-WebRequest https://github.com/tokiosAI/tokios-connector/releases/latest/download/SHA256SUMS -OutFile SHA256SUMS
$expected = (((Get-Content SHA256SUMS) -match 'tokios-connector-win-x64\.exe$') -split '\s+')[0].ToLower()
$actual = (Get-FileHash tokios-connector.exe -Algorithm SHA256).Hash.ToLower()
if (-not $expected -or $expected -ne $actual) { throw "checksum mismatch" }
$p = Start-Process -FilePath .\tokios-connector.exe -ArgumentList 'TKS-XXXX-XXXX','--Connector:ServerUrl','SERVER_URL' -WorkingDirectory $dir -WindowStyle Hidden -RedirectStandardOutput tokios-connector-stdout.log -RedirectStandardError tokios-connector-stderr.log -PassThru
Set-Content tokios-connector.pid $p.Id
```

Replace `TKS-XXXX-XXXX` with `claim_code` and `SERVER_URL` with `server_url` from step 1. The connector dials out,
presents the code, waits for approval, then writes its own config next to the binary. If the machine already has
`tokios-connector` installed, skip the download and run that binary the same way.

**Path B (only if the human asks for the installer):** the installer does the same download and checksum steps
and adds the `--detach` flag. It is meant for a human to paste. If you are asked to use it, download it to a file
and read it before running the saved file, and say so in your report. Never pipe it.

The connector's output is in `tokios-connector-stdout.log` and its pid in `tokios-connector.pid`, in the
directory above. Stop it later with `kill $(cat tokios-connector.pid)` or `Stop-Process -Id (Get-Content tokios-connector.pid)`.

**Persistence.** A detached process does not survive a reboot. Do not install a service unless the human's message
asked you to make the connector start at boot; otherwise say so in your final report and offer it. If you were
asked: finish steps 3 to 6 first, then stop the detached process (`kill $(cat tokios-connector.pid)`; the connector
allows 1 instance per directory) and follow [Run the connector at boot](/setup/connector-install.md#run-the-connector-at-boot)
for this platform. On Linux that is a systemd user unit whose `ExecStart` is
`%h/.tokios/connector/tokios-connector --config %h/.tokios/connector/tokios-connector.json`, enabled with
`systemctl --user enable --now tokios-connector`, plus `loginctl enable-linger "$USER"` so it starts without a login.
The pairing lives in `tokios-connector.json`, so the service reconnects without a new claim code.

### Step 3: wait for the device, then approve it

Poll every 3 seconds for up to 2 minutes:

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
curl -s "$TOKIOS_CONSOLE/account/connectors" -H "Authorization: Bearer $TOKIOS_TOKEN"
```

Find your `connector_id`. When the row shows `"claimPending": true`, it also carries `"sessionId": "sess_…"` and `"machineName"`. Check that the machine name is this machine, then approve with that exact session id:

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
curl -s -X POST "$TOKIOS_CONSOLE/account/connectors/CONNECTOR_ID/approve" \
  -H "Authorization: Bearer $TOKIOS_TOKEN" -H "Content-Type: application/json" \
  -d '{"session_id":"sess_…"}'
```

Success is `{"status":"approved"}`.

On `409`, the device reconnected with a new session id, is not connected yet, or the claim code expired. Re-read the row. If the code expired, request a new one as in step 1 and restart the connector with it. Otherwise approve again with the current `sessionId`.

Keep polling until the row shows `"status":"active"`, `"online":true`, and a non-empty `"announcedModels"`. Allow up to 60 seconds: the connector detects local models after approval. If `announcedModels` stays empty, no model server is running on a detected loopback port. Report that and stop.

### Step 4: publish the model

Check the workspace policy:

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
curl -s "$TOKIOS_CONSOLE/account/auto-publish" -H "Authorization: Bearer $TOKIOS_TOKEN"
```

* If it returns `{"auto_publish": true}`, every announced model is published for you. Poll `GET $TOKIOS_CONSOLE/account/models` until the announced names appear as `id` values.

  Be precise about what that means when you report it. "Published" means the model has a deployment in this
  workspace: it is callable at the API host by anyone holding one of this workspace's API keys whose model scope
  covers it, and by nobody else. Nothing is reachable without a key. It happens the moment the connector announces
  its models after approval, a few seconds in, and the public name is the upstream model id (for example
  `gemma4:e4b`). Auto-publish also re-publishes a model you deleted if the connector announces it again, so if the
  human wants only some of the detected models exposed, pause the others with
  `POST $TOKIOS_CONSOLE/account/deployments/DEPLOYMENT_ID/disable` and mention that auto-publish is on. A paused model stays
  paused. Do not delete them: deleting needs the `models:reroute` scope, which the Setup preset does not include,
  and auto-publish would publish a deleted model again.
* If it returns `false`, list `GET $TOKIOS_CONSOLE/account/deployments` first, then create 1 deployment per model that should be callable:

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
curl -s -X POST "$TOKIOS_CONSOLE/account/deployments" \
  -H "Authorization: Bearer $TOKIOS_TOKEN" -H "Content-Type: application/json" \
  -d '{"public_name":"gemma4:e4b","upstream_model":"gemma4:e4b","connector_id":"con_…"}'
```

`public_name` is what clients will send in the `model` field. `upstream_model` must be 1 of the `announcedModels`. A `409` means the name already exists; leave it as it is.

### Step 5: mint the API key

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
curl -s -X POST "$TOKIOS_CONSOLE/account/keys" \
  -H "Authorization: Bearer $TOKIOS_TOKEN" -H "Content-Type: application/json" \
  -d '{"display_name":"laptop 2026-10-16","model_patterns":["gemma4:e4b"]}'
```

Response: `{"id":"key_…","secret":"sk-tok-…","retrievable":true}`. The `secret` is shown once. Keep it for the report. Restrict `model_patterns` to the models you published; omit it only if the human asked for all models.

### Step 6: verify

Run the health check, a 1-token ping over the tunnel:

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
curl -s -X POST "$TOKIOS_CONSOLE/account/models/healthcheck" \
  -H "Authorization: Bearer $TOKIOS_TOKEN" -H "Content-Type: application/json" \
  -d '{"model":"gemma4:e4b"}'
```

Expect `"status":"ok"` with a `latency_ms`. Then make 1 real call with the **API key**, not the token. The client base URL is `https://api.tokios.com`; confirm it with `GET $TOKIOS_CONSOLE/account/connection`, which returns `base_url`.

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
curl -s -X POST "https://api.tokios.com/v1/chat/completions" \
  -H "Authorization: Bearer sk-tok-…" -H "Content-Type: application/json" \
  -d '{"model":"gemma4:e4b","messages":[{"role":"user","content":"Say hello in five words."}],"max_tokens":32}'
```

### Step 7: final report

Give the human:

* Connector: name, id, status, machine name.
* Models published: the public names, and whether auto-publish created them or you did. Remind the human that these are callable by holders of the workspace's API keys, not by the public.
* Whether the connector survives a reboot: "no, it runs detached" unless you installed a service, in which case say which one.
* API key: its id **and the `sk-tok-` secret**. This is the 1 secret you are meant to hand over.
* Client configuration, from `GET $TOKIOS_CONSOLE/account/connection`:
  * Claude Code: `ANTHROPIC_BASE_URL=<base_url>`, `ANTHROPIC_API_KEY=<sk-tok-…>`, and the model name to pass with `--model`.
  * Codex: `OPENAI_BASE_URL=<base_url>/v1`, `wire_api=responses`, `disable_response_storage=true`.
* The verification result: the health-check status and the chat reply.
* Anything you skipped or could not do, and why.

> **[Automation tokens](/setup/automation-tokens.md)**
>
> Scopes, presets, expiry, and how to revoke or regenerate a token.

> **[Claude Code](/guides/claude-code.md)**
>
> Point Claude Code at the key and model the agent just created.


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