Skip to content

Moving from Hive to Clusto ​

Clusto is installed as a separate application identity. It uses the Clusto name, the dev.vazac.clusto desktop and mobile identity, the clusto CLI, and the clustod daemon.

Desktop profiles start clean ​

Clusto does not copy Hive desktop profiles, cached settings, app credentials, or device activation state. This prevents the two application identities from sharing credentials or silently consuming the same activation.

After installing Clusto, add the connection again from Connection, or sign in and restore it from encrypted cloud sync if it was already synced. Keep the node token available before removing the old client. On an A0 node, hive daemon get-token prints the local token; after the handoff, use clusto daemon get-token.

Windows installer cleanup ​

The Clusto NSIS installer removes recognized Hive desktop-client installs before it copies Clusto:

  • The installer checks the known Hive 1.11.0 MSI product key directly in the machine-wide and per-user registry views. It removes the MSI only when the product code, display name, publisher, Windows Installer marker, and version all match the shipped package. Exit codes for already-absent products and reboot-required success are handled explicitly.
  • The Hive NSIS client is accepted only when its registry entry identifies the shipped per-user uninstaller under %LOCALAPPDATA%\Hive or %LOCALAPPDATA%\Programs\Hive.
  • The validated uninstaller runs first. The old Hive application directory, Add/Remove Programs entry, and Hive desktop and Start-menu shortcuts are then removed.

The installer never scans the full Windows uninstall registry or executes an arbitrary uninstall command from it. The registry work is fixed and the installer cannot remain on Checking for a previous Hive install after reaching the end of the uninstall entries. If a recognized uninstall fails or its registration remains, Clusto stops the installation instead of leaving two desktop identities.

Every legacy uninstaller runs with a 120-second timeout, and leftover hive-app.exe, hive.exe, and clusto.exe processes are terminated before files are copied. A blocked msiexec or an uninstaller waiting on a hidden prompt therefore fails with a message naming the timeout instead of freezing the progress bar. Remote client updates apply the installer with a 600-second cap and relaunch the app if that cap is hit; the transcript is at %TEMP%\clusto-update.log.

This cleanup is limited to desktop-client registrations and validated client directories. It does not delete daemon configuration, the session database, attachments, or the migration journal. Node state moves through the journaled layout migration described in Configuration.

Node handoff ​

An A0 node must have a verified rollback backup and a clean migration dry-run before it takes the epoch-2 Clusto update. The detached helper replaces the old hived service with clustod, moves the recorded state to the Clusto layout, and checks health before completing.

If the node still uses dl.vazac.dev, expect a two-hop update. Both legacy manifests (the old stable and unstable ones) are frozen at A1 1.14.5, and they download the A1 artifacts from dl.clusto.app. Once the A1 daemon starts, it repoints the stored update endpoint (a hive.vazac.dev or dl.vazac.dev manifest, or the retired manifest-unstable.json) to the release track https://clusto.app/ on load, not only after the layout handoff. Run another update check to take the newest release available there. The legacy origin never advances beyond 1.14.5.

Inspect the current node without changing it. The easy way is clusto doctor, which prints one diagnosis (see below). The detailed report is:

bash
hived migrate-layout --dry-run

On Windows the daemon is a GUI-subsystem program, so its dry run prints nothing in a console unless the output is piped:

powershell
& "C:\Program Files\Hive\hived.exe" migrate-layout --dry-run | Out-String

If the cutover is skipped, a node still running hived logs a Clusto layout cutover skipped warning with the reason (see it with clusto logs daemon --node <id>), and the dry run prints a cutover blocked by: ... line. A cutover that rolled back is retried once by each newer daemon version.

Stale binaries block the cutover ​

An early aborted cutover can leave clustod.exe and clusto.exe next to hived.exe in C:\Program Files\Hive. Every later attempt was then skipped with both ...hived.exe and ...clustod.exe exist, so the node stayed on hived forever. The daemon now renames such leftovers to <name>.stale-<timestamp> before the cutover check, and the node switches to clustod on its next restart or update. It does this only while it runs as hived with its rollback backup staged, no cutover in progress and no clustod service registered. You can also trigger it from Settings > Node Doctor: a node still on hived shows a Daemon install row, and Fix repairs it remotely (see Node Doctor).

If the node is the computer you are sitting at and its hived daemon is too old to report that row, Node Doctor shows a This computer's node row instead. Fix upgrades it in place after one administrator prompt (see Node Doctor).

Do not manually move the daemon database or populate the destination paths. An existing Clusto directory is merged entry by entry. Only an entry with the same name on both sides is a collision, and it must be inspected before the update continues. On Windows the Clusto desktop app already writes its logs into the per-user data directory, so that directory normally exists before the cutover and is merged rather than blocking it.

After the cutover, anything left in the Hive config directory (TLS certificates, cluster_preferences.json, config backups) is moved into the Clusto config directory on the next start. Names that already exist there go to a hive-leftovers/ subfolder, and nothing is overwritten or deleted. See Configuration for details.

Repair or finish a stuck node ​

clusto install upgrades a Hive-era node in place. It never creates a second daemon next to the old one. It prints the clusto doctor diagnosis and asks Repair the existing node now? [Y/n]; --non-interactive repairs without asking, and --json never repairs and fails with the diagnosis. The one-line installers tell you the same: install.sh detects a hived unit or binary, and install.ps1 runs clusto doctor when clusto install fails.

To check a node, run:

bash
clusto doctor

It reports the clustod and hived services, Hive-era state on disk and the cutover journal (C:\ProgramData\Clusto\migration on Windows, /var/lib/clusto-migration on Linux; reading it needs an Administrator terminal or sudo), then one diagnosis. To repair what it finds, run it from an Administrator terminal on Windows or with sudo on Linux:

bash
clusto doctor --fix

For a Hive-era node, --fix starts hived, updates it to the current release through the normal node self-update, and waits up to 5 minutes for the daemon's own journaled cutover to replace hived with clustod. Data, token and sessions are kept. If the cutover does not happen, it prints the daemon's own blocker reason. When the cutover journal already holds a rollback backup, it installs the daemon program bundled in clusto in place of hived instead of using the network update. A cutover that stopped part-way (hived runs again, or the journal has not moved for 10 minutes) is first rolled back with the bundled daemon, so the retry runs the current release's migration code. It also starts a stopped clustod, stops and disables a hived that runs next to clustod, and removes a stale hived registration or a clustod registration left by a rolled-back cutover. A cutover that rolled back shows its target version and recorded error, and each newer daemon version retries it once.

Hive data with no daemon is never touched automatically. Move it away yourself if you want a fresh install. See the clusto doctor reference for every diagnosis.

Verify the result ​

On a migrated node:

bash
clusto doctor
clusto daemon status
clusto version

Only clustod should be active. The old service may remain disabled during the rollback window, but it must not run beside clustod. In Windows Apps and Features, only Clusto should remain as the desktop application.

Clusto - remote AI coding agents over WebSocket.