vantage-docs/docs/operations/agent-updates.md

id, title, sidebar_label

id	title	sidebar_label
agent-updates	Agent updates	Agent updates

Agents are versioned and released independently of the control plane, and update themselves on command.

Checking the current version

Each server's detail page shows the version it reported at its last sync.

Updating from the UI

Servers → a server → Update agent pushes UpdateAgentCmd with a target version. The agent then:

1. Downloads the binary for its platform from the release.
2. Verifies the SHA-256 against checksums.txt.
3. Stops itself, replaces the binary in place, and starts again.

The server briefly goes offline and comes back within a poll interval or two.

Updating from the machine

There is a dynamic update script, the counterpart to the install one:

curl -fsSL https://vantage.example.com/update | bash

irm https://vantage.example.com/update.ps1 | iex

It does the same download, checksum and replace, then restarts the service. Use this when the control plane cannot push for example, when the machine is reachable but its command stream is not.

Rolling out across a fleet

There is no built-in bulk update. Two reasonable approaches:

• Update from each server's page, a few at a time.
• Build a workflow whose step runs the update script, and target it at the machines you want. That gives you ordering, failure handling and a log.

:::tip Update a canary first An agent that fails to start after replacing itself needs hands on that machine. Do one, confirm it returns to active, then do the rest. :::

Version compatibility

The agent API is versioned to tolerate an agent older than the control plane. The reverse an agent newer than the control plane is not a case anyone tests. Upgrade the control plane first.

Agents report their version on every poll, so a fleet running mixed versions is visible in the server list rather than something you have to go looking for.

If an update fails

Symptom	Cause
"Checksum mismatch"	Interrupted download, or a proxy rewriting the body. Retry
Downloads nothing	The machine cannot reach gitea.hostxtra.co.uk
Service will not start afterwards	Wrong architecture binary, or the file was replaced while a different service manager held it. Reinstall with the install one-liner

Reinstalling is always safe: the config file is left alone, so the agent comes back with the same identity and token.