Skip to content
WatchTower15 Docs

Upgrades

Keeping a monitoring agent current shouldn’t be a project. WatchTower15 agents learn about new versions from the backend and update themselves, with the same checksum verification used at install.

How version signalling works

Section titled “How version signalling works”

Every authenticated agent response includes an X-Agent-Required-Version header (cached briefly on the agent side to avoid chatter). When the version the backend advertises is newer than the running binary, the agent knows an upgrade is available. This is a pull model — the backend never reaches into your host.

Self-update

Section titled “Self-update”

When an upgrade is signalled, the agent:

  1. Downloads the new binary from the distribution endpoint.
  2. Verifies it against the published X-Content-SHA256 — a mismatch aborts the upgrade and the current version keeps running.
  3. Swaps the binary in place and restarts the service.

Because the download is checksum-verified before it is ever executed, a corrupted or tampered download cannot replace a healthy agent.

You can also trigger an update explicitly:

Terminal window
wt15-server-agent --upgrade

Rolling out across a fleet

Section titled “Rolling out across a fleet”

The pull model makes fleet upgrades naturally gradual — agents update on their own polling cadence rather than all at once — but you stay in control:

What an upgrade never does

Section titled “What an upgrade never does”
  • It never changes the agent’s privilege model — an upgraded agent is still unprivileged with an empty capability set.
  • It never requires inbound access to your host.
  • It never runs as root; the self-update writes only to the agent’s own binary path.

Verifying the running version

Section titled “Verifying the running version”
Terminal window
wt15-server-agent --version
systemctl status wt15-server-agent

If an agent is stuck on an old version, check that it can reach the API (X-Agent-Required-Version is only seen on successful authenticated calls) and that its clock is within ±300 seconds of real time, since request signatures depend on it.

Section titled “Related”