Config Sync

Selective, on-demand sync of Obsidian settings — hotkeys, CSS snippets, themes, plugin configs — across devices and vaults. The data rides your existing note sync (remotely-save, Obsidian Sync, iCloud…) by default, or config-sync's own git / vault remotes. Nothing ever lands on a device without an explicit Apply from the Sync Center.

[!IMPORTANT] Update every device before any of them captures or pulls again. This release moves the settings and the store to a new format, and the move is one way. A device still on 2.21.0 meets the new format, refuses it with a plain message and changes nothing. A device on 2.20.0 or earlier resets its Config Sync settings to defaults — that one cannot be fixed afterwards. Update Config Sync everywhere first, then carry on as usual. Three things also behave differently afterwards: see Updating from 2.21.0 and earlier.

Features

• One card per item — every synced thing (an Obsidian option group, a core or community plugin, a snippet) is one row with an expandable drawer holding its rules; a plugin's on/off state lives on its own card. (details)
• Orthogonal field rules — every key carries a {sharing, encrypted} pair (All devices / Desktop only / Mobile only / This device), and string-array keys can give each element its own sharing rule. (details)
• Credential-safe — This device keys never leave the machine, and a per-device passphrase encrypts what should travel.
• Explicit Apply — nothing changes a device until you tick items and press Apply; every run stays visible in the pinned result strip and a browsable History.
• A Sync Center that knows the state — every row spells out its own fate in plain language (turns on · installs · applies settings), normalized JSON diffs, a this device status chip and totals for every pending action. (tour)
• Install engine — plugins that are outdated, disabled or missing on this device can be updated, enabled or installed during Apply, pinned to the captured version. (rules)
• Remotes (desktop) — pull/push the store against a git repo or another vault, with per-file diff previews. (details)
• Safe to update one device at a time — settings or a store written by a newer Config Sync are refused with a plain message, never reset or overwritten, and a device's own choices (what it opted out of syncing) stay on that device where a pull can't erase them. That protection starts at 2.21.0; see the notice above before updating from anything older. (details)
• Search everywhere — both search boxes accept key:value qualifiers with autocomplete (section:, type:, action:, mode:, device:), combined freely with plain text.
• Status bar — ↑ capture / ↓ apply plus per-remote ⇡ push / ⇣ pull counts at a glance; click opens the Sync Center.
• Mobile-friendly — capture, apply and the Sync Center work on phones; the store is plain vault content, so any note sync carries it.

Install

From Obsidian: Settings → Community plugins → Browse, search Config Sync, install and enable.

Beta builds: via BRAT, add xooooooooox/obsidian-config-sync.

Quick start

1. Settings → Config Sync — tick what you want to sync (Obsidian / Core plugins / Community plugins / Beta tabs).
2. Open Sync Center from the ribbon menu (or the Open Sync Center command), tick what to capture, and press Capture N items.
3. On another device, once your note sync has delivered the data folder: open Sync Center, tick what to apply, and press Apply N items.

How it works

Two planes, kept separate.

• Local plane — Capture copies every enabled item's settings files and companion folders into the store, applying each field's {sharing, encrypted} rule; Apply lands the items you tick into this device's config dir. Direction (↑ capture, ↓ apply) comes from a per-device sync baseline, not file times, so the Sync Center can tell which side actually moved.
• Transport plane — by default the store is plain vault content and rides your note sync; a fresh device discovers an arriving store on its own and offers an Adopt guide. Optionally (desktop), Pull/Push move the store against a git repo or another vault from the Sync Center's Remotes block.

The full tour — Sync Center anatomy, field rules, encryption, the install engine, remotes, walkthroughs — lives in the user guide.

Security & privacy

Everything the plugin does by default stays inside your vault: Capture/Apply copy files between your config folder and the data folder, and your own note sync moves them between devices. Three optional, desktop-only remote behaviors go further and are disclosed here:

• Network use (git remotes only). If you add a git remote under Settings → Remotes, Pull/Push run the git binary against the URL you configured — that is the only network access the plugin ever performs. No telemetry, no other endpoints.
• Files outside the vault (vault remotes and git temp clones). If you add a remote of type "Another vault", Pull/Push read/write the absolute store path you configured (typically another vault's data folder). Git pushes additionally use a temporary clone directory that is removed afterwards.
• Access tokens (git remotes only). A token you link to a git remote is held in Obsidian's own keychain on that device and handed to git through the environment, never through the command line. Only the secret's name is written to the plugin's settings — the token itself never enters data.json, the store, or any error message. Config Sync never sends the remotes list anywhere either (it is a locked this-device field), so the name reaches another device only if your own vault sync copies the plugin's data.json; each device links its own token, or none at all.

All three are inert until you configure a remote, and never run without an explicit Pull or Push from the Sync Center.

Documentation

• User guide — every behavior in one place: the Sync Center, field rules, sensitive settings, transport, walkthroughs.
• Architecture — code map and invariants, for contributors.

Development

npm install
npm run dev     # watch build
npm test        # vitest
npm run build   # type-check + production bundle

Develop against a dedicated test vault (never a real one).

License

MIT