Dedicated Gateway Appliance

A gateway in meshr is not a special install mode or a separate binary. Any normal peer becomes a gateway the moment an admin attaches it to a routed-subnet route in the portal. A "gateway-only device" is therefore just an ordinary agent install on a box that you deliberately keep free of other heavy work.

This guide covers how to dedicate a small box to that single role, why it's worth doing, and how to attach and verify it.

If you're new to routes themselves, read Routes first — this page is about the hardware and placement side of a gateway, not the route model.

Why Dedicate a Box

Forwarding a subnet is cheap, but it is latency-sensitive. The gateway peer forwards every packet between the mesh and the LAN and runs periodic health probes so the controlplane knows it's alive.

When the same box also runs a heavy workload — video transcoding, an AI inference server, a busy database — that workload can saturate the CPU. When it does, the gateway's forwarding and probe paths get starved: forwarded traffic stalls, health probes are delayed, and the route can flap between healthy and degraded. Mesh clients see this as intermittent "can't reach the LAN" behaviour.

Moving the gateway role onto its own box removes the contention. The appliance does one thing, so its forwarding path always has CPU to spare.

The core rule

The whole point of a dedicated gateway is that nothing else CPU-heavy runs on it. That single invariant is what keeps forwarding predictable.

Requirements

Subnet forwarding programs kernel NAT and IP forwarding, so the gateway must be Linux. Meshr sets net.ipv4.ip_forward=1 and installs the masquerade rule for you when the device is attached to a route — there is no portable equivalent on macOS or Windows, and a non-Linux peer simply reports the route as unsupported and drops the traffic.

The box also needs a working path into the target subnet — a NIC on the LAN, or membership in the cloud VPC you want to expose.

Step 1 — Install the Agent

On the box that will become the appliance, install the agent the normal way. There is no gateway-specific flag or package:

curl -fsSL https://get.meshr.to/install.sh | sh

Then bring it onto the mesh. Using a dedicated setup key named something like gateway keeps appliance enrollments easy to spot in Setup Keys and lets you revoke them independently:

meshr install --setup-key <KEY>

Confirm the peer is online:

meshr status

Once connected, the agent automatically reports the subnets it can see on its non-mesh interfaces (its detected routes). Those subnets show up as suggestions when you create the route in the next step.

Agents can't self-advertise

For security, an agent never advertises a route on its own. It only reports the subnets it can see; every CIDR still requires admin approval in the portal before any traffic flows. Detecting a subnet is not the same as exposing it.

Step 2 — Create the Route and Attach the Appliance

Everything from here is done in the portal as an admin.

1. Go to Routes → New Route.

2. Choose type Routed subnet and enter the CIDR you want to expose — for example 192.168.1.0/24. If the appliance already reported that subnet, pick it from the suggestion chips.

3. Save, then open the route's detail page and click Add Gateway.

4. Select the appliance device and set:

   Field	Meaning
   Priority	Lower wins. Use 100 for a single primary.
   Masquerade	Leave true unless you control the return route at the far end of the LAN.
   Health probe target	A LAN-reachable address the gateway probes to prove the path is up — an ICMP-pingable host or a host:443 TCP target inside the subnet.

5. Save. The appliance starts carrying traffic for the CIDR within seconds.

Step 3 — Verify

On the appliance, the status output should now report a healthy forward path:

meshr status
# ... forward_path_healthy=true

In the portal, the gateway row on the route shows a healthy badge. Finally, from any other mesh peer (with a policy that allows the route), reach a host inside the subnet — e.g. 192.168.1.100 — to confirm end-to-end connectivity.

If the forward path never turns healthy, work through the common operational issues on the Routes page — probe target, forwarding, and masquerade are the usual suspects.

Hardware Suggestions

A gateway appliance should be always on, wired, and have a stable LAN IP. It does not need to be powerful — it needs headroom that nothing else claims.

Box	Good for
Intel N100 mini-PC	Most sites. Dual NIC options, solid forwarding throughput, fanless, low power.
Raspberry Pi 5	Small segments and home labs. Plenty for a single /24 with light traffic.

Either works because the appliance's job is narrow. What matters is that you don't later start running a media server, a build agent, or a database on the same box — that's exactly the contention this setup avoids.

Moving the Role Off a Busy Box

If a gateway currently lives on a machine that also does heavy work, migrate the role to a dedicated appliance:

1. Enroll the new appliance (Steps 1–2 above) and attach it to the same route.
2. Confirm the new appliance shows healthy.
3. On the route, open Gateways, select the old busy device, and click Remove.

Because you add the new gateway before removing the old one, the route keeps serving traffic throughout the swap.

Optional — High Availability

A single appliance is a single point of failure. Attach a second appliance to the same route with equal priority and meshr runs them active/standby: the controlplane elects one healthy primary, and if that primary's heartbeats go stale, the next healthiest gateway takes over automatically. No extra configuration is required beyond adding the second gateway — see Routes → High Availability for how failover and priority work.

Related Concepts

• Routes — the full route, gateway, and HA model
• Setup Keys — issue a dedicated gateway key for appliance enrollment
• Access Policies — grant teams access to the subnet the appliance exposes
• Mesh Overview — how peers and the control plane fit together