Skip to content

Reverse tunnels

After pairing, a device holds a single long-lived, encrypted reverse channel to its cluster node. Inside that channel, the device's local services — its web GUI, its internal API, its telemetry — are mapped to endpoints allocated on the cluster side, so the platform can reach them without any inbound path to the device. The channel is supervised continuously, and control flows back to the device pull-based.

The persistent reverse channel

The reverse channel is the durable outbound connection a device opens to its cluster and keeps open. "Reverse" describes the direction of setup versus use: the device establishes the connection outward, but once established, cluster-side services reach into the device's local ports through it. This is what lets a device with no public address expose its management interface to the platform while exposing nothing to the internet. One device holds one channel to one cluster node; the channel carries device traffic — control API calls, native GUI sessions, telemetry, and media previews — but never carries cluster-to-device signaling, which is handled separately and pull-based.

Mapping local services to cluster endpoints

A device's useful services usually listen only on its loopback interface — a web GUI on HTTP at 127.0.0.1, an internal API, a telemetry endpoint. Through the reverse channel, each of these is mapped to an endpoint allocated on the cluster node, recorded in a port-allocation record that ties a given local service to its cluster-side endpoint for the life of the channel. A cluster-side adapter or a native-GUI session then connects to that allocated endpoint as though the device were local. Because the mapping is explicit and recorded, the cluster knows exactly which endpoint reaches which service on which device, and it can tear the mapping down cleanly when the device disconnects.

Health supervision and stale-endpoint reclamation

The cluster supervises channel health continuously rather than assuming a once-established channel stays valid. When a device's link drops — common on cellular and intermittent networks — its channel closes and its allocated cluster-side endpoints become stale. The cluster reclaims those stale endpoints so they can be reissued, and the device, on reconnecting with backoff, is allocated fresh endpoints and a new port-allocation record. This self-healing loop means a flapping link produces temporary unreachability, not a permanently wedged allocation, and the cluster's view of which endpoints are live stays accurate.

Cluster-to-device instructions are never pushed. Instead the agent polls its cluster on a heartbeat for pending signals — configuration updates, reboot, reprovision, and upgrade — and applies them when it next checks in. This pull model is deliberately chosen for links that come and go: a pushed command would fail whenever the device happened to be unreachable, requiring retries, delivery tracking, and a persistent inbound-capable session. Polling inverts that — the device asks when it can, so a command simply waits in a shallow queue until the next successful check-in and is then applied. The cost is bounded latency; the benefit is that control tolerates disconnection without any inbound channel.