Let a coding agent set up Tokios for you

This page has 2 readers. The first section is for you. Everything from Instructions for the agent onward is written for the agent to read and execute.

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:

curl -fsSL https://docs.tokios.com/guides/agent-setup.md

Then follow 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

Mint an automation token

In the dashboard, open Settings, then Automation tokens, then Create token. Use the Setup preset and a 1 hour expiry. Copy the token once. See Automation tokens.

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.

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
Windows CMD
macOS & Linux

$env:TOKIOS_CONSOLE="https://tokios.com"
$env:TOKIOS_TOKEN="at-tok-YOUR_TOKEN"
claude

set TOKIOS_CONSOLE=https://tokios.com
set TOKIOS_TOKEN=at-tok-YOUR_TOKEN
claude

export TOKIOS_CONSOLE=https://tokios.com
export TOKIOS_TOKEN=at-tok-YOUR_TOKEN
claude

Send the agent 1 message

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.

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

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.
The token works only on TOKIOS_CONSOLE/account/*. Do not try /admin, /auth, /v1, or /portal with it.
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.
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.
Do not change passwords, reveal or share keys, touch request logging, or create other tokens. You cannot, and you must not try.
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:

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:

curl -s -X POST "$TOKIOS_CONSOLE/account/connectors/CONNECTOR_ID/claim-code" -H "Authorization: Bearer $TOKIOS_TOKEN"

Otherwise create one:

curl -s -X POST "$TOKIOS_CONSOLE/account/connectors" \
  -H "Authorization: Bearer $TOKIOS_TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"gpu-box"}'

Both return:

{
  "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):

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):

$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 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:

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:

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:

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:

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

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:

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.

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

Scopes, presets, expiry, and how to revoke or regenerate a token.

Claude Code

Point Claude Code at the key and model the agent just created.

Hardware & fit

Serve & connect your runtime

Connect a client or app

Compare

Let a coding agent set up Tokios for you

Before you start

Instructions for the agent

What you have

Rules

Step 1: start pairing

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

Step 3: wait for the device, then approve it

Step 4: publish the model

Step 5: mint the API key

Step 6: verify

Step 7: final report

Automation tokens

Claude Code

​Before you start

​Instructions for the agent

​What you have

​Rules

​Step 1: start pairing

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

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

​Step 4: publish the model

​Step 5: mint the API key

​Step 6: verify

​Step 7: final report

Automation tokens

Claude Code

Before you start

Instructions for the agent

What you have

Rules

Step 1: start pairing

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

Step 3: wait for the device, then approve it

Step 4: publish the model

Step 5: mint the API key

Step 6: verify

Step 7: final report