Automatic updates

What automatic updates are

From Scout v0.5.0 an agent can replace its own binary when the platform offers a newer release, so bringing a fleet forward no longer means a manual reinstall on every endpoint. It is off by default, and it stays off until two independent switches are both turned 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"	No policy row at all — pinned, disabled, 0%
Endpoint opt-in — this machine may replace its own binary	Whoever owns the endpoint's configuration	auto_update = true in scout.toml	false

Neither one alone does anything. A mis-click in the console cannot move a machine that has not opted in, and a machine 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, so an agent that has auto_update = true simply never hears about an update.

Turning it on

1 — Opt the endpoints in

Add the key to scout.toml (C:\ProgramData\VerOps\Scout\scout.toml on Windows, /etc/verops/scout.toml on Linux) and restart the service — the local config is read once at startup:

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

There is an environment override, SCOUT_AUTO_UPDATE=true, which is convenient for image-based or MDM-pushed deployments. Restart the service afterwards: sc stop VerOpsScout & sc start VerOpsScout on Windows, sudo systemctl restart verops-scout on Linux.

2 — Enable a channel for your fleet

Open Inventory → Agents and click Auto-update. Each agent binary — VerOps Scout and the Machine Agent — gets its own card. On the Scout card:

1. pick a channel (see below);
2. set the rollout percentage — start small, e.g. 5%;
3. switch the policy to enabled and save.

Agents pick the offer up on their next config poll (about a minute), not instantly.

Channels

Channel	Target it resolves to	Use it for
Pinned	The version you name, or — with no version named — the agent's own version, which can never move.	Staying put, or holding a fleet at one exact version.
Stable	The release marked current in Inventory → Agents → Release notes.	Almost everyone.
Beta	The newest published release, including one not yet marked current.	A pilot group that wants new releases first.

Movement is forward only. A target equal to what the agent already runs is the steady state and offers nothing; a target older than the agent is a downgrade and is refused. Pinning back to an older version therefore stops further updates rather than pushing an old binary onto machines that are already past it.

Percentage rollouts

The rollout percentage decides how much of the fleet is offered the update. The split is computed from the machine's stable identity, so the same machine always falls on the same side of it — raising 5% to 25% adds machines to the group being updated and never reshuffles the ones already done. At 0% nothing is offered even with the policy enabled, which is a useful way to arm a channel without starting anything.

Group overrides

A policy can be attached to an Inventory Group as well as to the whole organization. A group row wins over the org default for its members, and where an agent belongs to more than one, the most conservative row applies — halted beats permissive, disabled beats enabled, and the smaller percentage beats the larger. Overrides in force are listed under the policy cards.

What happens on the endpoint

Every step is written to fail closed: when anything is not exactly as expected the agent aborts, leaves the installed binary untouched, and reports. In order:

1. the offered version must be strictly newer than the running one — never equal, never older;
2. the artifact URL must be on the same origin as the configured backend — the download carries this endpoint's device key, and a server response is not permission to send that credential somewhere else;
3. the artifact is downloaded to memory and its SHA-256 verified before a single byte is written to disk; a mismatch aborts and reports failed;
4. the bytes must look like an executable for this platform (ELF on Linux, MZ/PE on Windows), so an error page or the wrong platform's build can never be installed as a binary;
5. the replacement is staged beside the installed binary (never in a temp directory — a cross-filesystem rename is not atomic) and then actually executed with --version; it must report the version it was promised. This runs while the installed agent is still in place, so a broken or wrong-architecture build is caught with nothing modified;
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 one fails, so the failure mode is "nothing happened" rather than "no binary at all";
7. the agent exits with code 42 so the service manager restarts it into the new binary. The code is non-zero on purpose: systemd's Restart=on-failure will not restart a clean exit, and the Windows Service Control Manager only runs its recovery actions on an unclean stop.

Probation and automatic rollback

The swap leaves a marker (update-pending.json, beside scout-state.toml) that is cleared only by a successful inventory report — not merely by starting. So a binary that starts and then dies before doing any real work never gets credit for working: after 3 such starts the agent restores the previous binary, reports rolled back, and restarts. The same happens immediately if the agent comes up on a version other than the one it installed. The failing binary is moved aside as .update-failed rather than deleted, and the previous release is kept as .update-bak.

Watching a rollout

The Auto-update dialog in Inventory → Agents is the screen to watch. It shows the fleet counters (agents, behind target, being offered, failed / rolled back), each agent's running version against the version its channel would land it on, and a recent update attempts trail. Every transition an agent reports is recorded:

Status	Means
Offered	The platform offered this version to this agent.
Downloading	The agent accepted and started fetching the artifact.
Applied	The new binary is installed and running.
Failed	The attempt stopped at one of the checks. The installed binary was never modified.
Rolled back	The new binary was installed but could not stay up; the previous one has been restored.

Applied, failed and rolled back are terminal, so they also land on the host's asset timeline as an Agent updated event. Offered and downloading are progress rather than history and stay out of the timeline. The attempt trail is kept for 90 days.

Halting a rollout

Each policy card carries a Halt updates button. Halting is checked before any download decision and overrides every group override in the organization, so one click stops a rollout that is going wrong — including for groups with their own permissive policy. It works even for an organization that has never saved a policy. Press Resume updates to lift it.

Halting stops further offers. It does not reach back into an endpoint that is mid-download; that attempt finishes on its own and, if it fails any check, rolls back on its own.

Why nothing is being offered

Every agent row shows the exact reason it is or is not being offered an update, straight from the platform's own resolver:

Reason	What to do
Not enabled	The policy exists but is switched off. Enable it.
Halted / Updates halted platform-wide	Resume from the policy card. The platform-wide form is a VerOps operator kill switch and is not something an org admin can lift.
No target version	A pinned channel with no version named, or a channel with no published release behind it.
Up to date	The agent already runs the channel's version. Nothing to do.
Outside the rollout (0%)	The percentage is 0. Raise it.
Outside the canary	The agent is in the part of the fleet the current percentage does not cover. Raise the percentage.
Agent version unknown	The agent has not reported a readable version, so an upgrade cannot be told from a downgrade and nothing is offered.

One more case never appears as a reason on the row: an offer also needs a matching downloads-catalog artifact — the exact version, the right platform, enabled, with a sha256: checksum and a known size. Until VerOps has published one, the platform declines silently and nothing is offered. If a channel is enabled with a non-zero percentage and the fleet still does not move, this is usually why.

Getting to a release that can update itself

Scout v0.5.0 is the first release that can update itself, so moving an existing fleet from v0.4.0 or older is still a manual install — the installers from Inventory → Agents → Deploy Scout or Resources → Downloads. No re-enrollment is needed: the device credential survives an upgrade. From v0.5.0 onward, an opted-in endpoint under an enabled channel moves on its own. The current release is v0.6.1.

Before you roll out v0.6.x: v0.6.0 removed the org-wide ingest api_key and the username / password login from the agent, and a Scout whose config still names one refuses to start. That applies to an automatic update exactly as it does to a manual one — an endpoint left on a legacy configuration will fail to come back up. Migrate those machines to an enrollment token first (re-deploy from Inventory → Agents → Deploy Scout is the one-step route), and roll v0.6.x out by percentage so a small canary proves the fleet is ready. See Enrollment and device credentials.

Note: Nothing here is a remote-execution channel. The agent only ever installs an artifact the platform itself published, from the platform's own origin, whose SHA-256 it verified and whose binary it ran before trusting it — and only when the endpoint's own config asked to be updated.