---
url: https://clusto.app/docs/migrating-from-hive.md
description: >-
  Move from the old Hive desktop client and daemon layout to the separate Clusto
  application safely.
---

# 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](/configuration#moving-a-node-from-hive-to-clusto).

## 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](/knowledge#daemon-install)).

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](/knowledge#this-computer-s-node)).

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](/configuration#moving-a-node-from-hive-to-clusto) 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](/cli#clusto-doctor-check-this-node-s-daemon-install-cluster-and-ai-setup)
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.
