Skip to content

Change History and Restore ​

Cluster replication and account cloud sync spread a change to every device within seconds. That is what you want, until the change is a mistake: a bad update that rewrites your settings, a connection profile deleted by accident, a node removed from the cluster. Clusto keeps history at each layer so any of those can be put back.

Recording and viewing history is always on and free on every plan. The restore actions are behind the cluster release flag settings.history, which is off by default. Turn on Change history restore in Settings > Labs to use them. Without the flag you can still browse everything and read every diff.

Open it from Settings > History, or press F1 and choose Open change history. Two more entry points open the matching part of the page: Recently removed nodes in cluster settings and Recently deleted on the connect screen.

This device ​

The This device tab covers what lives in this app.

Settings changes ​

A log of every change to your app settings, kept for 90 days on this device only. Each entry shows the before and after value and where the change came from:

SourceMeaning
This DeviceYou changed the setting here
Cloud SyncA pull from your account cloud sync changed it
Cluster PullA pull of Cluster Preferences changed it
App UpdateAn app update changed it
RestoreA restore from this page put it back
  • Undo last change reverts the newest settings change. A pull that changed many settings at once is reverted as one step, and you can repeat it to walk further back. F1 has Undo last settings change too.
  • Undo this change puts one entry back.
  • Undo this and later changes puts every setting changed since that point back to its earlier value, after a confirmation.

Every undo is recorded as a Restore entry, so you can undo the undo. Some settings apply after a reload and the page offers Reload now. Values too long to keep in full, and entries kept encrypted on this device, are marked and cannot be restored.

Recently deleted connection profiles ​

A connection profile you delete, including one removed because a sync pull from another device carried the deletion, is kept for 30 days. The full profile, token included, is stored encrypted with a device key that cannot be exported, so a copy of the data is useless on another machine. Restore brings the profile back on this device and, with cloud sync on, on your other devices. If a profile with the same name exists, restoring replaces it and the dialog says so. Remove forgets a copy early.

Cloud ​

The Cloud tab lists earlier versions of your encrypted account sync data. Turn on and unlock cloud sync first.

  • Each version is the state before a write, shown with the time and, for a checkpoint, why it was saved: profile deleted, pull override, push override, app updated or restore. Checkpoints are the safe points kept around destructive writes.
  • Pick a version to compare it with this device: connection profiles and settings that exist only in the version, only on this device, or differ.
  • Restore everything or Restore selected (tick the profiles and settings you want). The version is decrypted on your device, never on the server. The current state is saved as a new version first, so a restore can be undone, and the result syncs to your other devices. Profiles that exist only on this device are kept.
  • A version saved before you changed the sync passphrase needs the old passphrase to open.

How long versions are kept depends on your plan:

PlanKept forVersions
Personal30 daysup to 300
Pro and Team180 daysup to 1000

Frequent writes are thinned: the newest version per 10 minutes is kept for the last day and the newest per day before that, while every checkpoint is kept. Everything else on this page is free on every plan.

Nodes ​

The Nodes tab is a cluster-wide list of changes recorded by each node. You can filter by kind and by node; a note names any node that did not answer. Open an entry to see a before and after diff.

KindWhat is recorded
ConfigEach change to the node's config.toml
Project, Task, Workspace (chat workspace), SSH Connection, TeamThe earlier state when you edit or delete one
NodeA node removed from the cluster

Restore puts the earlier state back through the normal save path, so it replicates to the rest of the cluster like any other change, and the restore is recorded as a new entry. It asks you to confirm first.

  • Config restore writes the earlier config.toml back and restarts that node to apply it. The daemon token and cluster token stay at their current values.
  • Removed nodes cannot be restored in place. A node removed from the cluster forgets the cluster, so it has to be paired again. Re-add node opens Add node pre-filled with the recorded address; you still need a fresh pairing code from that node. See Node Identity & Pairing.
  • Deleted teams are not restorable. Edits to a team are.

History is kept per node and not replicated: a node that is gone takes its record history with it. Your cloud versions and the knowledge backups are the off-cluster copies.

Node config history ​

Every change to a node's config.toml is saved as a version: up to 100 versions and 180 days, with the changed keys noted.

Secrets in the config are kept so a restore is complete, but each one is encrypted with AES-256-GCM under a separate history.key file in the node's data directory. The key is kept outside the config directory, readable only by the node's account. A diff shows that a secret changed, never its value. A restore puts secrets back, except the daemon token and cluster token, which stay current (the offline restore below can bring them back on request).

Before every self-update the node also saves its config and a copy of its database (the newest 3 are kept). The database copies are restored only with the daemon stopped, from the command line.

From the command line ​

clusto history works over the daemon, against the whole cluster:

bash
clusto history list [--kind <kind>] [--node <node>] [--limit <n>] [--json]
clusto history show <id> [--node <node>] [--json]
clusto history restore <id> [--node <node>]
  • list prints entries newest first from every node. --kind is one of config, node, project, task, chat_workspace, team or ssh_connection. --node takes a node id or name. --limit defaults to 50.
  • show prints the entry with a diff of its state before and after. --json prints the entry with the two texts instead.
  • restore needs the settings.history flag. --node names the node that recorded the entry; it defaults to the node you are connected to. Restoring a config restarts that node.

When the app or the daemon is broken, recover from the files on the node. These commands read the node's own files and need --offline:

bash
clusto history config --offline [--config <path>] [--json]
clusto history restore-config <version> --offline [--config <path>] [--data-dir <path>] [--include-auth-tokens] [--force]
clusto history restore-db <version> --offline [--config <path>] [--data-dir <path>]
  • config --offline lists the config versions and the pre-update databases.
  • restore-config writes a config version back. Stop the daemon first: it refuses while one runs unless you pass --force, and a running daemon may save over the restore. The admin and cluster tokens stay current unless you add --include-auth-tokens, which locks out any client or peer using the newer ones.
  • restore-db copies a pre-update database back, named by the release it was taken from. The daemon must be stopped. The current database is kept next to it as data.sqlite3.before-restore.

--config and --data-dir default to the standard locations. See the CLI reference.

Agents ​

The clusto MCP server gives agents two read-only tools, clusto_change_history (list entries, optional kind, node and limit) and clusto_change_entry (one entry with its before and after). The Assistant has them too, so you can ask it what changed in a config. Config diffs show that a secret changed, never its value. Agents in sessions can read history but never restore it. See Knowledge.

Clusto - remote AI coding agents over WebSocket.