Watchflare Agent overview
Lightweight Go daemon that collects system metrics, package inventory, and container stats. Runs as an unprivileged user with outbound-only gRPC/TLS.
The agent is a lightweight Go daemon installed on each host you want to monitor. It runs as an unprivileged system user and communicates outbound only, opening no inbound ports on the monitored host.
What it does
The agent runs these loops independently:
| Loop | Interval | What it does |
|---|---|---|
| Heartbeat | 5 s | Sends a presence ping with current IP addresses |
| Metrics | 30 s | Collects system metrics and sends them to the Hub |
| Package inventory | 60 s after start, then daily at 03:00 | Scans installed packages, sends delta to the Hub |
| Service inventory | 60 s after start, then every 15 min | Catalogs systemd units (Linux with systemd only) |
| Service health | 30 s | Reports live systemd service state (Linux with systemd only) |
What it collects
| Category | Metrics |
|---|---|
| CPU | Usage %, iowait, steal (VMs) |
| Memory | Used, available, buffers, cached, swap |
| Disk | Total, used, read/write throughput |
| Network | Inbound/outbound bandwidth |
| Temperature | CPU and other temperature sensors (storage, power management, etc.) on physical hosts |
| System | Uptime, load average (1/5/15 min), process count |
| Containers | Per-container CPU, memory, network (Docker/Podman, opt-in) |
| Services | systemd unit inventory and live state on Linux hosts |
| Packages | Installed packages, versions, and outdated detection across ~30 supported package managers |
The agent adapts automatically to its environment:
| Environment | Skips |
|---|---|
| Application container (Docker, Podman) | Disk, disk I/O, network, swap, temperature |
| System container (LXC) | Nothing, monitored like a full host |
| Virtual machine | Temperature sensors |
| Physical host | Nothing, full collection |
How it works
WAL (Write-Ahead Log): Metrics are appended to a local file before being sent. If the Hub is unreachable, metrics accumulate in the WAL and are replayed in order on the next successful connection. Metrics are not lost during brief outages. By default the WAL stores up to 10 MB of data, and once full the oldest records are dropped. This limit is adjustable via wal_max_size_mb in agent.conf.
Security: Every gRPC request is signed with HMAC-SHA256 (agent ID + timestamp + payload). The Hub rejects requests outside a ±5 minute timestamp window. All communication is TLS 1.3, and the agent pins the Hub’s CA certificate at registration.
Minimal footprint: The agent runs as the unprivileged watchflare system user (Linux) or the invoking user (macOS via Homebrew). It has no shell, a non-writable home directory (/var/empty), and write access only to its own data directory.
System requirements
Linux
- systemd (Ubuntu 18.04+, Debian 10+, RHEL/CentOS 7+, Fedora 30+, Amazon Linux 2+, Arch Linux)
curlorwgetsudoaccess for installation
macOS
- macOS 11 (Big Sur) or later
- Intel or Apple Silicon (M1/M2/M3/M4)
- Homebrew