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

## Updating from the UI

Open a server and choose **Update agent**. 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:

```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 Vantage cannot reach the agent to push the update, but you can still
reach the machine.

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

An agent older than your control plane is supported. An agent newer than it is
not, so 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.