MDFriday Sync

Free, open-source, end-to-end encrypted vault sync for Obsidian — Desktop & Mobile

Keep your Obsidian vault in perfect sync across all your devices — no subscription, no black box, no vendor lock-in.
You own your data. You control the server.

Why MDFriday Sync?

There are several ways to sync an Obsidian vault. Here's how they compare:

MDFriday Sync builds on the battle-tested Self-hosted LiveSync core and adds what it lacks: a fully managed, open-source backend. With Self-hosted LiveSync you still have to provision and configure your own CouchDB server, manage user accounts, and handle updates yourself. With MDFriday Sync you enter a single license key and everything — database provisioning, authentication, connection credentials — is handled for you automatically. And if you prefer full control, the backend (hugoverse) is open source and self-hostable too.

How It Works

MDFriday Sync uses CouchDB as the sync backend — a battle-tested, open-source database purpose-built for multi-device replication. Changes made on any device are pushed to a CouchDB server and instantly pulled to all other connected devices.

You have two options for the backend:

Option A — MDFriday Managed (recommended)

Activate a license at mdfriday.com. The backend is provisioned automatically — no CouchDB installation, no server configuration, no credential juggling. Just paste your license key and start syncing. Your data is encrypted on your device before it ever leaves.

Option B — Self-host Everything (100% free)

Run the backend yourself using hugoverse — MDFriday's fully open-source backend. It bundles CouchDB setup and everything needed to run your own sync server.

# Spin up your own backend
git clone https://github.com/mdfriday/hugoverse
# follow the hugoverse README for setup

Or point the plugin directly at any existing CouchDB v3+ instance you manage.

Features

• 🔄 Live sync — changes appear on other devices in seconds via CouchDB long-polling
• 🔒 End-to-end encryption — AES-256 / HKDF; the server never sees plain text
• 🕵️ Path obfuscation — optionally hashes file paths so even filenames are hidden from the server
• 📁 Selective sync — choose which file types to sync: images, audio, video, PDF, themes, snippets, plugins
• 🚫 Custom ignore patterns — gitignore-style rules to exclude folders or file types
• ⚙️ Hidden file sync — keeps .obsidian/ configuration in sync across devices, with smart per-device exclusions (workspace layout, cache, etc.)
• 📶 Offline support — queues changes locally while offline and replays them on reconnect
• 🔁 Auto-reconnect — detects network interruptions and reconnects automatically
• 📊 Status indicator — real-time sync status shown in the editor corner
• 🌐 Desktop + Mobile — works on all platforms without any platform-specific code
• 🌏 Bilingual UI — English and Simplified Chinese (中文) built-in

Quick Start

1. Install the plugin

Search for MDFriday Sync in Obsidian's Community Plugins browser, or install manually by placing the files in your vault's .obsidian/plugins/mdfriday-sync/ folder.

2. Prepare a CouchDB server

• MDFriday hosted — create an account at mdfriday.com; your CouchDB URL and credentials are provided automatically.
• Self-hosted — follow the hugoverse setup guide, or install CouchDB directly and create a database.

CouchDB must be reachable from all your devices (desktop and mobile). For home servers, a VPN or reverse proxy with HTTPS is recommended.

3. Configure the plugin

Open Settings → MDFriday Sync and fill in:

Click Test Connection to verify.

4. Start syncing

• Toggle Enable Sync — the plugin starts live-syncing immediately.
• First device: click Upload local data to cloud to seed the remote database.
• Additional devices: enter the same credentials + passphrase → click Download data from cloud.

⚠️ If you see "The remote database has been rebuilt", click Fetch from Server to re-sync a new device.

Selective Sync

Control exactly what gets synced:

You can also define custom ignore patterns in gitignore format (e.g. attachments/, *.tmp, private/**) to exclude entire folders or file extensions.

Hidden File (.obsidian) Sync

MDFriday Sync can keep your Obsidian configuration — themes, snippets, plugin settings — in sync across devices.

The following are excluded by default because they are device-specific or auto-regenerated:

Building from Source

git clone https://github.com/mdfriday/obsidian-sync
cd obsidian-sync
npm install
npm run build      # → main.js + styles.css
npm run dev        # watch mode for development
npm test           # run unit tests

Requirements: Node.js ≥ 18

Security Model

1. Encryption happens on your device — the passphrase never leaves your machine.
2. The server stores only ciphertext — even if the server is compromised, your notes cannot be read.
3. Path obfuscation (optional) — file paths are SHA-256 hashed before being stored, so the server cannot infer your folder structure.
4. Open source end-to-end — plugin code and backend code are both publicly auditable.

Troubleshooting

License

Apache-2.0 — see LICENSE.
Use it, fork it, self-host it — no restrictions.

Network Requests & Data Privacy

This section discloses all external network requests made by the plugin, as required by the Obsidian plugin review process.

External domains contacted

If you self-host (Option B with your own CouchDB or hugoverse), no requests are made to mdfriday.com. The plugin only contacts the CouchDB server you configure.

Requests to app.mdfriday.com (managed backend only)

The following 6 API calls are made to app.mdfriday.com only when using the MDFriday managed backend:

No vault content is ever sent to mdfriday.com. The plugin only retrieves CouchDB connection credentials from the license server and performs all vault sync directly with CouchDB.

Runtime Base64 encoding (btoa)

The plugin uses btoa() in two places to encode CouchDB credentials as a standard HTTP Basic Authentication header (Authorization: Basic <base64(user:pass)>). This is the standard mechanism defined in RFC 7617. The encoded credentials are sent only to the user-configured CouchDB server. btoa is not used to hide API keys, URLs, or code payloads.

Why the plugin uses native fetch instead of Obsidian's requestUrl

Obsidian recommends requestUrl for network requests. This plugin follows that recommendation everywhere except the internal PouchDB CouchDB replication adapter, where native fetch is the only viable option for the following technical reasons:

PouchDB's CouchDB HTTP adapter requires AbortSignal to cancel in-flight _changes long-poll requests when the user stops sync. Without AbortSignal, requests cannot be cleanly cancelled — they would continue running in the background, leaking resources. The full-buffering behaviour of requestUrl also causes timeout failures for large bulk replication responses (_bulk_get, _bulk_docs) on cold start, because the response body is not available to PouchDB until the entire download completes.

All other network calls in the plugin (license API, CouchDB connection test, file publish) use requestUrl as recommended.

Acknowledgements

— LiveSync – multi-device synchronization