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

Every authenticated agent response includes an X-Agent-Required-Version header: the latest released agent version, which WatchTower15 caches for up to five minutes. When it differs from the running binary’s version, the agent knows an upgrade is available. This is a pull model — the backend never reaches into your host.

Self-update

When an upgrade is signalled, the agent:

1. Downloads the new binary from the distribution endpoint, to a staging file beside the running one.
2. Requires the X-Content-SHA256 header on the download and checks the bytes against it. A response with no checksum, or bytes that do not match it, is refused, and the current version keeps running.
3. Reads the version from the downloaded binary itself (its build information, not from what the server claims) and requires it to be higher than the running one. An equal or lower version is refused.
4. Swaps the binary in place and restarts the service.

Because the download is checksum-verified before it is ever executed, a corrupted download cannot replace a healthy agent. The checksum comes from the same server as the binary, so it proves the download is whole; it does not prove who published the release.

The agent upgrades right after WatchTower15 has accepted a telemetry sample (or a heartbeat, on a server whose telemetry is switched off), and flushes the data it keeps on the host to disk before it restarts. An upgrade therefore keeps that data: the new version sends whatever was still waiting.

You can also upgrade a host explicitly by re-running the installer in upgrade mode, as root. It downloads the latest release, verifies it the same way (no checksum, or a version lower than the installed one, stops it before anything is replaced), replaces the binary and restarts the service, keeping the host’s existing configuration (including any proxy):

curl -fsSL https://api.watchtower15.com/api/agent/install-script | sudo sh -s -- --upgrade

On a host behind a proxy, add -x <proxy> to that curl, as for the install; the upgrade itself reuses the proxy already in the agent’s configuration. Upgrades, automatic or run this way, download from api.watchtower15.com, so a host behind an IP allow-list needs nothing beyond the three addresses it already allows (see the Restricted egress tab under Install).

An upgrade run this way also installs the uninstall unit, which a host installed before agent 1.1.48 does not have. It is the one way such a host gets its agent removed by itself when its server is deleted; one whose agent already asked for its removal has it removed within seconds.

--upgrade runs no telemetry check: the host is a server already. The running agent repeats the check on its own and reports it, on the Agent card of the server’s Info tab and in --status. The check’s own unit is written only by an install; an upgrade adds none, so a host installed before it gets the unit by running the installer again.

When an agent refuses an upgrade

An agent never moves to a lower version. A fix for a bad release ships as a newer release, never as an older one served again. When an agent refuses a download it removes the staging file, leaves the running binary untouched, and does not try the same advertised version again for six hours. A refusal has one of four reasons:

Reason	What it means
The server sent no checksum	The download carried no X-Content-SHA256. A proxy that strips that header causes this: the host refuses every upgrade, and only that host.
The checksum did not match	The bytes are not the ones the checksum describes, as after a corrupted download.
The binary is not newer than the running agent	The advertised or downloaded version is equal to or lower than the one running.
The binary carries no version	The version could not be read from the binary’s own build information.

The last refusal shows on the server’s Info tab, in the Security collection card, as Last refused update: the refused version and the reason. The six-hour wait does not stop the agent reporting; it keeps collecting and sending data as before.

The software bill of materials

Every agent release is published with a software bill of materials (SBOM), a CycloneDX JSON list of what the binary contains. Download it for either architecture (amd64 or arm64):

curl -fsSL -D headers.txt -o sbom.json "https://api.watchtower15.com/api/agent/binary?arch=amd64&sbom=1"
grep -i '^x-content-sha256' headers.txt
sha256sum sbom.json

The two hashes must be equal. The X-Agent-Binary-Version header of the same response names the release the SBOM belongs to. The checksum comes from the same server as the file, so, as for the binary, it confirms a whole download rather than who published it.

Rolling out across a fleet

There is one advertised version for every agent: the latest release. Each agent picks it up the next time it contacts WatchTower15 after the release, so a fleet converges within minutes, with no orchestration. There is no per-profile or per-host version pinning.

What an upgrade never does

• It never changes the agent’s privilege model. The self-update replaces only the binary; the systemd unit, its service user and its two capabilities stay exactly as installed. Only --upgrade, run as root, adds the uninstall unit; the self-update never does.
• It never requires inbound access to your host.
• Installed as a service, the automatic self-update never runs as root: it runs as the agent’s service user and writes only to the agent’s own directory, /var/lib/wt15-server-agent.

Verifying the running version

The agent logs its version on its start-up line, and the server’s page in the dashboard shows it as Version in the Agent card, on its Info tab (a refused update is on the same tab, above):

grep 'agent running' /var/log/wt15-server-agent.log | tail -1
systemctl status wt15-server-agent

The start-up line also says where the agent’s configuration came from: config=fetched (from WatchTower15), config=cache (etag=…, saved … ago) (the profile kept on the host, when WatchTower15 could not be reached), or config=none (no profile: none was kept and WatchTower15 could not be reached, or the server is not being monitored, for example while it waits for approval). After a normal restart it reads config=fetched, preceded by the configuration the agent started from and WatchTower15’s confirmation:

agent config applied (source=cache, etag=…, saved=… (… ago), telemetry=15s, …)
agent config confirmed by WatchTower15 (etag=…): the cached profile is current
agent running v… (heartbeat=30s, telemetry=15s, …, config=fetched, proxy=none)

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). Request signatures depend on the clock, and WatchTower15 refuses a server whose clock is more than 300 seconds off. The agent corrects its own clock when it is more than 290 seconds off WatchTower15’s, before that limit, and writes an error line asking for the server’s time to be fixed (see When WatchTower15 cannot be reached).

Related

• Installation — the same checksum verification at install.
• Configuration reference — proxy and endpoint settings.
• Fleet & profiles — staging rollouts.