Wire protocol (tollan.v1)#
The protocol between an agent and the relay is deliberately small — a single authenticated connection carrying a handful of message types. This page is a conceptual overview; you do not need it to use Tollan, since the agents implement it for you.
Transport#
An agent connects to the relay outbound over a mutual-TLS WebSocket:
- Mutual TLS — the agent presents its client certificate and the relay presents its server certificate; both sides authenticate, and neither trusts the network. See the security model.
- WebSocket — the tunnel is one long-lived connection over which all of a device's traffic is multiplexed.
Version negotiation#
The protocol version is negotiated when the connection is established; the current version is tollan.v1. A version mismatch is terminal — the agent stops rather than risk talking a protocol the relay doesn't understand. This is a safety property, and it's why platform upgrades are coordinated.
Channels and messages#
Each public connection the relay accepts becomes a channel multiplexed over the tunnel. Channels have a simple lifecycle expressed by a few message types:
| Message | Meaning |
|---|---|
| Open | The relay asks the agent to open a new channel (optionally naming an internal target). |
| Data | Bytes flowing in either direction on a channel. |
| Close | Either side finishes; the channel is retired. |
| Keepalive | Periodic heartbeat that keeps an idle tunnel healthy and detects a dead peer. |
That small vocabulary is the entire protocol. Everything you do with Tollan — every request that reaches your device and every response that comes back — is these messages moving over the one authenticated tunnel.
One protocol, three agents#
The same protocol is implemented by every agent — the Go agent, the Node relay, and the ESP32 library — and all three are held to the same conformance tests, so a message produced by one is understood identically by the others. That shared conformance is what lets a microcontroller join the same fleet as a full server and speak the same language on the wire.