Network

Manage WireGuard mesh subnets and monitor peer connections across your device fleet.

Overview

Umoo's network plugin creates an overlay mesh network using WireGuard. Devices automatically:

1. Generate a WireGuard key pair on first enrollment
2. Receive an allocated IP address within the subnet CIDR
3. Get peer configurations pushed via the device shadow
4. Establish encrypted tunnels to all other peers in the subnet

The mesh is fully peer-to-peer — no central VPN gateway is required (though relay devices can be designated for NAT traversal).

Prerequisites

The WireGuard plugin must be enabled for your tenant. A super admin can enable it from Settings → Plugin Config.

The umoo-agent on each device must have WireGuard support compiled in or the wg / wg-quick tools available.

Networks (Subnets)

Navigate to Network → Networks to manage WireGuard subnets.

Creating a Network

1. Click + Create Network.
2. Enter a Name (e.g. prod-mesh).
3. Enter a CIDR (e.g. 10.100.0.0/24). Devices in this subnet will receive IPs from this range.
4. Set a Listen Port (default 51820). All devices in this network listen on this UDP port.
5. Click Create.

The network is created immediately. Devices enrolled in the network will have peer configs distributed via shadow sync.

Deleting a Network

Click the ⋮ menu on a network row → Delete. This removes the network and all peer allocations. WireGuard interfaces on devices will be torn down on next shadow sync.

Peers

Navigate to Network → Peers to see all WireGuard peer enrollments across all networks.

Columns:

• Device — device name (links to device detail)
• Network — which subnet this peer belongs to
• Allocated IP — the IP address assigned within the CIDR
• Public Key — the device's WireGuard public key
• Endpoint — the device's public IP and port (as observed by the platform)
• Last Handshake — time of the last successful WireGuard handshake

Auto-enrollment

When a device comes online and the WireGuard plugin is enabled, the agent:

1. Generates a WireGuard key pair (if not already present)
2. Reports its public key and endpoint in the shadow reported state
3. The backend allocates an IP and pushes peer configs to all devices in the network

No manual peer management is required.

Relay Devices

A relay device acts as a STUN/TURN server for devices behind symmetric NAT. To designate a device as a relay, set the wireguard.relay key in its desired shadow state:

{
  "wireguard": {
    "relay": true
  }
}

Relay devices are included in all peer lists with their public endpoint so other devices can route through them.

Troubleshooting

Device not getting a peer IP:

• Check that the WireGuard plugin is enabled in tenant plugin config.
• Verify the device is online and its shadow is syncing.
• Check device events for WireGuard plugin errors.

Handshakes failing:

• Ensure UDP port 51820 is open on the device firewall.
• Check if the device is behind symmetric NAT (use a relay).
• Verify the device's public key matches what is in the Peers list.

Peer list not updating:

• Shadow sync may be delayed. Wait 30 seconds and refresh.
• Check device logs for WireGuard plugin errors.