Skip to content

Provisioning Devices

Provisioning adds a device to your Watchgrid fleet. The device gets a WireGuard VPN connection, the Watchgrid agent, Magic DNS resolution, and SSH CA trust — all in one step.

Supported Platforms

  • Raspberry Pi (all models, including Pi 5)
  • Ubuntu Server 20.04+
  • Debian 11+
  • Any Linux system with systemd and bash

Supported architectures: amd64, arm64, arm (armhf/armv7).

One-Line Provisioning

Run this command on the device you want to add:

curl -s http://YOUR_SERVER:8080/provision.sh | sudo bash -s http://YOUR_SERVER:8080

Replace YOUR_SERVER with your Watchgrid server's IP address or domain name.

Options

Flag Description
--k3s Also install K3s (lightweight Kubernetes)
--update Only update the agent binary (skip VPN setup)
--token TOKEN Onboarding token for tenant assignment

Examples:

# Basic provisioning
curl -s http://10.0.0.100:8080/provision.sh | sudo bash -s http://10.0.0.100:8080

# With K3s installation
curl -s http://10.0.0.100:8080/provision.sh | sudo bash -s http://10.0.0.100:8080 --k3s

# Update agent only
curl -s http://10.0.0.100:8080/provision.sh | sudo bash -s http://10.0.0.100:8080 --update

# With onboarding token (assigns to specific tenant)
curl -s http://10.0.0.100:8080/provision.sh | sudo bash -s http://10.0.0.100:8080 --token abc123

What Provisioning Does

The provisioning script performs these steps automatically:

  1. Detects architecture — amd64, arm64, or arm
  2. Downloads the agent binary from your server (correct architecture)
  3. Generates WireGuard keys (or reuses existing ones if reprovisioning)
  4. Registers with the server — sends device info and public key
  5. Configures WireGuard — sets up the VPN tunnel to the server
  6. Installs the agent as a systemd service (watchgrid-agent)
  7. Configures SSH CA trust — downloads the CA public key for certificate-based SSH
  8. Optionally installs K3s with the --k3s flag
  9. Runs provisioning profiles — executes any tag-matched scripts (see Provisioning Profiles)

Approving Devices

After a device is provisioned, it appears in the Dashboard as a pending authorization:

  1. Go to the Dashboard
  2. Look for the Pending Agent Authorizations section at the top
  3. You'll see the device ID and its WireGuard public key
  4. Click Approve & Assign IP to admit the device to the VPN
  5. The device gets a VPN IP (e.g., 100.64.1.x) and becomes reachable

Denied devices are rejected and cannot connect to the VPN.

Onboarding via the Web UI

You can also onboard devices through the web interface:

  1. Go to Devices → click Onboard Device
  2. The modal shows a provisioning command with your server URL
  3. Copy the command and run it on the target device
  4. Onboarding tokens can lock a device to a specific tenant

Reprovisioning

If your server is reinitialized or you need to refresh a device's connection:

curl -s http://YOUR_SERVER:8080/provision.sh | sudo bash -s http://YOUR_SERVER:8080

Running the same provisioning command again:

  • Reuses existing WireGuard keys (does not generate new ones)
  • Updates the agent binary to the latest version
  • Re-registers with the server
  • Preserves the device's identity

Raspberry Pi 5 Note

On a Raspberry Pi 5 with K3s (--k3s flag), the provisioning script detects if cgroups need to be enabled. If so, it updates /boot/firmware/cmdline.txt and reboots the device automatically. After reboot, run the provisioning command again to complete the K3s installation.

Verifying a Provisioned Device

On the device, check the agent service:

sudo systemctl status watchgrid-agent
sudo journalctl -u watchgrid-agent -f

Verify VPN connectivity:

# Check WireGuard interface
sudo wg show

# Ping the server through the VPN
ping 100.64.1.254

Verify Magic DNS:

# Resolve another device by hostname
nslookup other-device.wg 100.64.1.254

Troubleshooting

Problem Solution
Device stuck on "pending" Check that WG_SERVER_ENDPOINT is reachable from the device
WireGuard handshake fails Verify port 51820/udp is open on the server
Agent won't start Check logs: journalctl -u watchgrid-agent -f
DNS not resolving .wg Ensure DNS = 100.64.1.254 is in the device's WireGuard config
Architecture mismatch The script auto-detects arch; verify with uname -m