☁️ CouchDB Sync for Obsidian

[!WARNING] Alpha — under active development. This is an early alpha release. It works and is genuinely useful, but it still has known bugs and rough edges, and behaviour may change between versions. Please keep backups of important vaults and expect the occasional hiccup. Bug reports are very welcome — thank you for helping shape it. 🙏

Keep the same notes on every device — on your own server, readable only by you.

Write a note on your laptop and it appears on your phone. Edit it on the train and your desktop has it when you get home. Nothing goes through a company's cloud: your notes travel to a server you choose, and they are locked before they leave your device, so whoever runs that server sees nothing but scrambled data.

There are no pop-ups to click away and no "rebuild your database" rituals. One switch says whether this vault syncs, and a panel shows you the honest truth about every single file.

---

🌱 New to syncing? Start here

Three ideas cover almost everything:

Term	What it means for your vault
🗄️ Server	The meeting point. Every device uploads its changes there and picks up everyone else's. It runs CouchDB — free, open-source database software. You can rent one for a few euros a month or run it on a computer at home.
🔐 Passphrase	A secret sentence you invent. It locks your notes before they leave your device and unlocks them on the other side. The server never learns it, so it must be exactly the same on every device. Lose it and your notes cannot be recovered — write it down somewhere safe.
🔄 Sync	The continuous back-and-forth. Once it is switched on, it just runs: you edit, it uploads; someone else edits, it downloads.

The short version of a normal day: you write notes and never think about this plugin again. It is running in the background, and the status bar at the bottom of Obsidian quietly tells you how things are going.

You need a server for this. That is the one piece of setup this plugin cannot do for you. Getting a server walks through the options, from "pay someone else to run it" to "run it yourself in one command".

---

What you get

🔐 Everything is encrypted before it leaves

Encryption is on by default and covers more than most sync tools: not only what you wrote, but also your file names, folder structure, file sizes and timestamps. Someone who steals the whole server database gets a pile of numbered blobs — no titles, no folder names, no hints.

📊 A status panel that tells you the truth

Open it from the status bar and see how many files are in sync (1,284 / 1,284 · 100%) plus a folder tree of every file, colour-coded:

	State	What it means
🟢	In sync	This file is identical here and on the server. Nothing to do.
🟠	Local only	It exists here but hasn't been uploaded yet.
⚪	Remote only	It exists on the server but hasn't been downloaded here yet.
🟣	Differs	Both sides changed. The plugin will reconcile it automatically.
🔴	Conflict	Two devices edited it at the same time. Handled by your chosen rule — see below.

Folders show the most urgent state inside them, so a green folder really means "everything in here is fine". Files being transferred right now shimmer and show their progress.

🕰️ Every version, kept

The plugin keeps a history of each note (the last 50 versions). Open it, compare any two versions side by side, and restore an older one on all devices with one click. Restoring is itself just another version, so you can always undo the undo.

⚖️ Conflicts without pop-ups

If two devices edit the same note before they can talk to each other, the plugin resolves it by a rule you pick once — either the newest edit wins, or one device you nominate always wins. It never interrupts you to ask. And because every version is kept, the other version is never actually gone.

📦 Big files, small memory

Photos, PDFs, audio, video — files are cut into 1 MB pieces and only the changed pieces are uploaded. Identical pieces are stored once, even across different files. A 600 MB file syncs without Obsidian ever holding it in memory.

🛟 Hard to break

Sync is one switch, and it is honest: on means running, off means nothing touches the network. If Obsidian ever shuts down uncleanly mid-sync, the plugin starts up switched off and tells you why, so you can never land in a loop that crashes on every launch. "Wipe local cache" only ever touches this device — the server is never harmed by anything you can press here.

---

🚀 Getting started

🧩 Step 1: Get a server

Pick whichever fits you. All you need at the end are four things: a web address, a database name, a username, and a password.

Option A — let someone host it for you (easiest). Search for "CouchDB hosting"; providers like IBM Cloudant or a small managed CouchDB plan give you a URL and login without any admin work. Make sure the address starts with https://.

Option B — run it yourself. If you have a home server, a NAS (Synology and Unraid both offer CouchDB), or a small cloud VM, CouchDB installs in minutes. If you have Docker, a test server is literally one command from this repository:

docker compose -f docker-compose.couchdb.yml up -d

That gives you http://127.0.0.1:5984 with user admin and password password — perfect for trying things out on one computer. Change that password and use https:// before you sync anything real over the internet.

One-time server setting. However you got your server, open its configuration and add this. It lets Obsidian talk to it and allows large files:

[chttpd]
enable_cors = true
require_valid_user = true
max_http_request_size = 4294967296
[cors]
origins = app://obsidian.md,capacitor://localhost
credentials = true

Finally, create an empty database (the default name this plugin expects is obsidian).

🔌 Step 2: Connect Obsidian

Open Settings → CouchDB Sync and fill in the four things from Step 1:

1. Server URL — the full address, e.g. https://couch.example.com:6984
2. Database name — e.g. obsidian
3. Username and Password
4. Press Test connection. Green means you're good.

🔑 Step 3: Choose your passphrase

Leave End-to-end encryption on and type a Passphrase. Invent something long that you can write down — a short sentence works well.

⚠️ Write it down now. The passphrase never reaches the server, which is the whole point — but it also means nobody can reset it for you. And it must be typed identically on every device, or they will not understand each other's notes.

▶️ Step 4: Let it run

Make sure the switch in the status card says Sync on. That's it — your notes start uploading, and sync restarts by itself every time you open Obsidian.

📱 Step 5: Add your next device

Install the plugin there, enter the same server details and the same passphrase, switch it on, and wait. Your vault downloads itself. If you use the master device wins rule, turn on This device is the master on exactly one device — usually your main computer.

---

🎛️ Using it day to day

The status bar (bottom edge of Obsidian) is two controls in one:

• the icon switches sync on and off
• the label (CouchDB 63%) opens the full status panel in the sidebar

The status panel is the same panel embedded in the settings tab — same tree, same buttons. From it you can:

• press Force sync to run a full pass right now
• expand the tree and hover any file for a ⋯ menu with only the actions that make sense for it: download / overwrite local, upload / overwrite server, sync once, delete on this device, delete everywhere, remove from index
• click 🕘 to browse, compare and restore that file's versions
• apply any of those to a whole folder at once

---

🧩 Requirements

• Obsidian 1.7.2 or later
• A CouchDB server you can reach (Step 1)
• Tested and validated on desktop. Mobile is supported by design (the plugin uses Obsidian's own networking, so it works without special server tweaks) but has not yet been through a full mobile test round.

---

⌨️ Commands

Available from Obsidian's command palette (Ctrl/Cmd + P).

Command	What it does
Open sync status panel	Opens the panel in the sidebar
Force sync	Runs a full sync pass right now
Turn sync on/off	The master switch, without leaving your keyboard
Wipe local cache (does not download)	Clears this device's local copy only
Show what's new	Re-opens the release note for the installed version

⚙️ Settings

Setting	Default	What it does
Server URL	(empty)	Your server's full web address, including https://
Database name	obsidian	Which database on that server to use
Username / Password	(empty)	Your login for the server
Test connection	—	Checks all of the above, and unlocks the status view
End-to-end encryption	on	Locks note content and file names, sizes and dates before upload
Passphrase	(empty)	Your secret. Must be identical on every device
Conflict strategy	newest wins	Who wins when two devices edit the same note
This device is the master	off	With master wins: this device's version always wins. Turn on for exactly one device
Live sync (real-time)	on	Keeps changes flowing continuously. Off = only when you press Force sync
Sync hidden files	off	Also sync .obsidian (your settings, themes, plugins), .git, etc.
…except these	a safe default list	With hidden sync on: which hidden folders to leave out
…but still sync these	(empty)	With hidden sync off: which hidden folders to include anyway
Download from server	—	One-way catch-up: pull everything, upload nothing
Wipe local cache	—	Deletes this device's copy. The server is not touched
Forget local cache when plugin is disabled	off	Privacy mode: destroy the local copy whenever you turn the plugin off

Changing encryption or the passphrase changes how everything is stored. If you switch encryption on or off, or change the passphrase, wipe the local cache and start from a fresh, empty database — otherwise old and new notes get mixed and neither side can read the other.

---

🔒 What the plugin does with your data

Locked before it leaves your device — your note text, your file and folder names, file sizes, creation and modification dates, and which pieces make up which file. All of it is encrypted with AES-256-GCM, using a key derived from your passphrase. The server stores it and can read none of it.

Still visible to whoever runs the server — that data exists and roughly how much of it there is, how many files and versions there are (approximately), which pieces repeat, and when versions were created. Nothing that reveals a title, a folder, or a word you wrote.

On this device — the local cache keeps some information in the clear (file paths, sizes, fingerprints) so the status panel can work offline. Turn on Forget local cache when plugin is disabled if you want that removed whenever the plugin is off.

Your credentials — your server password and your passphrase are stored in plain text in the plugin's own data.json file inside your vault, exactly as with every Obsidian plugin that holds a login. That file is never synced. Keep your disk encrypted, and change your credentials if the file was ever exposed.

Where things go — only to the server you configured yourself. Nothing is sent anywhere else, ever. With sync switched off, the plugin makes no network requests at all.

---

☕ Support

CouchDB Sync is free and open source, built and maintained in my spare time. If it keeps your notes together across your devices, you can support continued development with a coffee — it's genuinely appreciated.

---

🛠️ Development

npm install
npm run dev      # watch build -> main.js
npm run build    # type-check + production bundle
npm test         # unit tests

Copy manifest.json, main.js and styles.css into <vault>/.obsidian/plugins/couchdb-sync/.

---

License

MIT