Concepts & glossary#

The terms used throughout these docs, and how they relate.

The moving parts#

Agent — the tunnel client that runs on or beside your device. It dials out to the relay over mutual TLS and bridges channels to local targets. Two implementations exist and speak the same protocol: the Go agent (installed from a bundle) and the TollanAgent library for ESP32.

Relay — the public-facing server that accepts inbound connections and routes them to the right device over its open tunnel. It's a byte pump: for passthrough routes it never decrypts your traffic.

Control plane — the API and console that manage state: devices, routes, certificates, teams, and billing. It runs the certificate authority and tells the relay what routes exist.

Console — the web dashboard at app.tollan.ie. Everything below is created and managed here (or through the API at api.tollan.ie).

The resources you manage#

Organization (org) — the tenant boundary. It owns devices, routes, members, and billing. Every resource belongs to exactly one org, and data is isolated between orgs. Users join orgs via memberships with a role.

Role — a member's permission level in an org: admin (full control, including billing and members), operator (manage devices and routes), or viewer (read-only).

Device — a physical or virtual machine represented in the console. It has an identity (a client certificate), a status (pending / online / offline), and owns routes. One agent instance == one device.

Bundle — a one-time download package that provisions a device: the agent binary, its certificate and key, the CA certificate, config, and an installer. See Devices & bundles.

Route — the rule that exposes an internal service publicly. It has an exposure mode (hostname/SNI or port), a public address, and an internal target the agent connects to. See Routes & exposure.

Internal target — the host:port on your side that the agent bridges a channel to, e.g. 127.0.0.1:8080 (same host) or 192.168.1.50:80 (a LAN host, forwarding mode).

Exposure mode — how a route is reached from the public internet:

Certificate — the mutual-TLS identity issued by Tollan's CA. Devices present a client certificate; the relay presents a server certificate. Certificates can be rotated (revoke + reissue) or revoked. See Security.

Enrollment token — a one-time token that lets a device generate its own key on first boot and request a certificate via a CSR, so the private key never leaves the device. An alternative to bundle-issued keys.

Access rule — an optional edge-authorization layer on a route or device: IP allowlist, HTTP basic auth, OIDC, or client-certificate mTLS. See Access control.

Custom domain — your own domain used for a route instead of a *.tollan.app subdomain, with automatic TLS certificate issuance. A paid-plan feature.

Billing terms#

Plan — a billing tier (e.g. Free, Pro) that defines limits: number of devices, routes, monthly egress, team seats, and custom domains.

Entitlement — an org's current plan plus its billing status (active, trialing, past_due, canceled, suspended). Only a verified billing event changes it.

Quota — a plan limit enforced when you create resources. Creating a device or route past your plan's limit is refused until you upgrade.

Egress — outbound bytes pumped through your tunnels, summed per month and metered against your plan.

Suspension (dunning) — if an org's subscription goes past_due, the relay stops pumping that org's traffic until payment is resolved. Tunnels stay connected but carry no data.

Protocol terms#

Tunnel — the single long-lived mutual-TLS WebSocket connection from an agent to the relay. All of a device's traffic is multiplexed over it.

Channel — one multiplexed stream inside a tunnel, corresponding to a single public connection. Opened with OPEN, carries DATA, ends with CLOSE.

Frame — the unit of the wire protocol: a 5-byte header (type + channel id) plus payload. The five types are OPEN, DATA, CLOSE, PING, PONG. See the wire protocol.

tollan.v1 — the wire protocol version, negotiated at WebSocket upgrade. A version mismatch is terminal — the agent stops rather than talk a protocol it doesn't understand.

Handler mode / forwarding mode — the two ways an agent answers a channel: the device is the service (handler), or the device proxies other LAN hosts (forwarding). See How it works.