Skip to content

Agents

Watchgrid ships three different agents. Each is a small Go binary that connects a specific kind of workload to the Watchgrid server: a Linux host, a whole Kubernetes cluster, or a single container.

Agent Runs on Device type Purpose
agent Physical or virtual Linux hosts device / admin-device Full host management: WireGuard, heartbeats, terminal, optional K3s
cluster-agent One pod per Kubernetes cluster cluster Registers a whole K3s/Kubernetes cluster, proxies kubectl, reports cluster metrics
service-agent Sidecar in a Kubernetes pod or Docker Compose service service Lightweight per-workload reporter for individual services

All three heartbeat to the same server API and appear in the Devices page, distinguished by their Type column.

agent (device agent)

The default agent. This is what provision.sh installs on Raspberry Pis, Ubuntu servers, and Linux workstations.

Source: agent/ (in the Watchgrid repository)

Responsibilities:

  • Generates / reuses WireGuard keys and brings up wg0 on the device
  • Long-polls the server for commands (25 s) and sends a heartbeat (/api/heartbeat) after each poll cycle — roughly every 25–30 seconds — with system stats (CPU, memory, disk, temperature, uptime)
  • Executes remote commands dispatched from the server
  • Provides WebSocket terminal access (agent/terminal.go)
  • Optionally manages a local K3s installation
  • Reports agent version so the server can flag update_available

Device types it registers as:

  • device — physical / virtual machine (default)
  • admin-device — a workstation or laptop added for admin access

Set via the WATCHGRID_DEVICE_TYPE environment variable.

Install:

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

See Provisioning Devices for the full flow.

cluster-agent

A single agent that represents an entire Kubernetes cluster as one device in Watchgrid. Deploy it once per cluster (typically as a Deployment with one replica) and it registers the cluster, brings up the cluster's WireGuard tunnel, and proxies Kubernetes operations back to the Watchgrid server.

Source: cluster-agent/ (in the Watchgrid repository)

Responsibilities:

  • Registers as device_type = cluster
  • Sends a heartbeat every 10 seconds with cluster-level stats
  • Establishes WireGuard connectivity from inside the cluster (TUN device) — see cluster-agent/wireguard.go and cluster-agent/tun_linux.go
  • Provides a Kubernetes API proxy so the Watchgrid server can run kubectl-style operations against this cluster
  • Executes cluster-scoped commands dispatched from the server (cluster-agent/commands.go)
  • Reports node count, pod count, and cluster-level metrics via the Kubernetes metrics API
  • Exposes cluster DNS information (cluster-agent/dns.go)

When to use it:

  • You have a full multi-node Kubernetes or K3s cluster and want it managed as a single entity in Watchgrid
  • You want to run kubectl, deploy apps, or open terminals against cluster pods from the Watchgrid UI
  • You do not want a per-node agent on every worker

When not to use it:

  • For a single-node K3s on a Pi or server, the regular agent with --k3s is simpler
  • For a single containerized service without a full cluster, use the service-agent

See Clusters for deployment details.

service-agent

A minimal sidecar agent intended to run alongside a single containerized workload — either as a Kubernetes sidecar container or as an extra service in a Docker Compose stack. It lets a specific service show up in Watchgrid with heartbeats and WireGuard connectivity, without deploying the full host agent or claiming an entire cluster.

Source: service-agent/ (in the Watchgrid repository)

Responsibilities:

  • Registers as device_type = service
  • Sends heartbeats every 5 seconds with basic container stats
  • Maintains a WireGuard tunnel for the pod (reconciled every 30 seconds)
  • Lightweight — no K3s management, no host-level commands

When to use it:

  • A single containerized app (for example nzyme, a scanner, or a custom service) that should appear in Watchgrid as its own device
  • Kubernetes workloads running outside a Watchgrid-managed cluster that still need VPN + monitoring
  • Docker Compose stacks where you want one service registered in Watchgrid without installing the host agent
  • Anywhere the full agent is overkill and a cluster-agent doesn't apply

Deployment options:

  • Kubernetes sidecar — add the service-agent container to your pod spec. See the example manifests in the examples/ directory of the repository:
    • mock-service-with-watchgrid-agent.yaml
    • nzyme-with-watchgrid-service-agent.yml
    • kismet-with-watchgrid-agent.yaml
  • Docker Compose — add it as an extra service alongside your app. A reference stack lives at docker-compose.service-agent.yml in the repository.

Choosing the right agent

Is it a Linux host (Pi, VM, server, workstation)?
  └─ Use  agent           (device_type: device / admin-device)

Is it a full Kubernetes / K3s cluster you want to manage as one unit?
  └─ Use  cluster-agent   (device_type: cluster)

Is it a single containerized service (K8s pod or Docker Compose)?
  └─ Use  service-agent   (device_type: service)

All three are built from the same monorepo and versioned together — see the Changelog and ./scripts/version.sh to verify alignment.