Automatic updates

What automatic updates are

From Machine Agent v0.4.0 a server can replace its own agent binary when the platform offers a newer release, instead of someone re-running the installer on every host. It is in parity with Scout v0.5.0 — identical sequence, identical safety checks — so a mixed fleet of servers and workstations updates the same way and is watched on the same screen.

It is off by default and stays off until two independent switches are both on. Doing nothing keeps every agent exactly where it is.

Two switches, and both must be on

Switch	Who sets it	Where	Default
Release channel — the platform may offer this org an update	An admin of your organization (a role with the Inventory manage permission)	Inventory → Agents → "Auto-update", on the Machine Agent card	No policy row at all — pinned, disabled, 0%
Server opt-in — this host may replace its own binary	Whoever owns the host's configuration	auto_update = true under [inventory] in config.toml	false

Neither one alone does anything: a mis-click in the console cannot move a server that has not opted in, and a server that has opted in does not move until the console says so. With no policy row — the shipped state for every organization — nothing is offered at all.

Turning it on

1 — Opt the servers in

The key lives in the [inventory] section of config.toml (/opt/verops/config.toml on Linux, C:\Program Files\VerOps\config.toml on Windows), alongside the other inventory settings:

[inventory]
enabled = true
enrollment_token = "sce_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# Allow THIS server to replace its own binary when the platform offers a
# newer release. Off unless you write this line.
auto_update = true

Restart the service afterwards — the config is read at startup: sudo systemctl restart verops-machine-agent, or sc stop VerOpsMachineAgent & sc start VerOpsMachineAgent.

2 — Enable a channel for your fleet

Open Inventory → Agents, click Auto-update, and on the Machine Agent card pick a channel, set a rollout percentage, switch the policy to enabled, and save. Servers pick the offer up on their next config poll (default 60 s), not instantly.

Channels and rollout percentage

Channel	Target it resolves to
Pinned	The version you name, or — with none named — the agent's own version, which can never move.
Stable	The release marked current in Inventory → Agents → Release notes. The right default for servers.
Beta	The newest published release, including one not yet marked current. Point a pilot group at this, not a production fleet.

Movement is forward only — equal is the steady state and older is refused, so pinning back stops further updates rather than pushing an old binary out. The rollout percentage decides how much of the fleet is offered the update, and the split is computed from each machine's stable identity, so the same server always falls on the same side of it: raising the percentage adds servers and never reshuffles the ones already done. A policy can also be attached to an Inventory Group, which wins over the org default for its members; where several apply, the most conservative one does.

What happens on the server

Every step fails closed — when anything is not exactly as expected the agent aborts, leaves the installed binary untouched, and reports:

1. the offered version must be strictly newer than the running one;
2. the artifact URL must be on the same origin as the configured backend — the download carries this host's device key, and a server response is not permission to send that credential elsewhere;
3. the SHA-256 is verified before a single byte is written to disk; a mismatch aborts and reports failed;
4. the bytes must be an executable for this platform (ELF on Linux, MZ/PE on Windows);
5. the replacement is staged beside the installed binary and executed with --version, which must report the promised version — caught while the running agent is still in place and nothing has changed;
6. the swap is two renames in one directory (installed binary to .update-bak, staged binary into place) with an immediate undo if the second fails;
7. the agent exits with code 42 so systemd or the Service Control Manager restarts it into the new binary — non-zero on purpose, because Restart=on-failure will not restart a clean exit.

Everything up to the swap is a best-effort side activity that never interrupts heartbeats, log reads or command execution — and a platform that cannot be reached costs an audit row, not an update. The swap itself restarts the whole agent process, so expect one short gap while the service manager brings it back on the new binary.

Probation and automatic rollback

The swap leaves a marker (update-pending.json, beside the inventory state file) cleared only by a successful inventory report — not merely by starting. A binary that starts and then fails before doing real work is therefore never credited as working: after 3 such starts the agent restores the previous binary, reports rolled back, and restarts. The failing binary is kept aside as .update-failed, the previous release as .update-bak.

Watching and halting a rollout

Inventory → Agents → Auto-update shows the fleet counters, each host's running version against its channel target, and the recent attempt trail — offered, downloading, applied, failed, rolled back. The three terminal states also land on the host's asset timeline as an Agent updated event; the trail is kept for 90 days.

Halt updates, on the Machine Agent card, stops further offers immediately and overrides every group override in the organization. Use Resume updates to lift it.

If a channel is enabled with a non-zero percentage and nothing moves, check the reason shown on the agent's row (Not enabled, Up to date, Outside the canary, Agent version unknown…). One case never shows there: an offer also needs a published downloads-catalog artifact for that exact version and platform, with a sha256: checksum — until VerOps has published one, the platform declines silently.

Getting to a release that can update itself

Machine Agent v0.4.0 is the first release that can update itself, so moving an existing fleet from v0.3.0 or older is still a manual install — replace the binary and restart the service, or re-run install.sh / install-service.cmd from Resources → Downloads. No re-enrollment is needed. From v0.4.0 onward, an opted-in server under an enabled channel moves on its own. The current release is v0.5.0, and it needs no configuration change: the connection key and the inventory module's api_key both keep working, so a Machine Agent update carries none of the migration that Scout v0.6.x requires.

Note: Auto-update belongs to the inventory module and travels with it — a Machine Agent with [inventory] disabled has no update channel. See the inventory module.