Agent updates

New installs pin the current Linux agent. v0.2.2 can self-update; v0.1.0 cannot. This page covers opt-out and when to re-run the installer.

Updated Nov 7, 2026

On this page

Version behavior
How auto-update works (v0.2.2)
Opt out
Confirm after an update

New installs from the current installer pin v0.2.2. Check the binary on the host:

/usr/local/bin/cloudstats-agent version

Version behavior#

Installed agent	Self-update	What to do
v0.1.0	No. That release does not check for newer agent versions.	Re-run the current installer with a new one-time command from the CloudStats UI.
v0.2.0 or v0.2.1	The agent can stage an update, but those units did not persist the release URL.	Re-run the current installer once so the service starts with `--release-base-url`.
v0.2.2 and later installer units	Yes. The running agent periodically checks CloudStats release metadata over HTTPS.	Leave the service running, or opt out as below.

v0.2.2 is the first installer pin that bakes the release URL into ExecStart. Hosts still on v0.1.0 / v0.2.0 / v0.2.1 need that one installer re-run.

There is no upgrade-only installer mode. Re-running install always enrolls with the token in that script. See Reinstall and server identity.

How auto-update works (v0.2.2)#

On a v0.2.2 unit the agent checks about once per hour (first check after about 30 seconds). When the published latest pointer is a newer canonical vMAJOR.MINOR.PATCH than the running binary, it stages /var/lib/cloudstats/update-ready. A root systemd path unit then runs /usr/local/lib/cloudstats/update.sh, which:

Downloads that version’s binary and SHA256SUMS over HTTPS
Verifies the checksum (there is no bypass)
Replaces /usr/local/bin/cloudstats-agent
Restarts cloudstats-agent.service

Guards that matter on the host:

HTTPS only; checksum is the trust anchor
Newer versions only (no downgrade, and no install of latest / dev / prerelease strings)
Downloads over 128 MiB are rejected
If the new binary does not stay active, the helper rolls back to .prev and records the failed version in /var/lib/cloudstats/update-failed so it is not retried
The sandboxed agent process does not write /usr/local/bin

Opt out#

Create this file as root to skip self-update:

text

/etc/cloudstats/no-self-update

When that file exists, an update helper run clears the trigger and leaves the binary unchanged.

Confirm after an update#

/usr/local/bin/cloudstats-agent version
systemctl status cloudstats-agent
journalctl -u cloudstats-agent