Updates

Cluster Build can update itself to the latest released cluster binary, either on demand with cluster update or automatically in the background when you start an interactive session. The automatic check stays off the hot path: it never runs until after the interactive UI has drawn its first frame, so startup stays responsive.

Update on demand

Run cluster update to check for a newer release and install it:

cluster update

If a newer version is available, Cluster downloads it, verifies it, and replaces the running binary in place. The update takes effect the next time you start cluster:

Cluster update installed: 0.1.3 -> 0.1.4. Restart to use it.

When you're already on the latest release, cluster update reports that and exits without changing anything.

Automatic updates

Interactive sessions check for a newer release in the background after the first frame renders. If an update installs, you'll see a notice in the session and can restart to use it. The check is rate-limited, so it won't run on every launch, and only interactive startup triggers it — cluster exec and other non-interactive commands never auto-update.

Automatic updates are controlled by the auto_update_enabled config key, which defaults to true. Turn them off if you manage the cluster binary yourself:

cluster config set auto_update_enabled false

See Config basics for the full config-key reference.

Release notes after an update

After an update — whether Cluster installed it or you replaced the binary yourself — the first interactive session on the new version opens with a "What's New in Cluster Build" notice: the release notes for the version you're now running, under a Cluster Build <version> heading. It appears once — the notice is marked seen across processes, so parallel sessions won't each repeat it.

If that first launch on the new version resumes an existing session (via --resume or /resume), the notice is deferred rather than interrupting the replayed transcript — it stays unseen and appears at the start of the next fresh session instead.

To read release notes again, or to browse older releases, run /changelog inside a session — it replays the full release history on demand.

When an update can't apply

Updates only replace a cluster binary that Cluster can write to. If the binary lives in a location your user can't modify (for example a system-managed install), the update is reported as failed and the existing binary is left untouched. Reinstall manually with the install script:

curl -fsSL https://assets.cluster.app/serve/cstatic-assets/releases/cli/install.sh | sh

cluster update exits non-zero when an update fails, so it's safe to wire into a script that falls back to a manual reinstall.

Checking update status

Both /status (inside a session) and cluster doctor report update status. They always show the runtime version of the binary you're currently running, separately from the last background update check, and they show whether background updates are currently enabled, disabled by config (auto_update_enabled = false), or disabled for debug build.

If the last recorded check ran under a different cluster binary version than the one you're running now — for example after a manual reinstall — that cached state is labeled historical rather than being reported as if it described the current run:

Updater: disabled by config (runtime=0.1.26; historical=up_to_date, checked_by=0.1.25, latest=0.1.25, checked_at=1753488000)

Update state is stored under ~/.cluster/update/.

Next steps

• Config basics — toggle auto_update_enabled and tune other settings in config.toml.
• Diagnostics — cluster doctor surfaces your update status alongside the rest of your setup.