Skip to content

Upgrading agents

Agents update themselves from a signal the operator publishes from the control plane. Upgrades are operator-triggered: nothing changes on your endpoints until you press Publish.

How it works

flowchart LR
    OP["Operator<br/>clicks Publish"] --> MAN["Control plane writes<br/>an upgrade manifest"]
    MAN --> CHK["Agents run a<br/>scheduled upgrade-check"]
    CHK -->|new trigger?| APPLY["Verify + apply<br/>then restart"]
    CHK -->|same trigger| SKIP["Do nothing"]
  1. You ship the new version to the distribution path (a new agent build and/or a new container tag).
  2. In Config → Agents → Upgrade, you click Publish. The control plane writes an upgrade manifest carrying a fresh trigger id, the target version, the new build's checksum, and the container tag.
  3. Each enrolled agent runs a scheduled upgrade-check — hourly on Linux/macOS, daily on Windows.
  4. An agent applies an upgrade only when the trigger id is new to it. It verifies the download against the published checksum, swaps in the new version, and restarts. A matching trigger is a no-op, so re-checks are cheap and idempotent.

Rollout visibility

The Upgrade view shows the rollout: each agent's current version against the target, so you can watch the fleet converge. Clear (unpublish) withdraws the manifest — agents that haven't upgraded yet simply stop seeing a new trigger.

Publishing a new version

The order matters: make the new version available first, then Publish. If you publish a trigger that points at a build the agents can't fetch or that fails checksum verification, they will correctly refuse to apply it.

  1. Build and upload the new agent (native executable and/or container tag).
  2. Confirm it's reachable at the distribution path.
  3. Click Publish.

Existing agents

Agents enrolled before the upgrade-check existed won't have the scheduled check. Re-enroll them once to pick it up; from then on they upgrade in place.

Roadmap

Operator-triggered is the current model. An opt-in auto-upgrade toggle — apply a published trigger without a manual Publish gate — is a planned addition.