TheWatcher is a platform agnostic server/endpoint monitoring platform trying to be better than the complex and ugly solutions that are currently out there.
It's been created in C++20 with deployable user-space agents, a ZeroMQ/LibSodium data plane, a SQLite-backed server (PostgreSQL to come), and a React dashboard.
Agents initiate all network connections. They enroll with the server, submit
metrics periodically, send heartbeats, and request current runtime config after
each metrics submission. The server receives data, queues commands/config
responses over the existing agent connection, exposes the REST API, and marks
agents offline when last_seen exceeds the configured threshold.
Build everything from a Visual Studio developer PowerShell prompt:
.\scripts\setup-build-env.cmd -SkipWsl
.\meson-build.cmd(On Linux: ./scripts/setup-build-env-linux.sh then
meson setup builddir-release --buildtype=release && meson test -C builddir-release --print-errorlogs.
On BSD: ./scripts/setup-build-env-bsd.sh and the same meson commands.)
Start the server in foreground mode:
.\builddir-release\server\TheWatcherServer.exe --config C:\ProgramData\TheWatcher\server.jsonCreate or edit the agent config:
THEWATCHER_SERVER=127.0.0.1
Start the agent in foreground mode:
.\builddir-release\agent\TheWatcherAgent.exe --config C:\ProgramData\TheWatcher\TheWatcherAgent.confRun the dashboard during development:
cd dashboard
npm.cmd install
npm.cmd run devOpen http://127.0.0.1:5173, approve the pending agent on the Pending
Enrollments page, and wait for metrics to arrive. The approved enrollment
response gives the agent the server public key plus a pinned fingerprint, which
the agent writes back to TheWatcherAgent.conf.
- Installation: build outputs, install locations, Windows service installation, non-Windows supervision.
- Configuration: every server and agent config option, default config paths, generated files, and command-line overrides.
- Running: foreground start/stop, service start/stop, dashboard startup, enrollment workflow, and health checks.
- Architecture: server, agent, common protocol, dashboard, storage, and command/config data flow.
- Dashboard: UI behavior, API contract, and development commands.
- Development: repository layout, build/test targets, coding workflow, and how to extend the product end to end.
- Progress Tracker: alpha, beta, and v1 production release Done/TODO tracking.
- Collector Contract: how collectors populate
SystemMetricsand what to change when adding a collector. - Build Environment: Windows, Linux, and BSD toolchain setup for the Meson build.
- Logging: log file locations and startup diagnostics.
- Service Installation: focused Windows service command reference.
meson compile -C builddir-release TheWatcherServer TheWatcherAgent
meson test -C builddir-release config_test store_test
meson test -C builddir-release server_agent_integration_testThe dashboard is built with npm:
cd dashboard
npm.cmd run build
npm.cmd test

