---
id: agent-updates
title: Agent updates
sidebar_label: 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.
`GET /api/agent/latest-version` reports the newest release available.

## 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.

`Restart=always` on the systemd unit is what makes the last step work.

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:

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

```powershell
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](../vantage/workflows.md) 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 gRPC 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 `SyncKeys`, 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.