# Agent updates

The agent keeps itself on the build your board serves. It installs an update only when the build is signed with the
release key this machine pinned. The installer pins one for you: your board's own key when the board signs its builds,
else Andon's release key. When your board serves unsigned builds, a machine that trusts Andon's key updates from
Andon's official releases instead.

## How the agent updates

1. Two minutes after it starts, and then once a day, the agent reads the board's `agent/latest.json`.
2. If this machine trusts Andon's release key and that build isn't signed with it, the agent reads Andon's official
   releases instead and takes a release only if it is newer than the agent it runs.
3. When there is another build, the agent downloads it and checks the SHA-256 of the bundle and of the terminal
   helper.
4. It checks the build's Ed25519 signature against the release key pinned on this machine, or Andon's key for an
   official release. An older version number is refused.
5. It starts the new bundle once to make sure it runs, swaps the files (the previous bundle stays as `andon.mjs.old`)
   and exits. The service starts the new version.

Settings → Machines shows **update available** next to a machine that runs another build than the board serves. When
you send a machine a command its agent is too old for, the board says **Update <machine> first**.

| To | Run |
|---|---|
| update now, or repair a damaged install | `andon update` |
| stop daily updates on this machine | `andon policy auto-update off` |
| turn them back on | `andon policy auto-update on` |

`andon update` names the board it updates, then lists every other agent on this machine with the command for it
(`andon --profile <name> update`).

## Pin the release key

The manifest and the bundle come from the same board, so the SHA-256 only proves the bytes match that board. The
signature proves the build came from whoever holds the release key.

The installer pins the key it names: the key your board signs with, or Andon's release key when it signs nothing.
That is the same trust as running the installer. To pin a key you got through a channel independent of the board, or
to change the pin later, use one of these:

- At install: `curl -fsSL https://<your board>/install.sh | sh -s -- --update-key <key>`, or set `ANDON_UPDATE_KEY` for
  the installer.
- On an installed agent: save the key's base64url SPKI value as `~/.local/share/andon/update-key.pub`. For a second
  agent, use `~/.local/share/andon/profiles/<name>/update-key.pub` ([One machine, several boards](https://andon-docs.pages.dev/machines/multiple-agents.md)).

`ANDON_UPDATE_KEY` in the agent's environment overrides the file. For daily updates it must be in the service's
environment too.

Passing `--update-key` doesn't make the installer script itself trusted: it still comes from the board.

## A board that doesn't sign its builds

A board built without `ANDON_UPDATE_SIGNING_KEY` serves unsigned builds. A machine that pinned Andon's release key,
which its installer does by default, or that pinned nothing, updates from Andon's official releases instead: only a
release signed by Andon's key, and only one newer than the agent it runs. The board doesn't show **update available**
for a machine that is ahead of it.

The same goes for a machine that pinned Andon's key when your board later starts signing with a key of its own: the
machine can't check those builds, so it keeps following Andon's official releases. To have it take your board's builds
again, pin your board's key.

A machine that pinned another key, such as your board's own from before it stopped signing, refuses the unsigned
build and never takes Andon's.

An agent from before Andon's official releases doesn't know them. Once your board serves a newer build, update such a
machine by hand once with `andon update --trust-board`; from then on it follows the official releases by itself.

`andon update --trust-board`, with no key pinned, installs the board's own build on its SHA-256s alone. That is the same
trust you gave the installer you ran from that board. Only a person runs it, never the daily check, and a pinned key
always wins over it.

## When an update was interrupted

- The agent refuses to start while `~/.local/share/andon/.update-lock` exists. Check `andon.mjs.old` and
  `prebuilds/<platform>.old` next to it, restore them if the update left things broken, then remove the lock. Don't
  remove it while another update is running.
- If the update state can't be read, updates stop. Restore a backup you trust rather than deleting it: the state holds
  the version this machine last accepted, which is what refuses an older build.
- A signature doesn't stop someone replaying a different build with the same version number. If you publish agent
  builds, give every security fix a higher version.

## The terminal helper

The board terminal needs node-pty's native files for the machine's platform. The installer puts them in
`~/.local/share/andon/prebuilds/<platform>/`, for example `linux-x64` or `darwin-arm64`; the Linux ones need glibc 2.31
or newer.

If a terminal on the board says **The terminal helper isn't installed on <machine>**, or `andon doctor` fails on
`node-pty`, run `andon update` on the machine. A board built without the helper for that platform can't open a
terminal there at all. Runs still work.
