Moving your agent runner to a new version¶

Your instance and your agent runner are two containers on two different update paths. Upgrading the instance does not move the runner, and that is deliberate — recreating the runner stops any agents running on that machine, so it is your decision and not something an update does to you while you are working.

The consequence is the thing this page is about: after an upgrade the runner is normally behind the instance, and it stays behind until you move it.

How you know¶

The Infrastructure page lists your machines. A machine whose runner is behind carries a notice saying so, with the version it reports.

Three states, and only one of them is a problem you can act on directly:

What the notice says	What it means
the versions match	nothing to do
the runner reports an older version	it is behind; move it
the runner has never reported a version	it predates version reporting. Move it once using the steps below; afterwards it reports its version and the instance can tell you directly.

That third state is shown, but the instance will not offer to move it for you: a runner that has never reported anything could be any version, and moving it to a target chosen on a guess is how a working install stops working.

Moving it¶

Open the machine's row on the Infrastructure page and start a re-pin. Before anything happens you are shown, and asked to confirm:

which machine it is,
the version its runner reports now — this is also what a rollback returns it to,
the image reference it will move to,
and that agents running on that machine will be stopped.

Confirming records the decision, including the version to roll back to, and then carries it out where it can. The row tells you which happened — it never reports a move it did not make.

When your instance can do it for you¶

Two things have to be true. If either is not, you are shown the steps instead, with the reason:

Your updater is current. The re-pin is performed by the updater service that applies your upgrades, and that service is only replaced when you recreate it. An update pins the new updater image but never recreates the container, so shortly after upgrading, your updater is usually still the previous one. Recreate it once and the action works from then on:
```
sudo docker compose up -d hivemind-updater
```
The machine you picked is the one your instance runs on. The updater can only recreate the runner on its own host, so re-pinning a runner on another machine — a developer workstation, for example — is done on that machine.

You do not have to work out which is which. Your runner records its own identity, and the updater checks it before doing anything, so picking another machine's row is refused rather than acted on. That check is the thing standing between a mis-aimed re-pin and agents stopping on a machine somebody else is working on.

A runner old enough not to record an identity is the one case this cannot confirm. On a single-machine install there is nothing to confuse it with and it goes ahead; otherwise you are shown the steps. Recreating that runner once gives it an identity, after which it is checked like any other.

Doing it yourself¶

Check the image, then recreate the runner:

sudo docker compose --profile runner config --images
sudo docker compose --profile runner up -d hivemind-runner

--profile runner is required. Without it compose exits successfully having done nothing.

An update has usually already set the image for you — it records the release's runner image without replacing the container — so the first command often shows the right reference already. Recreating is the step an update never performs, and it is what actually moves your runner.

When it will not offer to move¶

Each of these is shown with its own reason, because they need different things from you:

the runner already matches — nothing to move;
the runner has never reported a version — see above;
the runner is not behind — moving it from here would be a downgrade, which is a separate decision this action does not make;
no image reference could be resolved for this release — check that the instance can reach its update channel;
the machine is not reporting in — a re-pin would be recorded and never carried out; bring it back first;
agents are running on that machine — re-pinning stops them. Wait for them to finish or stop them yourself, then try again.

Rolling back¶

Rolling back is the same action run the other way. The version the runner was on before its last re-pin is recorded, and the instance shows it to you when you start a re-pin on that machine, so you do not have to remember it: set the runner image back to that version and recreate the runner exactly as above.

Every re-pin is kept, including a rollback — so the record shows that a machine went forward and then came back, rather than hiding it.