---
url: https://clusto.app/docs/change-history.md
description: >-
  Change history and restore - the Settings > History page, undo for settings,
  recently deleted connection profiles, cloud sync versions, node config and
  record history, the clusto history CLI and the read-only MCP tools.
---

# Change History and Restore

Cluster replication and [account cloud sync](/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](/feature-flags) `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:

| Source | Meaning |
|---|---|
| This Device | You changed the setting here |
| Cloud Sync | A pull from your account cloud sync changed it |
| Cluster Pull | A pull of [Cluster Preferences](/cluster-preferences) changed it |
| App Update | An app update changed it |
| Restore | A 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](/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:

| Plan | Kept for | Versions |
|---|---|---|
| Personal | 30 days | up to 300 |
| Pro and Team | 180 days | up 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.

| Kind | What is recorded |
|---|---|
| Config | Each change to the node's `config.toml` |
| Project, Task, Workspace (chat workspace), SSH Connection, Team | The earlier state when you edit or delete one |
| Node | A 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](/node-identity).
* **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](/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](/cli#clusto-history-change-history-and-restore).

## 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](/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](/knowledge#mcp-tools).
