Updating Agents (Fleet Management)

Once agents are enrolled, you need a way to keep them on a current, compatible build. Proxima Console provides Fleet Management — an operator-controlled, canary/batched rollout system that pushes agent self-updates from the console and shows you live, per-agent progress. This page covers the Agents page, version skew, and how to plan, push, and monitor a rollout.

Two ways to update agents

Method	When to use
Console fleet rollouts (recommended)	Updating one or many host agents. Canary/batched, observable, and controllable (pause / resume / abort) from the Agents page.
Manual / CLI self-update	One-off or host-specific updates from an ops engineer who is already on the box — e.g. recovering a single host, or bootstrapping an old build (see the prerequisite below).

The CLI path is proxima-agent self-update (or re-running the install script); see Installation — CLI Self-Update. The rest of this page focuses on the console fleet rollout flow.

Prerequisite: the fixed checksum verifier

Prerequisite — the fixed checksum verifier

An agent can only self-update if it is running a build with the fixed checksum verifier, shipped in v0.6.1+. Older builds rejected the published bare-hash checksum (malformed checksum file), so every self-update failed.

Agents on older builds must be updated once manually — re-run the install script on the host — to pick up the fix. After that one hop, fleet self-updates work normally. This is why a brand-new or long-stale fleet may need a single manual update before canary rollouts succeed.

The Agents page

The Agents page lives at /agents, under Assets → Agents in the navigation. Viewing it requires the agents:read permission; without it the page shows an "Access Denied" state.

It lists every enrolled agent visible to you (tenant-scoped — you only see agents for clients you have access to), with these sortable columns:

Column	Description
Host/Name	The agent's hostname (falls back to its name).
Project	The client/project the agent belongs to.
Version	The agent's reported version, with a skew badge.
Type	The agent type — Host, K8s node, or Collector.
Status	Online/offline status.
Last seen	When the agent last reported in.

Click a column header to sort by it. The page header shows the version compatibility snapshot — the backend version and the recommended (latest published) agent version — so you can see at a glance whether your fleet is behind.

Version skew

Each agent's version is compared against three reference points to compute its skew — the badge next to its version:

• The minimum supported version (the oldest build this backend still works with)
• The recommended version (the latest published release)
• The backend version (the agent-compat ceiling for this backend)

Badge	Meaning
Up to date	At or above the recommended version (and not ahead of the backend).
Update available	Below the recommended version — a newer release exists.
Outdated	Below the minimum supported version — should be updated promptly.
Ahead of backend	Newer than the backend supports (e.g. backend was rolled back). Upgrade the backend to catch up.
Unknown	The agent has not reported a version yet.

Agent types and what is updatable

Only host agents self-update via fleet rollouts. The other agent types are container/Helm-managed and are updated by redeploying their image, not by a console rollout:

Type	Updatable via fleet rollout?	How to update
Host	Yes	Fleet rollout (this page) or CLI self-update.
K8s node (k8s-node-monitor)	No	Redeploy the Helm chart / new image.
Collector (collector)	No	Redeploy the container / new image.

Non-host agents still appear in the list (so you can see their version skew), but their selection checkbox is disabled. If you somehow target one anyway, the backend rejects the whole rollout with an unsupported_agent_type error rather than silently dropping it.

Pushing a rollout

Pushing a rollout requires the agents:write permission. The Update selected button only appears for users who have it.

1. On the Agents page, tick the checkbox for each host agent you want to update. (Only host agents are selectable.)
2. Click Update N selected to open the Update agents dialog.
3. Choose your settings:
   • Target version — defaults to the recommended version. You can type any valid version.
   • Canary size — how many agents update first, before the rest. Default 1.
   • Batch size — how many agents update per wave after the canary. Default 5.
4. Click Start rollout.

The canary → batches model

A rollout proceeds in waves:

• Wave 0 (canary) — the first canary size agents update first. If they fail, the rollout pauses before touching anything else.
• Wave 1, 2, … — once the canary is healthy, the remaining agents update in batches of batch size, one wave at a time. Each wave must succeed before the next begins.

Pause-on-failure

If any agent in the current wave fails (or times out without reporting the target version), the rollout pauses automatically. No further agents are dispatched until you resume or abort. This keeps a bad build from sweeping the whole fleet.

Backend-first guardrail

You cannot roll agents to a version newer than the backend supports. The backend version is the ceiling; the dialog blocks Start rollout and the API rejects the request (invalid_target) with a message like "target version … exceeds the supported version …; update the backend first".

Upgrade the backend first

Always upgrade the backend before the fleet. The guardrail enforces this so an agent never runs ahead of the backend it talks to.

Downgrade and restart cautions

• Downgrade warning — if the target version is lower than some selected agents' current versions, the dialog shows a non-blocking warning with the count of agents that would move backward. You can still proceed.
• Restart caution — updating restarts the agent. In-progress interactive terminal sessions on those hosts may be interrupted.

Monitoring a rollout

After you start a rollout (or click any row in Update history), the rollout progress view opens and polls live until the rollout reaches a terminal state.

It shows:

• The target version and overall status (Running / Paused / Completed / Aborted).
• A healthy count (e.g. 4/10 healthy), plus who started it and when.
• Agents grouped by wave (Wave 0 is labeled canary), each row showing the agent, its from → to version, its current per-agent status (pending, sent, downloading, verifying, swapping, restarting, healthy, failed, timed out, skipped offline, aborted), and the error message for any failed/timed-out/ aborted agent.

Pause / Resume / Abort

Users with agents:write see control buttons in the rollout header:

Action	Available when	Effect
Pause	Running	Stops dispatching new agents; in-flight agents finish.
Resume	Paused	Continues the rollout from where it stopped.
Abort	Running or Paused	Marks every non-terminal agent aborted and ends the rollout.

Resuming past a failure

When you resume a rollout that auto-paused on failure, the failed/timed-out agents are marked aborted (their original error is preserved) so the planner does not immediately re-pause, and the rollout continues with the remaining waves. Fix those hosts separately — e.g. with a manual update — if needed.

Update history

Below the agent list, the Update history card lists recent rollouts — when each one started, who started it, the target version, and its status. Click any row to reopen its live progress / final result.

Permissions

Fleet management uses two tenant-scoped RBAC permissions:

Permission	Grants
agents:read	View the Agents page, fleet version info, and rollouts.
agents:write	Push rollouts and pause/resume/abort them.

Both are granted to the operator-class system roles — Super Admin, Admin, Engineer, and Team Lead. The tenant-facing client roles and the read-only overview roles do not have them: fleet self-update is an operator capability. See Roles & Permissions for the full role matrix.

See also

• Installation — CLI Self-Update — the manual/per-host update path.
• How It Works — agent startup, command channel, and heartbeats.
• Troubleshooting — Self-update command failed — when an agent won't update.