tollan docs Sign up

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-<username>.a.tollan.app, where <username> is your organization's username).
  • Architecture — the OS/CPU of the host that runs the agent, so the bundle ships the right binary: linux/amd64, linux/arm64, linux/arm (32-bit ARM — uname -m says armv6l/armv7l), 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:

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

A bundle contains:

FilePurpose
Agent binaryThe Go agent for the chosen architecture
device.crtThe device's client certificate (mTLS identity)
device.keyThe device's private key — secret
ca.crtThe CA certificate the agent uses to verify the relay
agent.envThe agent's settings (written by the installer)
install.sh / install.ps1Installs 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. 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:

  1. In the console, mint a one-time enrollment token for the device.
  2. Configure the device with ENROLL_URL and ENROLL_TOKEN (via the installer, a QR code, or a config file).
  3. 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.
  4. 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 installer writes the agent's settings into agent.env; you normally never edit it. The two you might change:

VariablePurpose
LOCAL_TARGETDefault local service, e.g. 127.0.0.1:8080
LOCAL_TARGETSExtra host:port targets the agent may connect to

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 their certificates automatically, so no operator action is needed. Keep a device online now and then so it can; one that has been off for too long needs a new bundle.

Note

An agent installed from a bundle downloaded before automatic renewal shipped can't renew: install a fresh bundle on it. The desktop and phone apps renew after an app update, with no new bundle.

See the security model.

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.

Health. With each allowlist check-in (every 15 minutes on Linux, Windows, macOS and phones; every 5 on an ESP32) the agent reports its machine's health: free memory, CPU load, free disk, uptime and, on a Raspberry Pi, the CPU temperature (an ESP32 sends free memory, Wi-Fi signal, uptime and its last reset reason). The device page shows the latest report.

Stability. The device page's Stability tab covers the last 72 hours: how long the current connection has lasted, the share of time the device was online over 24 and 72 hours, its disconnects, the typical time to reconnect, the longest outage, a list of outages, and the free memory from each check-in.

Live log. Open live log on the device page streams the agent's recent log, then new lines as they happen. Nothing is sent while the log is closed, and these bytes don't count towards your traffic. Agents installed before this feature need a new bundle or the latest app.

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.