# 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 [#update-on-demand]

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

```bash
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`:

```text
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.

<Callout type="info">
  An update replaces the `cluster` binary on disk but does not restart a running
  session. Quit and relaunch `cluster` to pick up the new version.
</Callout>

## Automatic updates [#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:

```bash
cluster config set auto_update_enabled false
```

See [Config basics](/docs/build/config/basic) for the full config-key
reference.

## Release notes after an update [#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 [#when-an-update-cant-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:

```bash
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 [#checking-update-status]

Both `/status` (inside a session) and [`cluster doctor`](/docs/build/diagnostics)
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:

```text
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 [#next-steps]

* **[Config basics](/docs/build/config/basic)** — toggle
  `auto_update_enabled` and tune other settings in `config.toml`.
* **[Diagnostics](/docs/build/diagnostics)** — `cluster doctor` surfaces your update
  status alongside the rest of your setup.