tokios-connector.json configuration reference

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.

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:

tokios-connector.json

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

tokios-connector --config tokios-connector.json

`Connector` fields

string

required

managed by pairingrestart requiredThe connector’s id from the console (e.g. con_...). Identifies this connector to the Tokios gateway.

string

required

managed by pairingsecret — redacted in logsThe connector token issued when you create the connector (e.g. ct-...), bound to your tenant. Shown only once in the console.

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

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:

tokios-connector.json

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

tokios-connector.json

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

Upstream fields

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

string

required

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

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.

string[]

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

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:

string

The key injected into the upstream request.

string

default:"Authorization"

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

string

default:"Bearer "

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

object

Static headers added to every upstream request.

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:

tokios-connector --config tokios-connector.json --Logging:LogLevel:Default=Debug

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:

tokios-connector.json

{
  "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" }
  }
}

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.

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.

integer

default:"14"

Number of daily log files to keep.

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

Complete example

macOS
Linux
Windows

Config path: ~/Library/Application Support/tokios/tokios-connector.json

{
  "Connector": {
    "ConnectorId": "<generated-during-pairing>",
    "Token": "<generated-during-pairing>",
    "Models": ["gemma4:e4b"],
    "Upstream": {
      "BaseUrl": "http://127.0.0.1:11434/v1"
    }
  }
}

Config path: /etc/tokios/tokios-connector.json

{
  "Connector": {
    "ConnectorId": "<generated-during-pairing>",
    "Token": "<generated-during-pairing>",
    "Models": ["gemma4:e4b"],
    "Upstream": {
      "BaseUrl": "http://127.0.0.1:11434/v1"
    }
  }
}

Config path: %APPDATA%\tokios\tokios-connector.json

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

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.

macOS (launchd)
Linux (systemd)
Windows (Service)

Create a plist file at ~/Library/LaunchAgents/com.tokios.connector.plist:

~/Library/LaunchAgents/com.tokios.connector.plist

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

launchctl load ~/Library/LaunchAgents/com.tokios.connector.plist
launchctl start com.tokios.connector

Create a unit file at /etc/systemd/system/tokios-connector.service:

/etc/systemd/system/tokios-connector.service

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

sudo systemctl daemon-reload
sudo systemctl enable tokios-connector
sudo systemctl start tokios-connector

On Windows, use NSSM (Non-Sucking Service Manager) or Task Scheduler to run the connector as a background service.Using NSSM:

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.

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 for resolution steps.

Get Started

Models

Concepts

Reference

tokios-connector.json configuration reference

The config file

`Connector` fields

Declaring what the connector serves

Upstream fields

Authenticating to a remote upstream

Command-line flags

Logging

Complete example

Running as a background service

​The config file

​Connector fields

​Declaring what the connector serves

​Upstream fields

​Authenticating to a remote upstream

​Command-line flags

​Logging

​Complete example

​Running as a background service

​Related errors

The config file

`Connector` fields

Declaring what the connector serves

Upstream fields

Authenticating to a remote upstream

Command-line flags

Logging

Complete example

Running as a background service

Related errors