Devices & bundles#

A device is an agent's identity in Tollan. Registering one gives it a certificate; installing its bundle puts a running agent on the machine; adding routes exposes services through it.

Register a device#

In the console, create a device with:

Name — a human label (e.g. warehouse-pi).
Slug — the short identifier used in default hostnames (e.g. warehouse-pi → warehouse-pi.tollan.app).
Architecture — the OS/CPU of the host that runs the agent, so the bundle ships the right binary: linux/amd64, linux/arm64, darwin/arm64, windows/amd64, and so on.
Agent CN — the certificate common name (usually derived from the name automatically).

A new device is pending until an agent connects with its certificate, at which point it becomes online (and offline when the tunnel drops).

Provision it: bundle mode#

The default path. The control plane issues the device's key and certificate for you and packages everything:

Open the device and build a bundle.
Download it — the link is one-time and short-lived (about 15 minutes).
Extract and run the installer on the device.

A bundle contains:

File	Purpose
Agent binary	The Go agent for the chosen architecture
`device.crt`	The device's client certificate (mTLS identity)
`device.key`	The device's private key — secret
`ca.crt`	The CA certificate the agent uses to verify the relay
`agent.env`	Config: relay URL, SNI, target allowlist, renewal settings
`install.sh` / `install.ps1`	Installs and starts a background service

bash

tar -xf tollan-warehouse-pi-linux-arm64.tar.gz
cd tollan-warehouse-pi
sudo ./install.sh          # Linux/macOS — installs a systemd service
# Windows: run install.ps1 in an elevated PowerShell

Important

The private key in a bundle never leaves your possession after download — the control plane keeps only what it needs to verify renewals. Store the bundle securely and delete it once installed.

Provision it: enrollment mode#

For devices that should generate their own key so the private key never touches the network:

In the console, mint a one-time enrollment token for the device.
Configure the device with ENROLL_URL and ENROLL_TOKEN (via the installer, a QR code, or a config file).
On first boot the agent generates an EC key on-device, builds a CSR, and submits it. The control plane verifies the token and signs it, returning the certificate and CA.
The agent writes the certificate locally and continues to tunnel startup. The private key is never transmitted.

Enrollment is the more secure option for fleets; bundle mode is the quickest for a single machine.

Agent configuration#

The Go agent is configured by environment variables (the installer writes them into agent.env). The most common:

Variable	Purpose
`RELAY_WS`	The relay's tunnel endpoint the agent dials out to
`RELAY_SNI`	TLS SNI hostname the relay's cert is pinned to
`LOCAL_TARGET`	Default local service, e.g. `127.0.0.1:8080`
`LOCAL_TARGETS`	Allowlist of additional `host:port` targets it may bridge to
`TLS_CERT` / `TLS_KEY` / `TLS_CA`	Paths to the device's mTLS material
`RENEW_URL` / `RENEW_BEFORE`	Automatic certificate renewal endpoint and lead time
`TARGETS_URL`	Optional: sync the target allowlist from the control plane

You normally never edit these by hand — the bundle sets them. They're listed here so you know what the installer configured.

Certificate lifecycle#

From the device page you can:

Issue a new certificate.
Rotate — revoke the active certificate and issue a fresh one (returns a new key for one-time download). Use after a suspected key exposure or on a schedule.
Revoke — invalidate the device's certificates. The relay checks revocation status and drops the tunnel; the device can't reconnect until re-provisioned.

Agents also renew automatically before expiry when RENEW_URL is configured, proving possession of their key so no operator action is needed. See the security model for the full detail.

Metrics & status#

Each device reports online/offline status and periodic traffic metrics (bytes in/out, active channels) that the relay pushes to the control plane. The console surfaces these on the device page and rolls egress up into your org's usage.

Deleting a device#

Deleting a device cascades to its routes and revokes its certificates. The agent's next connection attempt fails mTLS. Delete when you're decommissioning hardware or rotating a compromised identity you can't otherwise recover.

Next: Routes & exposure — actually publish a service through the device.