Skip to content

Watchgrid Documentation

Unified Device Management for Raspberry Pi, Ubuntu Servers & Linux Systems

Watchgrid combines WireGuard VPN, Magic DNS, Kubernetes orchestration, a private Docker registry, SSH Certificate Authority, and web-based device management into a single control plane.

What is Watchgrid?

Managing distributed edge devices — Raspberry Pis, Ubuntu servers, IoT gateways — typically means juggling half a dozen tools: a VPN for connectivity, a DNS service for discovery, a certificate authority for SSH, a container registry for images, an orchestrator for workloads, and a dashboard to tie it all together.

Watchgrid replaces that entire stack with one platform:

Capability What It Does
WireGuard VPN Encrypted mesh networking across all devices (100.64.0.0/10)
Magic DNS Automatic .wg domain resolution so devices find each other by name
SSH Certificate Authority Short-lived SSH certificates — no more managing authorized_keys
Private Docker Registry Built-in container registry at registry.wg:5000
K3s / Kubernetes Deploy and manage containerized workloads on any device
Web Dashboard Real-time monitoring, terminal access, and fleet management

Quick Start

Get a full Watchgrid stack running in under 5 minutes:

git clone https://github.com/RDG88/watchgrid.git
cd watchgrid
docker compose up -d

Then open http://localhost:3000 and log in:

  • Username: admin
  • Password: watchgrid

See the Getting Started guide for full setup instructions.

How It Works

┌─────────────────────────────────────────────────┐
│                 Watchgrid Server                 │
│  ┌──────────┐ ┌──────┐ ┌─────┐ ┌────────────┐  │
│  │ REST API  │ │ DNS  │ │ VPN │ │  SSH CA    │  │
│  │  :8080    │ │ :53  │ │:518 │ │            │  │
│  └──────────┘ └──────┘ └─────┘ └────────────┘  │
│  ┌──────────┐ ┌──────────────┐ ┌────────────┐  │
│  │ Registry │ │  PostgreSQL  │ │  Frontend  │  │
│  │  :5000   │ │    :5432     │ │   :3000    │  │
│  └──────────┘ └──────────────┘ └────────────┘  │
└─────────────────────────────────────────────────┘
         │ WireGuard VPN Tunnel (100.64.x.x)
    ┌────┴────┬──────────┬──────────┐
    ▼         ▼          ▼          ▼
 ┌──────┐ ┌──────┐ ┌──────┐ ┌──────────┐
 │ Pi 1 │ │ Pi 2 │ │ VM 1 │ │ K8s Node │
 │agent │ │agent │ │agent │ │ cluster  │
 └──────┘ └──────┘ └──────┘ │  agent   │
                             └──────────┘
  1. Devices run the Watchgrid agent, which connects via WireGuard VPN
  2. Server manages all VPN peers, DNS records, certificates, and workloads
  3. Dashboard provides real-time visibility and control over your fleet

Documentation Sections

Section Description
Getting Started Installation, first login, initial configuration
Provisioning Devices Adding Raspberry Pis, servers, and VMs to your fleet
Dashboard Real-time fleet overview, map, device cards
Device Management Inventory, search, bulk operations, terminal access
Kubernetes Clusters Adding and monitoring external K8s clusters
Applications Deploying containerized workloads to devices
App Metadata Defining app metadata and configurable fields
K3s Administration Managing pods, deployments, services on K3s nodes
Networking WireGuard VPN and Magic DNS
SSH Certificates SSH Certificate Authority setup and usage
Docker Registry Private container registry
User Management Users, roles, two-factor authentication
Multi-Tenancy Tenant isolation and firewall policies
Provisioning Profiles Automated device setup with tag-based scripts
Audit Log Tracking administrative actions
Licensing Editions, activation, and limits
Production Deployment Deploying Watchgrid for production use
API Reference REST API overview

Getting Help

Watchgrid B.V. — The Netherlands