---
url: https://clusto.app/docs/cluster-preferences.md
description: Share Clusto app preferences across every client connected to a cluster.
---

# Cluster Preferences

Clusto can store the app's local user preferences (theme preset, custom
CSS, and any other `clusto-*` `localStorage` key) on the connected
daemon and share them across every client that joins the cluster.

By default every client keeps preferences in its own `localStorage` - this
feature is opt-in: nothing is uploaded until the user clicks
**Save to cluster**, and the cluster blob is never auto-applied to a client
until they click **Pull from cluster**.

## Where to configure

**Settings → Cluster**, card **Sync preferences with cluster**. The card shows:

* **Cluster value updated** - the timestamp on the blob the connected daemon
  currently holds, refreshed automatically on (re)connect.
* **Save to cluster** - snapshots every `clusto-*` key in the running client's
  `localStorage` and pushes the blob to the daemon. The daemon persists it to
  `cluster_preferences.json` and, in cluster mode, broadcasts it to every peer.
* **Pull from cluster** - fetches the latest blob from the daemon and compares
  it with this device first (see below). After you confirm, it replaces every
  synced `clusto-*` key in `localStorage` (keys not in the blob are removed),
  and reloads the window so module-level composables re-read their state.
* **Undo last pull** - shown after a pull. Puts back the settings this device
  had before that pull and reloads.
* **Refresh** - re-fetches the cluster timestamp without touching local state.

The buttons are disabled when no daemon is connected. **Sync preferences with
cluster** in the F1 command palette opens this card.

## Pull confirmation and undo

The blob on the cluster may have been saved from a different device (another
OS, screen size or input method), and settings that suit that device can make
this one slow or hard to use. A pull therefore never writes anything until you
confirm:

1. The app fetches the blob and diffs it against this device's synced keys.
2. If nothing differs, it says so and stops.
3. Otherwise a dialog says how many settings it would replace, when the cluster
   copy was saved, and how many are changed, new or removed, followed by the
   names of the affected settings (the first eight, then a count). **Cancel**
   is the default and leaves everything as it is.
4. **Replace settings** first saves a one-level backup of this device's synced
   settings under `clusto:cluster-preferences-backup` (a key no sync carries),
   then applies the blob and reloads. If the backup cannot be written, the pull
   stops with an error instead.

**Undo last pull** restores that backup and removes it. A newer pull replaces
the backup, so only the most recent pull can be undone. **Save to cluster** has
no confirmation: it changes the cluster copy, not this device, and every other
device still has to confirm before pulling it.

## What gets synced

Everything the app writes under the `clusto-` `localStorage` prefix, which today
includes:

* `clusto-theme-preset` - selected appearance preset (or `custom`).
* `clusto-theme-custom-css` - the user's custom CSS overrides.
* `clusto-theme-custom-mode` - whether the custom theme is light or dark.
* The date and time format chosen in [Appearance](/appearance#date-and-time).
* `clusto-session-appearance` - the session title template, color rules and
  project overrides from [Appearance](/appearance#session-colors-and-titles).

Anything else the app adds under that prefix is picked up automatically.

### Device-local keys

Some `clusto-*` keys describe the device rather than your preferences, so they
are never pushed, never applied by a pull, and never deleted by one. Account
[cloud sync](/cloud-sync) uses the same rule. A blob saved by an older build
may still carry them; they are ignored.

* Battery saver (`clusto-battery-*`) - when a backgrounded app disconnects.
* On-screen keyboard mode (`clusto-terminal-keyboard-mode`) - touch devices only.
* Panel widths and split ratios (`clusto-nav-width`,
  `clusto-right-sidebar-width`, `clusto-notes-tree-width`, the GitHub and
  Azure DevOps list widths, and the editor, notes editor and design
  splits), sized for this screen.
* What is open on this device: open note tabs and the active tab, the notes
  tree and folder collapse state, hidden design previews and chat read markers.
* When this device last backed up the notes vault to the cloud.
* Usage-data state (`clusto-telemetry-*`): install id, consent and queue.

The retired update-channel preference key is skipped. Keys *outside* the `clusto-`
prefix are intentionally not synced. The remote-update settings stored at
`clusto.remoteUpdate.settings.v1` are a notable
example: those have their own daemon-side persistence in `config.toml` and
are replicated separately via `PeerMessage::SyncRemoteUpdateConfig`.

## How it's stored and replicated

* The daemon keeps an in-memory `ClusterPreferences { values, updated_at }`
  blob plus a JSON file at `<config_dir>/cluster_preferences.json`. The file
  is restored on daemon start, so a restart preserves the last-written value.
* `updated_at` is Unix milliseconds, stamped server-side at `Set` time so a
  client with a skewed clock cannot poison ordering.
* In cluster mode, every `Set` is broadcast as
  `PeerMessage::SyncClusterPreferences`. Receivers apply the incoming blob
  only when its `updated_at` is strictly newer than their local copy -
  last-writer-wins on the whole blob.
* Every connected client receives the new blob as
  `ServerMessage::ClusterPreferences`, but the desktop app does **not**
  auto-apply it; the user must click **Pull from cluster** to overwrite
  local state.

## Conflict resolution

Whole-blob last-writer-wins. A second client clicking **Save to cluster**
right after the first one wins because the daemon stamps a newer
`updated_at`. There is no per-key merge; if you push, you push everything
your client has under `clusto-*`.

## Wire protocol

* `ClientMessage::GetClusterPreferences` → `ServerMessage::ClusterPreferences`.
* `ClientMessage::SetClusterPreferences { preferences }` → daemon persists,
  broadcasts to peers, and replies/broadcasts `ServerMessage::ClusterPreferences`.
* `PeerMessage::SyncClusterPreferences { preferences }` - peer-to-peer
  replication of the blob (LWW on `updated_at`).
