Skip to content

Networking

Two networking features sit at the core of Watchgrid: a WireGuard VPN that encrypts traffic between devices, and Magic DNS that gives every device a .wg hostname.

WireGuard VPN

Every device in your fleet connects to the Watchgrid server through a WireGuard VPN tunnel. This creates a private, encrypted network where all devices can communicate directly.

Network Architecture

Component Address
Subnet 100.64.0.0/10 (RFC 6598 CGN space)
Default tenant 100.64.1.0/24
Server gateway 100.64.1.254
Device IPs Allocated from 100.64.1.1 upward
DNS server 100.64.1.254:53
WireGuard port 51820/udp

How Devices Connect

  1. The provisioning script generates a WireGuard key pair on the device
  2. The device registers its public key with the server
  3. An admin approves the device and assigns a VPN IP
  4. The server adds the device as a WireGuard peer
  5. The device configures its WireGuard interface with the server's public key and endpoint

Multi-Tenant Networking

Each tenant gets its own /24 subnet within the 100.64.0.0/10 space:

  • Default tenant: 100.64.1.0/24 (up to 253 devices)
  • Additional tenants: 100.64.2.0/24, 100.64.3.0/24, etc.
  • Up to 16,384 tenant subnets available

Tenants are isolated by default — devices in one tenant cannot reach devices in another.

Verifying VPN Connectivity

On any provisioned device:

# Check WireGuard status
sudo wg show

# Ping the server
ping 100.64.1.254

# Ping another device by VPN IP
ping 100.64.1.3

WireGuard over HTTPS (UDP-blocked networks)

WireGuard normally rides raw UDP on port 51820. Many corporate and cloud networks block outbound UDP while still allowing outbound TCP 443 (ordinary HTTPS). For those environments, Watchgrid can carry the WireGuard tunnel inside a TLS/WebSocket connection on 443 instead — the same port and path the agent already uses to register.

How it works: the agent's WireGuard packets are wrapped in a WebSocket to the server's /api/wg/tunnel relay, which unwraps them to the server's local wg0 socket. WireGuard's encryption and key exchange are unchanged — only the transport differs. This is the same approach as Tailscale's DERP relay and Talos's "WireGuard over HTTP/2".

  • Scope: currently available for cluster-agents (K3s/K8s clusters). It is opt-in, per cluster.
  • Enable it: tick "Tunnel WireGuard over HTTPS (443)" in the Cluster Manifest section when onboarding the cluster (see Clusters). This sets WATCHGRID_WG_OVER_HTTPS=true in the generated manifest.
  • Trade-off: tunneling UDP inside TCP/TLS adds overhead (TCP-over-TCP) and the MTU is reduced to 1280. This is fine for management traffic, which is the intended use. Prefer plain UDP when the network allows it.
  • Verifying: on the server host, wg show shows a latest handshake and transfer counters for the cluster's peer even though UDP 51820 is unreachable from the cluster, and the cluster's tunnel IP becomes pingable.

Magic DNS

Every device that connects to the VPN automatically gets a DNS name under the .wg top-level domain. The Watchgrid server runs a DNS server at 100.64.1.254:53 that resolves these names.

Automatic Records

When a device with hostname pi-sensor-1 connects, it's immediately reachable at:

pi-sensor-1.wg

Examples:

ssh admin@pi-sensor-1.wg
curl http://my-service.wg:8080/api/status
ping gateway-london.wg

Custom DNS Records

You can create additional DNS records through the web UI:

  1. Go to System → DNS
  2. Click Create DNS Record
  3. Fill in:
  4. Hostname — e.g., database (becomes database.wg)
  5. IP Address — the WireGuard IP to resolve to
  6. Record Type — A, AAAA, or CNAME
  7. The record is immediately active

Managing Records

The DNS page shows a table of all custom records with:

  • Hostname
  • IP address
  • Record type
  • Delete action

Records are scoped to the current tenant.

DNS Configuration

Setting Default Description
WATCHGRID_MAGIC_TLD wg Top-level domain for Magic DNS
Upstream DNS 8.8.8.8, 1.1.1.1 Forwarding for non-.wg queries
DNS port 53 Standard DNS port

The DNS server updates in real-time as devices connect and disconnect — no manual intervention needed.

Connecting to the Registry

The built-in Docker registry is accessible via Magic DNS after joining the VPN:

# Before VPN (from the server host)
docker push localhost:5000/myapp:latest

# After VPN (from any device)
docker push registry.wg:5000/myapp:latest
docker pull registry.wg:5000/myapp:latest

K3s devices pull from registry.wg:5000 automatically for images tagged with that prefix.