Skip to content
WatchTower15 Docs

Server agent overview

The wt15-server-agent is a single, statically-linked Go binary that collects host telemetry, system information and logs, and forwards them to WatchTower15. Its defining characteristic is its security posture: it installs and runs with no root, no sudo, and not one Linux capability — a bar no mainstream monitoring agent clears by default.

What the agent does

Section titled “What the agent does”
  • Reports host telemetry every 60 seconds (CPU, memory, disk, network, load).
  • Reports a fuller system-information snapshot every 300 seconds (OS, kernel, per-disk and per-interface detail).
  • Ships logs — tails profile-defined files and the systemd journal, and forwards them for search.
  • Self-identifies with tags collected from cloud, Docker and Kubernetes metadata (see auto-tagging).
  • Enrolls itself using an organisation token and keeps its configuration in sync with a server profile.

The zero-privilege model

Section titled “The zero-privilege model”

The installer creates a dedicated, login-less wt15-agent service user and runs the binary under a hardened systemd unit. The relevant directives:

# /etc/systemd/system/wt15-server-agent.service (excerpt)
[Service]
User=wt15-agent
NoNewPrivileges=yes
ProtectSystem=strict
CapabilityBoundingSet=
  • NoNewPrivileges=yes — the process and its children can never gain privileges through setuid/setgid binaries.
  • ProtectSystem=strict — the entire filesystem is read-only to the agent except its own state directory.
  • Empty CapabilityBoundingSet — the process holds zero Linux capabilities, not even CAP_NET_BIND_SERVICE.

Everything the default agent collects comes from world-readable kernel interfaces (/proc, /sys) plus the adm and systemd-journal groups the service user belongs to for log reading. Capabilities that would require more — filesystem integrity monitoring, raw packet capture, per-process inspection of other users’ processes — are intentionally out of scope for the default agent and, where offered, are delivered by separate narrowly-scoped helpers rather than by widening the main agent’s privileges.

How the agent talks to the backend

Section titled “How the agent talks to the backend”

The agent makes outbound HTTPS only — there are no inbound ports on your host. Every request carries an HMAC signature so the backend can authenticate it without a session:

Header Purpose
X-Agent-Id the server’s UUID
X-Agent-Timestamp Unix time; must be within ±300 s of the server clock
X-Agent-Signature HMAC-SHA256 over the id, timestamp and body hash, keyed by the agent secret

Two response headers drive self-management: X-Agent-Config-Etag signals a changed profile configuration, and X-Agent-Required-Version signals an available upgrade.

Lifecycle at a glance

Section titled “Lifecycle at a glance”
  1. Install — the one-line installer downloads the binary (verified against a published X-Content-SHA256), creates the service user, and writes the unit.
  2. Enroll — the agent calls the enrollment endpoint with your organisation token, optionally collects self-reported tags, and stores its credentials locally.
  3. Run — it pushes telemetry and system information on their intervals, ships logs, and polls its configuration etag.
  4. Upgrade — when the backend advertises a newer required version, the agent updates itself (see Upgrades).

In this section

Section titled “In this section”