---
url: https://clusto.app/docs/remote-updates.md
description: >-
  Update Clusto daemons, matching CLIs, and apps from release manifests at any
  HTTP endpoint.
---

# Remote-URL Updates

Clusto can fetch the daemon (`clustod`), the CLI (`clusto`), and the desktop / mobile
app from an arbitrary HTTP(S) URL hosting a JSON manifest. This is independent
of the desktop app's download-from-connected-daemon flow - it lets you stand up
an update source behind any plain static HTTP server (S3, GitHub Pages, nginx, a
raw folder served by `python -m http.server` for testing, etc.).

A daemon update is always a Clusto node update: it requires the matching `cli`
artifact for the node's platform, verifies and stages both binaries, then
installs or updates the CLI when the daemon restarts. Clusto does not expose a
separate node CLI update control because the daemon and its local CLI are one
release unit. If the staged CLI cannot be copied, made executable, or renamed
into place on that restart, daemon startup fails instead of running a mixed
daemon and CLI release.

Every release is signed. Daemons, CLIs, and apps install only artifacts whose
Ed25519 release signature verifies against the keys built into Clusto, whatever
URL they came from (see [Security model](#security-model)). Pushing a daemon
binary to a node over the WebSocket, or from one peer to another, no longer
exists; a node only installs a signed release it fetched itself from a manifest
URL. Use a manifest URL through the app or `clusto update-node --from ...`; the
manifest flow stages the daemon and CLI atomically.

## Manifest format

A manifest is a single JSON document. Every entry carries its release version,
a SHA-256 digest and size that are verified after download, and one or more
Ed25519 signatures from a Clusto release key. A client rejects the whole manifest
if any entry is unsigned or does not verify.

```json
{
  "version": "1.11.1",
  "build_date": "2026-05-12T11:00:00Z",
  "artifacts": [
    {
      "kind": "daemon",
      "platform": "linux-x64",
      "filename": "clustod",
      "sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
      "size": 12345678,
      "url": "clustod",
      "build_date": "2026-05-12T11:00:00Z",
      "version": "1.11.1",
      "signatures": [{ "key_id": "32a8052c1307d5b4", "sig": "<128 hex characters>" }]
    },
    {
      "kind": "cli",
      "platform": "linux-x64",
      "filename": "clusto",
      "sha256": "abcd...",
      "size": 9876543,
      "url": "clusto",
      "version": "1.11.1",
      "signatures": [{ "key_id": "32a8052c1307d5b4", "sig": "..." }]
    },
    {
      "kind": "app_installer",
      "platform": "windows-x64",
      "filename": "Clusto-win-x64-1.11.1-setup.exe",
      "sha256": "feed...",
      "size": 87654321,
      "url": "Clusto-win-x64-1.11.1-setup.exe",
      "version": "1.11.1",
      "signatures": [{ "key_id": "32a8052c1307d5b4", "sig": "..." }]
    },
    {
      "kind": "android_apk",
      "platform": "android-arm64",
      "filename": "Clusto-android-universal-1.11.1.apk",
      "sha256": "cafe...",
      "size": 30000000,
      "url": "Clusto-android-universal-1.11.1.apk",
      "version": "1.11.1",
      "signatures": [{ "key_id": "32a8052c1307d5b4", "sig": "..." }]
    }
  ]
}
```

Notes:

* `kind` is one of `daemon`, `cli`, `app_installer`, `android_apk`.
* `platform` slugs: `windows-x64`, `linux-x64`, `linux-arm64`, `macos-x64`,
  `macos-arm64`, `android-arm64`.
* `url` is the location of the artifact bytes. **Absolute** URLs are used
  verbatim. **Relative** URLs are resolved against the manifest URL, so a
  folder layout like
  `https://updates.example.com/clusto/{manifest.json,clustod,clusto,...}` works
  out of the box.
* `build_date` is optional. When present, it is written next to the artifact
  as a `<filename>.builddate` sidecar - the daemon's artifact picker uses
  that to prefer fresh builds over stale siblings.
* `sha256` must be the lowercase hex digest of the artifact bytes. Mismatch
  aborts the update and removes the partial file.
* `version` (`X.Y.Z`) and `signatures` are required on every entry. The signature
  covers the entry's kind, platform, version, filename, SHA-256, size, and build
  date. `url` is the only field it does not cover, which is why a mirror can serve
  the same files from another location. The manifest's own top-level `version`
  and `build_date` are never trusted; clients derive both from the signed entries.
* A signature from a key Clusto does not trust is ignored, and an entry needs at
  least one valid signature from a trusted key. Manifests signed with a test key
  are refused by release builds.

### Public manifest API

The website exposes the current distribution manifest without a license key:

```text
GET /api/updates/manifest
```

The response wraps the distribution document as `{ "manifest": { ... } }`.
This public endpoint is rate-limited and returns HTTP 502 if the distribution
manifest is unavailable. It does not select versions by license or maintain a
release catalog. Paid subscription access is checked separately from downloads.
For a direct manifest URL used by update tools, use
`https://dl.clusto.app/manifest.json`.

## One release track

There is a single release track. Every build published by `deploy distribution`
(or by the ship workflow) writes `manifest.json`, and every daemon, CLI and app
follows it. There is no separate stable or unstable channel and no promote step.
Risky changes ship behind [feature flags](/feature-flags) instead of a
pre-release channel; users who want new behavior first turn on **early access**
in Settings > Labs.

`manifest.json` is also what the nginx index serves, so a base URL with no
filename (`https://clusto.app/`) resolves to it.

`manifest-unstable.json` is still written as a byte-identical copy of
`manifest.json`. Nodes configured for the old unstable channel keep fetching that
file, so they reach the release that migrates them. It will be retired together
with the frozen `dl.vazac.dev` bridge.

### Per-version manifests

Every release also publishes its signed manifest under its own name,
`manifest-<version>.json` (for example `https://clusto.app/manifest-1.15.29.json`),
next to `manifest.json`. It is a byte-for-byte copy of that release's
`manifest.json`, so it carries the same signatures, and a slot the release did not
rebuild keeps the older artifact it already had. `clusto update --version X` and
`clusto update-node --version X` install from it instead of the newest release; see
[Installing a specific release](#installing-a-specific-release). A client refuses a
`manifest-X.Y.Z.json` whose signed version is not `X.Y.Z`.

Only the **10 most recent releases** stay installable this way. Older per-version
manifests are retired when the distribution is pruned, together with the artifacts
no retained manifest still names. Asking for a retired release fails with
`release vX is not published (only the 10 most recent releases stay installable)`.

`https://dl.clusto.app/` is the only distribution origin that advances. New
releases, manifests, installers, and artifact files publish there.
The Clusto website at `https://clusto.app/` resolves update requests to that
canonical distribution.

### Two-hop legacy bridge

`https://dl.vazac.dev/` is a frozen compatibility bridge, not an alias for the
canonical store. Its `manifest.json` and `manifest-unstable.json` are each
written once at A1 1.14.5 and never advance again. Every artifact URL in those
bridge manifests is absolute and points to `https://dl.clusto.app/`.

This gives a node whose stored endpoint still names the legacy origin a safe
two-hop update:

1. The A0 client fetches its manifest from `dl.vazac.dev` and receives
   the frozen 1.14.5 manifest.
2. It downloads the A1 daemon and matching CLI from `dl.clusto.app` and performs
   the layout handoff.
3. A1 migrates the stored endpoint to the canonical Clusto origin.
4. A second update check can then install the current release from
   `dl.clusto.app`, even when it is newer than 1.14.5.

Fresh installs use the canonical origin immediately. `install.sh` accepts
`CLUSTO_BASE_URL` as its override; `HIVE_BASE_URL` remains only as a temporary
environment-name fallback. The legacy domain is retained solely as a fixed
compatibility identifier for old clients.

Nodes and clients take a manifest base URL, not a channel:

* **Node**: the `[update].manifest_url` field in `config.toml` drives clustod's
  own self-update and its auto-check broadcast. Edit it from **Settings >
  Updates > Update source**; it replicates to peers.
* **Client (app)**: the app updates from the connected daemon's manifest URL. The
  old channel picker and the `hive-update-channel` preference are gone.

### Moving off the old channels

The `[update] channel` key no longer exists. A config that still contains it keeps
loading. On start the daemon migrates once: `channel = "unstable"` turns on
**Settings > Labs** early access for the cluster (only if Labs settings were never
set), any other value is just dropped, and `config.toml` is rewritten without the
key. The web client's old `https://clusto.app/app/` and
`https://clusto.app/app-unstable/` URLs redirect (301) to
`https://web.clusto.app/`, see [Web Client](/web-client).

### Publishing

```bash
pwsh ./scripts/clusto.ps1 build all
pwsh ./scripts/clusto.ps1 deploy distribution   # writes manifest.json (+ identical manifest-unstable.json and manifest-<ver>.json)
```

`deploy distribution` writes `manifest.json` with the newest version per
artifact. Before it publishes, it signs every entry with the Clusto release key,
checks the signatures against the production keys, and only then replaces the
live manifest; if signing or verification fails, the published manifest is left
unchanged. The `dl.clusto.app` download index lists only the current version and
names the signing key ids. The versioned artifacts of older builds stay in the
folder, so a node pointed at a specific manifest file keeps working. `clusto.ps1
prune` keeps the newest 10 per-version manifests and every artifact they, or
`manifest.json`, reference; it retires older per-version manifests and deletes
the artifacts only they referenced (a dry run lists both, `prune apply` deletes
them and mirrors the deletion to `dl.clusto.app`).

Release flags are a separate mechanism: `flags.json` is published next to the
manifest and gates individual behaviors rather than whole builds. It is signed
too, with a counter that must never go backwards; mirror it along with the
manifest; see [Feature Flags](/feature-flags).

## App updates (Settings → Updates → App updates)

Settings has a standalone **Updates** tab. Its top card, **App updates**,
drives this app's own self-update from the connected daemon and is built for
unattended, interruption-tolerant downloads:

* **Background, resumable download.** Click **Download** (or enable
  auto-download) and the artifact streams to disk in the background. The bytes
  are saved to a `<filename>.partial` sidecar as they arrive; if the transfer
  is interrupted (you leave, the socket drops, the app restarts), the next
  attempt sends an HTTP `Range` request and resumes from where it left off
  instead of starting over. The daemon's `/clients/{kind}/{platform}` endpoint
  advertises `Accept-Ranges: bytes` and answers `206 Partial Content` to make
  this possible.
* **Staged reuse - download once, install later.** A completed, SHA-256
  verified download is kept on disk. When the same update is rediscovered (on
  reconnect or relaunch) the app detects the staged file and jumps straight to
  *Ready to install* - so a cancelled or deferred install never re-downloads.
  The app checks the release signature of the offered update and re-verifies the
  staged file's signed size and SHA-256 again immediately before every install.
  It installs only an update built for this app and platform, and never one older
  than the running version.
* **Auto-download toggle.** Off by default. When on, a newly discovered update
  is fetched in the background automatically so **Install** is instant. The
  preference is stored per device in `localStorage`.
* **Install** applies the staged artifact via the platform installer (NSIS on
  Windows, DMG on macOS, `.deb`/`.rpm`/tarball/AppImage on Linux, system
  PackageInstaller on Android). See [Linux desktop artifacts](#linux-desktop-artifacts)
  for how the Linux app picks which one it updates with.

The same staged + resumable download powers the **Install on this device**
button on the update-available banner, so banner installs are equally
interruption-tolerant.

Install on this device asks first when any cluster node still runs an older
version than the app update (**Update your nodes first?**), because a newer app
sends requests older nodes do not understand. Update the nodes from the
**Cluster** view first and the app last, or choose **Install app anyway**.

## What's new after an update

After an update, the app shows what changed. On startup it compares its version
with the last version this device ran. The last-run version is kept on the
device only and is not synced to other devices or your account.

* **Updated to a newer version.** A "Welcome to vX" dialog opens on its own
  with a short summary of every version since the one this device last ran,
  newest first: the headline of each change (up to 6 per version, then "and N
  more"), and a **Full release notes** link to that version's section of
  <https://clusto.app/docs/changelog>. A **Full changelog** button opens the
  whole page. It opens once per update: closing it does not bring it back on
  the next start.
* **Fresh install.** Nothing is shown, since there is no earlier version to
  compare with.
* **Reopen any time.** Run **What's new in Clusto** from the F1 command palette
  (it lists the latest 5 releases), or click the version number at the bottom of
  the sidebar.

The notes come from the `CHANGELOG.md` bundled into the app build, so they work
offline. The changelog has one section per version, written automatically on
every release: entries added while a change was made, plus entries drafted from
the release's commits for anything they missed.

## Persistent settings (Settings → Updates → Update source)

The **Update source** card (below *App updates* in the same tab) persists the
manifest URL, optional bearer token, auto-check toggle, and interval
across restarts. This card is the only place these fields are edited - the
cluster config dialog no longer duplicates them.

* **When connected to a daemon**: Save writes to the daemon's
  `[update]` section in `config.toml` and broadcasts to every cluster peer
  via `PeerMessage::SyncRemoteUpdateConfig`. Each node ends up with the
  same URL/token in its local config, so a peer can still self-update on
  schedule even when other nodes are offline.
* **When not connected**: Save stores the settings in browser
  `localStorage` only. The app keeps polling the URL locally so the
  desktop client can still receive an "update available" banner.

The token is propagated alongside the URL because cluster peers already
share the `cluster_token` over the same authenticated peer transport -
treat the manifest token with the same care.

### Updating an installed node from the app

Connect to the installed daemon, then use **Cluster > Check Updates** and the
node's **Update** button (shown when a newer version is available). This works for a daemon on the same machine
or a remote server. **Update All** updates eligible nodes across the cluster
after you confirm it.

The daemon verifies and stages its own binary and the matching CLI, then
restarts and installs the CLI beside the daemon. A missing or invalid CLI
artifact fails the update before restart; a failure to install the staged CLI
aborts the new daemon startup. A0 also verifies or creates its immutable
rollback backup before allowing its process image to be replaced.

The app does not update a disconnected local service directly. It can install
a node on the computer it runs on once, with the
[one-click setup](/downloads#set-up-this-computer-from-the-app); after that,
updates arrive over the connection. A node run by the app in
[local mode](/downloads#local-mode-a-node-inside-the-app) is the exception: it
never self-updates or polls for updates, and is refreshed to the app's version on
the next start after an app update. For another machine, install the daemon
through the [install script and CLI wizard](/downloads), and use the service
tools on its host if it cannot start or accept a connection.

### `[update]` section in `config.toml`

```toml
[update]
manifest_url = "https://updates.example.com/clusto/"  # base directory URL
token = "optional-bearer-token"
auto_check = true
interval_secs = 21600    # 6 hours
```

`manifest_url` is the **base directory**. If its last segment ends in `.json`, it
is used verbatim, so a node can point at one specific manifest file
(`https://host/manifest.json`); anything else gets `/manifest.json` appended.
`flags.json` resolves in the same directory.

The URL must be `https://`. Plain `http://` is accepted only for a loopback host
(`localhost`, `127.0.0.0/8`, `::1`), and redirects are held to the same rule. The
app and the daemon reject a disallowed URL when you save it, so nothing is stored
or sent to the other nodes. The bearer `token` is sent only to the manifest's own
host and port, never to an artifact URL on another origin.

`channel` is removed. Old configs that still have it keep loading and are migrated
once on start (see [Moving off the old channels](#moving-off-the-old-channels)).

Missing section → defaults to `auto_check = true`, `interval_secs = 21600`,
base URL `https://clusto.app/`.

`[update]` also holds `fetch_flags` (default `true`) and `flags_interval_secs` (default `900`) for the remote feature flag file; see [Feature Flags](/feature-flags).

### Auto-check + manual install confirmation

When `auto_check = true` and `manifest_url` is set, clustod spawns a
background task at startup that:

1. Sleeps for `interval_secs`.
2. Fetches the manifest, compares its `version` against
   `env!("CARGO_PKG_VERSION")`.
3. If newer, broadcasts `ServerMessage::RemoteUpdateAvailable` to every
   connected client. The app shows a "vX.Y.Z available" banner under
   **Settings > Updates > Update source** with an **Install on this device**
   button; nodes are updated from the **Cluster** view. **The install itself
   is always manual**: clustod never auto-applies an update without explicit
   user confirmation.

Interval changes propagate on the next tick (no restart needed). Settings
re-read every cycle, so cluster-replicated changes via
`SyncRemoteUpdateConfig` take effect within `interval_secs` on every node.

## Endpoints

All three targets accept an optional **Bearer token** via
`CLUSTO_UPDATE_TOKEN` env var (CLI) or the dialog (desktop). When set, every
HTTP request to the manifest URL and to each artifact on the same origin gets
`Authorization: Bearer <token>`; an artifact hosted on another origin never
receives it. Public URLs work with no token.

### CLI self-update from URL

```bash
# Default base URL (or the local node's configured one):
clusto update

# Custom base URL, with a bearer token:
CLUSTO_UPDATE_TOKEN=secret clusto update --from https://updates.example.com/clusto/
# or
clusto update --from https://... --remote-token secret
```

`--from` is the **base directory URL**. When it is omitted, the CLI reads the
local clustod config's `[update]` section and follows the same `manifest_url` the
node itself tracks (falling back to `https://clusto.app/` when there is no
config). `--remote-token` likewise falls back to the config's `[update].token`.
`--channel` is still accepted for one release but hidden from help; it prints a
notice that channels are gone and is ignored. The CLI downloads the `cli` artifact for its own
platform, verifies the release signature, size, and SHA-256, replaces the running binary,
and re-execs.

```text
Remote offers v1.14.52 (80957552 bytes, signed by release key 32a8052c1307d5b4); current is v1.14.51.
Download matches its signed SHA-256 and size. Restarting...
```

A CLI that is already on the signed version prints `Already on v1.14.51 (matches the
signed CLI in the remote manifest).` and exits 0. A signed CLI that is **older** than the
running one is refused with `refusing to downgrade from vX to vY` and exit 1; there is no
override, so roll back by releasing a higher version. Use `clusto update --dry-run` to
verify the manifest and see the decision (`update from vA to vB`, `already on vA, nothing
to do`, or `refusing to downgrade`) without downloading or changing anything.

An unsigned or tampered manifest stops with `<url> is not a signed Clusto release
manifest` and the cause. A plain `http://` URL off loopback is refused before any request
is made.

`clusto update --version X.Y.Z` installs that exact release instead of the newest one;
see [Installing a specific release](#installing-a-specific-release).

### Daemon self-update from URL

The daemon self-updates only when asked, via the WebSocket. You can drive that from the CLI:

```bash
clusto update-node --from https://updates.example.com/clusto/manifest.json
```

A bare `clusto update-node` updates the local node, following the `[update]`
manifest URL the node already tracks. Every run requires the
same-platform daemon and CLI entries, signed at the same release version (a mismatch
fails with `the signed daemon (vX) and CLI (vY) for <platform> differ`), and refuses
a release older than the running daemon (`refusing to install daemon vX: older than
the running vY`). It verifies and stages both, and installs or
updates the CLI as part of the daemon restart. If either required artifact is
missing or fails verification, the node does not restart into a partial update.
If the staged CLI cannot be installed beside the daemon on the next boot, daemon
startup fails rather than accepting a mixed release.

Add `--refresh-artifacts` to additionally download the remaining entries: CLIs
and daemons for other platforms plus app installers and Android APKs. These are
written into the daemon's local `clients/` and `daemons/` trees so connected
clients and peer relays can pull them later. The current node's CLI is always
staged and installed even when this flag is omitted. Each peer daemon is brought
up to date by running its own URL update against the same manifest.

The daemon never auto-applies an update (its auto-check only announces one).
Trigger an update explicitly - `cron`, `systemd timer`, a CI deploy step, or a
human in the app.

### Installing a specific release

Test a release on one machine first, then roll that exact release out to the rest
of the cluster later, without pulling the other nodes to something newer:

```bash
# This CLI, or the connected node, to release 1.15.29:
clusto update --version 1.15.29
clusto update-node --version 1.15.29

# Every outdated node of the cluster to 1.15.29, staged together, one restart:
clusto update-node --cluster --version 1.15.29

# Every node to the release that home-pc runs (display name or node id):
clusto update-node --cluster --match-node home-pc

# Show the verified target and what each node would do, change nothing:
clusto update-node --cluster --match-node home-pc --dry-run
```

`--version` swaps the manifest for the release's
[per-version manifest](#per-version-manifests) next to the one the node already
follows (`--from` and `[update].manifest_url` still pick the base). A leading `v`
is accepted. `--match-node` needs `--cluster` and cannot be combined with
`--version`: it reads the named node's running version from the cluster status.
`update-node --cluster` without either flag updates every outdated node to the
newest release.

The downgrade guard is unchanged. A node already ahead of the target is never moved
back: the CLI lists it as `Left alone: <node> (vY): ahead of vX, left alone (nodes
are never downgraded)`, and `clusto update` / `update-node` on a node ahead of the
target refuse with the usual downgrade error. Only the 10 most recent releases can
be targeted; an older one fails with `release vX is not published (only the 10 most
recent releases stay installable)`. Pinning a release for auto-update is not
supported; the auto-check always follows `manifest.json`.

### Desktop app update from URL

Set the manifest URL and optional bearer token under **Settings >
Updates > Update source**. Use **App updates** to update the current app, or
the **Update** button on the target node's card in **Cluster** to update its daemon and
matching CLI over the authenticated connection. The desktop app does not stage artifacts for other
platforms; use `clusto update-node --refresh-artifacts` when a daemon should cache
the remaining manifest entries.

On desktop the installer is downloaded into the user's Downloads folder and
run automatically (NSIS `/S` on Windows, `open` on macOS, `pkexec apt
install -y` for `.deb`, `pkexec rpm -Uvh` for `.rpm`, `pkexec tar -xzf … -C /`
or `replace-and-restart` for the tarball, `replace-and-restart` for AppImage).
On Android the APK is staged into the app cache and handed to the system
PackageInstaller via the JS bridge.

### Linux desktop artifacts

Linux ships four desktop artifacts per release, all x64:

| Artifact | Manifest platform | WebKitGTK |
| --- | --- | --- |
| `Clusto-linux-x64-<ver>.deb` | `linux-x64-deb` | system `webkit2gtk-4.1` |
| `Clusto-linux-x64-<ver>.rpm` | `linux-x64-rpm` | system `webkit2gtk-4.1` |
| `Clusto-linux-x64-<ver>.tar.gz` | `linux-x64-tar` | system `webkit2gtk-4.1` |
| `Clusto-linux-x64-<ver>.AppImage` | `linux-x64` | bundled (Ubuntu 24.04) |

**Prefer the package or the tarball.** They link against the system
`webkit2gtk-4.1`, so they follow the host's graphics stack. The AppImage carries
its own Ubuntu 24.04 WebKitGTK. Up to 1.14.51 it also bundled that build's
`libwayland` libraries, which crash against a much newer host Mesa: the WebKit
process dies with `EGL_BAD_PARAMETER` and the window never appears (seen on
RDNA4 + Mesa 26). Later AppImages no longer bundle `libwayland` and use the
host's copy, like `libEGL`.

The tarball is the `.deb` payload repacked (`./usr/bin`, `./usr/share`), so a
system-wide install is `sudo tar -xzf Clusto-linux-x64-<ver>.tar.gz -C /`; it can
also be unpacked into any user-owned prefix and run from there.

The running app reports which artifact it wants as its update platform:

* A real AppImage run (the binary sits inside the AppImage mount `APPDIR`) asks
  for `linux-x64`, and the update replaces the `.AppImage` file itself.
* A binary under `/usr` asks for `linux-x64-deb` when `dpkg` is present,
  `linux-x64-rpm` when `rpm` is, else `linux-x64-tar`.
* Any other location, such as a tarball unpacked into your home directory or an
  AppImage extracted with `--appimage-extract`, asks for `linux-x64-tar` and
  swaps only its own binary. An extracted AppImage is never overwritten with an
  AppImage, so a tree that runs against the system libraries stays that way.

### URL updates from the Cluster view

The **Cluster** view's toolbar exposes update actions once a manifest URL is
configured under **Settings → Updates → Update source**:

* **Check Updates** fetches the configured manifest and refreshes the per-node
  update strips so you can see which nodes are behind.
* **Update All** shows how many nodes are behind. It first opens a list of the
  outdated online nodes with a checkbox each, all ticked; untick any node you do
  not want to update now. Because every selected node restarts, the connected
  node last, it asks for confirmation before it starts. Once confirmed,
  it hands the whole run to the connected daemon in a single
  message. The daemon fetches the manifest, picks the selected nodes whose running
  daemon version is older than it, and runs the update in two phases. First every
  node stages its matching daemon and CLI without restarting. Only when all of
  them are ready do they restart together, the connected node last, so the
  cluster goes through one round of disconnects instead of one per node. A node
  that fails to stage keeps its version and is reported; the others still
  restart. A staged update whose restart signal never arrives (for example the
  driving node died) is discarded after 15 minutes. It reports
  "All nodes already on vX.Y.Z or newer" when nothing is behind, and lists how
  many offline nodes it skipped.

  The run lives on the daemon, not in the app: **you can close the client right
  after confirming and the cluster still finishes the update.** Progress arrives
  as one acknowledgement per node, broadcast to every connected client, so a
  second app (or a reconnecting one) sees the results too. The same is true of
  a single node's **Update** - the download and staging survive a
  disconnect.

Once a manifest version newer than a node is known, its card shows a **vX.Y.Z
available** strip with an **Update** button - on the connected node *and* each
online peer. A single node's **Update** restarts it as soon as its download is
staged; only **Update All** holds the restarts until every node is ready. The button is hidden while a peer is offline, since the update needs
a live connection to it.

After you start an update, from the button or **Update All**, the card shows
**Updating to vX.Y.Z** while the node downloads and stages the release, then
**Restarting to vX.Y.Z** while the app waits for the node to come back. This
continues until the node reports the new version, and a toast then says
"NODE is running vX.Y.Z" (with the node name). A node that has not reported back after 10 minutes
gets a warning toast; check its log if it stays on the old version. While
updates run, the header **Update All** button reads **Updating N...**.
The manifest version is populated by **Check Updates**, the **Check now** button
under *Settings → Updates → Update source*, the daemon's auto-check broadcast,
or the client-side poll.

Node cards still report the installed **CLI** version, but there is no separate
install or update button. **Update** updates the daemon and installs or
updates the matching CLI beside `clustod` in the same operation.

Triggering an update asks the connected daemon to drive it:

* **Connected node**: the daemon runs the same flow as the `update-node --from` CLI path locally.
* **Peer**: the connected daemon forwards a `SelfUpdateFromUrl` over the
  inter-node WebSocket. The peer fetches the manifest itself, picks the daemon
  and CLI artifacts for *its own* platform, verifies both, and restarts (with
  `defer_restart` set, as in **Update All**, it stages and waits for a
  `CommitStagedUpdate` message instead) - the
  manifest URL/token travel over the authenticated peer transport, the binary
  bytes never do. A manifest missing either artifact for the peer's platform
  comes back as a failed update acknowledgement.

Because every node downloads from the manifest URL directly, no node needs to
host binaries for another node's platform.

Both paths run in a detached daemon task. The client's message only starts the
work; the acknowledgement comes back over a broadcast channel when the node
actually finishes, which is why closing the app mid-update no longer cancels
it. Peers are staged concurrently, and the connected node restarts last so it
stays alive to dispatch and report on the others before its own restart.

## Terminals that survive a restart

A node update restarts the daemon, and by default that ends the node's live
terminal sessions. New terminals on Linux and Windows nodes avoid that.

Every new terminal (PTY) session on the node runs in its own small
holder process (`clustod pty-hold`, shown as `clusto-pty` in `ps` on Linux). The
session keeps running through `clusto update-node`, **Update All**, a daemon
restart and a daemon crash or out-of-memory kill. When the daemon is back it
re-attaches: same session id, same tab in the app, scrollback intact. The holder
buffers the last 4 MiB of output, so output produced while the daemon was down is
kept, and full-screen programs such as Claude Code repaint.

* **Linux:** each holder runs in its own systemd unit,
  `clusto-pty-<session id>.service`, inside `system-clusto.slice`, so
  `systemctl restart clustod` leaves it alone.
* **Windows:** the holder is a detached process outside the service, so
  `sc stop` and `sc start` leave it running. Reinstalling the daemon with the
  install scripts keeps holders running.
* **macOS:** not supported. Terminals end on restart as before.

Limits:

* Terminals started before the node upgraded to this behavior still end on restart.
* A machine reboot ends every terminal.
* If a child exits while the daemon is down, the holder keeps its exit status for
  up to 15 minutes, so the session shows as exited instead of vanishing.
* A release that changes the holder protocol says "terminals end on this update"
  in its changelog: a holder and a daemon from different protocol versions do not
  talk, and the daemon ends the old holder.
* The uninstall and purge scripts end holders together with their session
  processes.

`clusto doctor` prints a `Terminal holders: N running` line on Linux when any are
running.

## Producing a manifest

Clients accept only manifests whose entries are signed by a Clusto release key, so
you cannot hand-write a manifest for your own builds. Clusto's release pipeline
signs each manifest when it publishes. To run your own update source, mirror the
published release: copy the signed `manifest.json`, the artifact files it
references, and `flags.json` onto your static host unchanged.

`url` is the one entry field the signature does not cover, so a mirror may rewrite
it, or leave it relative so the files resolve next to the manifest. Do not edit any
other field: a changed filename, hash, size, or version makes the entry fail
verification and the whole manifest is rejected. A mirror also cannot serve a
manifest older than what a client already runs; downgrades are refused.

See [One release track](#one-release-track) for how releases are published.

## Security model

* **Release signatures** are the integrity check. Every manifest entry carries an
  Ed25519 signature made with a Clusto release key. The matching public keys are
  built into the daemon, the CLI, the app, and `install.sh`: the current key plus a
  next key pinned ahead of a rotation. A client accepts an entry only when a
  signature from one of those keys verifies, so a compromised download server or
  mirror cannot get its own binary installed. Signatures from other keys are
  ignored, which lets a key rotation release carry both keys' signatures.
* **SHA-256 and size** from the signed entry are verified on every artifact after
  download; a mismatch aborts the install and deletes the staged file.
* **No downgrades.** The CLI, the daemon, and the app refuse a signed release older
  than the version they are running, with no override. This stops an old, signed,
  vulnerable build from being replayed through a stale manifest. Installing the same
  version again is allowed as a repair.
* **Transport.** Manifests and artifacts are fetched over `https://` only (plain
  `http://` is allowed for a loopback host, for testing a local mirror), and
  redirects must stay within that rule. The bearer token goes only to the manifest's
  own origin.
* **Signed flags.** `flags.json` is signed the same way and carries an issue
  counter. A node ignores an unsigned or altered file, and a file issued earlier than
  one it already accepted. See [Feature Flags](/feature-flags).
* **Peer and client pushes are gone.** A node installs a daemon only from a signed
  manifest it fetched itself. A peer cannot push a binary to it, and the daemon's
  client-download endpoint serves only artifacts whose signature, size, and hash it
  has verified.
* **Staged files.** The daemon records the signed entry next to each file it stages
  (`<file>.release.json`) and re-checks it, with the file's size and hash, before
  listing or serving the file to a client. A file with no valid record is not served;
  the daemon writes the record for an earlier staged file when it next sees a manifest
  entry that matches it exactly.

## Pre-existing alternatives

The remote-URL flow doesn't replace the app's own update path - it sits
beside it: **Settings > Updates > App updates** downloads the app from the
connected daemon's bundled client artifacts when they are newer than the
running build.

Use the remote-URL flow when there is no upstream daemon to pull from, or
when you want one URL to be the source of truth across an unmanaged fleet.
