Relay for restricted networks
Most fleets do not sit on an open network. Devices live behind NAT, on factory VLANs, or behind a corporate firewall that allows only outbound traffic. The question for any fleet platform is the same: how does the control plane reach a device it cannot dial? Meshanics answers it by never needing to dial in.
The connection model: outbound only
The agent initiates every connection. It dials the control plane over a mutually authenticated (mTLS) channel, registers, and then heartbeats on an interval the server assigns. The control plane never opens a connection back to a device.
This has direct consequences for restricted networks:
- No inbound ports on devices. A device needs no public address, no port forward, and no inbound firewall rule. It works behind NAT unchanged.
- Egress is all you allow. The only requirement is that the device can make outbound connections to the control plane's device endpoints.
- Desired state flows on the device's own poll. Update assignments are delivered in the heartbeat response, so a device picks up work the next time it reaches out - there is nothing to push at it.
device (behind NAT) control plane
────────────────── ─────────────
agent ──── outbound mTLS ─────────▶ device API (register, heartbeat)
agent ──── outbound mTLS ─────────▶ artifact repo (verified pull)
◀── desired state in response ──
What a restricted network must permit
For a device to be managed, its network needs to allow outbound, mutually authenticated connections to two endpoints on the control plane: the device API, where it registers and heartbeats, and the artifact repository, from which it pulls verified updates. Both are mTLS-only; both run on stable ports you choose at deployment.
If your environment forces traffic through an egress proxy, route the agent's outbound connections through it the way you would any other service on the host.
Bringing the control plane closer
When even outbound reach is constrained - a cell that can talk to a local gateway but not to a central site - the control plane can be placed inside the restricted zone. A single-node deployment on a local box gives devices a control plane they can reach with a short, local egress rule, while the operators who run rollouts work against that same node. For a zone with no path out at all, see Offline & air-gapped operation.
The site gateway
When devices cannot reach any control plane directly - a private OT LAN, a DMZ, or a site with a single audited egress - install a gateway on one box at the network boundary. Devices on the site treat the gateway as their control plane, and it relays their traffic outward on one outbound connection. No inbound port is opened on the site. The gateway holds only its own tenant-scoped identity. It never receives device private keys, customer release-authorizer keys, or TUF signing-role keys. A compromised gateway can delay, deny, or replay cached bytes, but it cannot forge an accepted update. Every signature, version, expiry, and digest check still happens on the device.
Register a gateway in the console under Devices → Air-gapped, then run the one-line installer it gives you on the site box:
curl -fsSL https://meshanics.com/gateway-install.sh | sudo bash -s -- \
--token <BOOTSTRAP-TOKEN> --name <SITE> \
--upstream <CONTROL-PLANE-HOST> --addresses <THIS-GATEWAY-ADDRESS>
| Flag | What it sets |
|---|---|
--name | the gateway/site name you registered |
--upstream | the control-plane address the gateway relays to |
--addresses | the LAN name or IP the site's devices reach this gateway by; turns on the on-site artifact cache |
The generated command also configures the gateway's outbound reverse tunnel. The gateway self-enrols once with the bootstrap token, then runs as a service.
Pointing devices at the gateway
Expand the enrolled gateway in Devices → Air-gapped and choose Add device. The console uses the LAN address reported by a connected gateway when available, or lets you enter the address devices use to reach it. It then creates a one-use token and gives you a tenant-pinned command. Run that command on the device. If you already have SSH access from the gateway host, the optional SSH target produces a wrapper you can run there instead. Meshanics does not store SSH credentials or initiate that connection.
The token is bound to the selected gateway. After the device registers, the fleet list and expanded device view label its connection via gateway-name. This is the route chosen during enrollment, not a claim that Meshanics continuously inspects or monitors every network hop.
The gateway's detail panel offers two bounded installation choices. Install on the target device is the normal path. Install remotely from this gateway host is a convenience wrapper for sites where the operator already has SSH access. Long commands remain inside a scrollable command panel and can be copied without widening the console page.
Devices on the site enrol against the gateway instead of the control plane. Each device keeps verifying the control plane's own identity end-to-end, so the gateway cannot impersonate it - it is the same agent either way:
| Flag | Environment | What it sets |
|---|---|---|
--host | MESHANICS_HOST | the gateway address the agent talks to |
--server-name | MESHANICS_SERVER_NAME | the control-plane identity the agent verifies through the relay |
A device with neither set talks straight to the control plane, unchanged.
The gateway authenticates its cache refresh with its own tenant-scoped gateway certificate. That identity can fetch only TUF metadata and target bytes for its own tenant. It cannot act as a device or fetch device manifests, firmware, or keys. The agent still verifies the complete TUF chain and artifact digest after the bytes cross the gateway.
Re-enrolling a gateway after a trust change
A gateway intentionally keeps its identity and pinned update root across normal
installer runs. If the tenant root changes, revoke the old gateway, register a
replacement, and append --replace-identity to the new install command. The
installer moves the previous identity files to a timestamped backup before
enrolling again. Cached artifacts and queued evidence are preserved.
Do not use --replace-identity for routine upgrades. A normal installer run
updates the binary while retaining the established gateway identity.
The on-site cache
With --addresses set, the gateway also caches update artifacts on the site:
the first device pulls a given artifact across your egress link, and every other
device pulls it from the gateway over the LAN. Each device still verifies the
cached bytes against the update's own signature and hash, so the cache is never
a trust anchor - only a bandwidth saving.
Site gateways are part of a scoped on-premise or air-gapped deployment. Request pricing from Settings → Billing in the console or review plans & pricing.