Skip to content

Networking

Watchgrid provides two integrated networking features: WireGuard VPN for encrypted connectivity and Magic DNS for automatic name resolution.

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

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.