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