Mesh networking
The mesh subsystem gives you a flat overlay across all your gateways and any clients you’ve joined. You can use it for remote management (SSH into a Pi at home from a laptop on the other side of the world) or for traffic (use a peer node as your egress).
The Gateway supports two control planes:
- Tailscale — SaaS coordinator, zero setup, free tier. Easy mode.
- Headscale — self-hosted coordinator, fully under your control. The installer can bring it up alongside
gatewayd.
The dataplane in both cases is the same WireGuard, with STUN / DERP relays for NAT traversal.
What it gives you
Section titled “What it gives you”- Peer-to-peer reachability between every node you’ve joined to the mesh, regardless of NAT.
- Subnet routing — advertise your LAN (
192.168.10.0/24) from one gateway and reach it from another. - Exit nodes — route a remote peer’s egress through your gateway (useful for routing a travel laptop through home).
- Hostname discovery — every node has a stable hostname inside the mesh DNS (
*.headscale.lanor*.ts.net). - Per-peer ACLs — Headscale supports Tailscale-style ACL files; rules apply per-source / per-destination.
Headscale, self-hosted
Section titled “Headscale, self-hosted”The full install profile sets up Headscale alongside gatewayd. The bootstrap config:
mesh: enabled: true provider: headscale server_url: "https://mesh.example.invalid:8085" api_key: "REDACTED" auth_key: "REDACTED" namespace: "default" poll_interval: 30 advertise_routes: - "192.168.10.0/24" exit_node: falseThe Headscale instance runs as its own systemd unit; gatewayd only consumes its API.
Tailscale, SaaS
Section titled “Tailscale, SaaS”mesh: enabled: true provider: tailscale auth_key: "tskey-auth-REDACTED" advertise_routes: - "192.168.10.0/24"Pick one provider at startup; switching requires a daemon restart with the new bootstrap config.
Coordination-server front (v2.19.0)
Section titled “Coordination-server front (v2.19.0)”An optional public gateway can serve another gateway’s Headscale over HTTPS through their federation tunnel. Devices away from home can reach the coordinator without exposing the home gateway’s public address. The front uses a short-lived Let’s Encrypt IP certificate and exposes only the paths mesh clients need.
This feature is admin-only and off by default. Enabling it creates a public entry to that Headscale control plane; it is not merely an outbound relay or a private management tunnel. Configure it through PUT /api/v1/mesh/control-front only when that exposure is intended.
Mesh privacy defaults (v2.19.0)
Section titled “Mesh privacy defaults (v2.19.0)”Relay-map downloads follow the gateway’s own-traffic tunnel policy. Ghost mode suppresses relay-map downloads, relay probing and captive-portal checks; relay fallback waits. The installer starts tailscaled with --no-logs-no-support.
The Tailscale Inc. (self-hosted tailnet) telemetry-blocking preset is a separate opt-in and is off by default. It can break Tailscale-hosted clients that resolve through this gateway; self-hosting one tailnet is not sufficient reason to enable it for every client.
Inter-gateway federation vs mesh
Section titled “Inter-gateway federation vs mesh”Two related things:
- Mesh is overlay connectivity. Any device with
tailscale/tailscale upjoins. - Federation is configuration sharing between
gatewaydinstances. It usually runs over a mesh tunnel, but it’s a separate concern: federation is about which config kinds flow between which peers; mesh is about whether boxes can reach each other.
A common deployment: mesh joins five nodes; federation has one node push routing and dns to the other four.
API surface
Section titled “API surface”| Method | Path | Purpose |
|---|---|---|
GET |
/api/v1/mesh/status |
Coordinator reachable? Local node state. |
GET |
/api/v1/mesh/config |
Current mesh configuration |
GET |
/api/v1/mesh/peers |
List peers with IP, hostname, RTT, online |
DELETE |
/api/v1/mesh/peers/{id} |
Remove a peer |
POST |
/api/v1/mesh/up |
Bring this node up on the mesh |
POST |
/api/v1/mesh/down |
Take it down |
POST |
/api/v1/mesh/create-key |
Mint a Headscale pre-auth key |
POST |
/api/v1/mesh/register |
Register this node with the coordinator |
GET |
/api/v1/mesh/derp-mode |
DERP-relay mode setting |
PUT |
/api/v1/mesh/control-front |
v2.19.0: configure the optional coordination-server front; admin only. |
Next steps
Section titled “Next steps”When the mesh is up and peers are reachable:
- Build federation on top. Mesh gives you connectivity; federation lets you push/pull selected config kinds across the same tunnel with per-peer allowlists.
- Probe peers from each direction. Symmetric NAT sometimes lets traffic flow one way but not the other — check
gwctl mesh peersfrom both nodes. - Pin DERP if you’re seeing >50 ms RTT to direct-paired peers — a relay can paradoxically be faster than a direct path through a bad route.
- Audit the pre-auth keys you’ve minted. A leaked key joins any device to the mesh; revoke via the coordinator and rotate.
Linked meshes and managed relays (v2.18.0)
Section titled “Linked meshes and managed relays (v2.18.0)”Two gateways hosting their own Headscale control planes can link their meshes through the federation tunnel, with per-direction access policies and a reachability matrix. DERP can be fronted by gatewayd over TLS on port 443. A fresh installation has no relay until one is set up; use Server management to provision and maintain your own relays.
Related
Section titled “Related”- Federation — what runs over the mesh tunnel between gateways.
- Use case: hybrid home lab — home Pi + VPS joined over a self-hosted Headscale mesh.