Appearance
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). 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:
kindis one ofdaemon,cli,app_installer,android_apk.platformslugs:windows-x64,linux-x64,linux-arm64,macos-x64,macos-arm64,android-arm64.urlis the location of the artifact bytes. Absolute URLs are used verbatim. Relative URLs are resolved against the manifest URL, so a folder layout likehttps://updates.example.com/clusto/{manifest.json,clustod,clusto,...}works out of the box.build_dateis optional. When present, it is written next to the artifact as a<filename>.builddatesidecar - the daemon's artifact picker uses that to prefer fresh builds over stale siblings.sha256must be the lowercase hex digest of the artifact bytes. Mismatch aborts the update and removes the partial file.version(X.Y.Z) andsignaturesare required on every entry. The signature covers the entry's kind, platform, version, filename, SHA-256, size, and build date.urlis 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-levelversionandbuild_dateare 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/manifestThe 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 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. 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:
- The A0 client fetches its manifest from
dl.vazac.devand receives the frozen 1.14.5 manifest. - It downloads the A1 daemon and matching CLI from
dl.clusto.appand performs the layout handoff. - A1 migrates the stored endpoint to the canonical Clusto origin.
- 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_urlfield inconfig.tomldrives 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-channelpreference 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.
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.
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>.partialsidecar as they arrive; if the transfer is interrupted (you leave, the socket drops, the app restarts), the next attempt sends an HTTPRangerequest and resumes from where it left off instead of starting over. The daemon's/clients/{kind}/{platform}endpoint advertisesAccept-Ranges: bytesand answers206 Partial Contentto 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 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 inconfig.tomland broadcasts to every cluster peer viaPeerMessage::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
localStorageonly. 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; after that, updates arrive over the connection. A node run by the app in local mode 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, 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 hoursmanifest_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).
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.
Auto-check + manual install confirmation
When auto_check = true and manifest_url is set, clustod spawns a background task at startup that:
- Sleeps for
interval_secs. - Fetches the manifest, compares its
versionagainstenv!("CARGO_PKG_VERSION"). - If newer, broadcasts
ServerMessage::RemoteUpdateAvailableto 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.
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.jsonA 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 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 forlinux-x64, and the update replaces the.AppImagefile itself. - A binary under
/usrasks forlinux-x64-debwhendpkgis present,linux-x64-rpmwhenrpmis, elselinux-x64-tar. - Any other location, such as a tarball unpacked into your home directory or an AppImage extracted with
--appimage-extract, asks forlinux-x64-tarand 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 --fromCLI path locally. - Peer: the connected daemon forwards a
SelfUpdateFromUrlover the inter-node WebSocket. The peer fetches the manifest itself, picks the daemon and CLI artifacts for its own platform, verifies both, and restarts (withdefer_restartset, as in Update All, it stages and waits for aCommitStagedUpdatemessage 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, insidesystem-clusto.slice, sosystemctl restart clustodleaves it alone. - Windows: the holder is a detached process outside the service, so
sc stopandsc startleave 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 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 (plainhttp://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.jsonis 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. - 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.