Skip to content
CatalystCatalyst Docs

Updating a Node

The panel drives agent updates: it reports the agent version each node is running and, once the panel is newer, offers an Update Agent command that the agent applies to itself. Running game servers keep running while the agent restarts and reconnects. Nothing is updated automatically unless you approve the node first (see automatic node updates).

Prerequisites

Section titled “Prerequisites”
  • The panel is already on the target version — a node only updates to the version the panel itself runs (updating Catalyst).
  • The node is online; the update command travels over the agent’s WebSocket.
  • Administrator access (admin.write) to trigger the update.

Safe update order

Section titled “Safe update order”
  1. Update the panel first (updating Catalyst). The agent update targets the panel’s own version, so a newer panel is what makes the node update available.
  2. Update one node and watch it for a full day before touching the rest.
  3. Update remaining nodes in batches, never all at once.

Automatic node updates

Section titled “Automatic node updates”

The panel does not push agent updates to every outdated node. Each node is either Automatic or Manual:

  • Manual (default) — the node keeps its current agent version. The panel flags Update available and you run the update yourself.
  • Automatic — when the panel’s agent version is newer than the node’s, the panel sends the update command on its own.

Choose the mode in Admin → System → Auto Updater → Automatic node updates: tick the nodes you trust to update unattended, untick the rest, then select Apply. Selecting rows only stages the change — nothing is sent until you apply, and the count badge shows how many nodes are currently automatic.

A node that is offline, or currently mid-update, is skipped; it is picked up on the next health report once it can take the command. A node is only ever updated to the version the panel itself runs.

Start with a canary: approve one node, watch it for a full day, then approve the rest. To update a Manual node now, use the per-node steps below.

Update one node from the panel

Section titled “Update one node from the panel”
  1. Announce maintenance — the agent restarts during the update.
  2. Open the node in Admin → Nodes. If its agent is behind the panel, the header shows a version badge (v<current> → v<latest>) and the Update tab carries a status dot.
  3. Open the Update tab and compare Current with Latest. Select Update Agent. The button is only enabled when the panel has a newer version; when there is nothing to do it reads No Update.
  4. Watch the status in the same panel: it moves through downloading (with a progress bar) and restarting, then clears. A failure shows the error text.
  5. Verify: the node is healthy again, a test server starts, the console streams, and backups list.

The panel sends the update over the agent’s WebSocket, so the node must be online — an offline node reports “Failed to send update command to agent”. The agent downloads the binary (GitHub Releases first, panel as fallback), verifies its checksum, swaps the binary in with an atomic rename, and restarts itself. A download or checksum failure aborts before anything is replaced.

Node settings are a different dialog

Section titled “Node settings are a different dialog”

The header’s settings button opens Update node, which edits the node’s identity, capacity, SFTP, and agent paths — not its version. Changes there apply to future deployments and do not restart the agent. To re-run the install command with new paths, use Deploy on the node header.

Rules

Section titled “Rules”
  • Never update the panel and all nodes simultaneously. A bad release then breaks everything instead of one canary node.
  • Game servers themselves do not update with the agent — game versions come from templates (templates).
  • Keep a changelog note per node (agent version + date) for the next incident.
Section titled “Related”