Sync your Obsidian notes across devices without a central server. This plugin uses peer-to-peer technologies (WebRTC via PeerJS) to transfer your files directly between your devices, offering a free, private, and local-first alternative to cloud-based sync services.
Your notes are your own. This plugin ensures they stay that way.
- Core Features
- How It Works
- Manual Installation
- 🚀 Getting Started: Connecting Your First Devices
- ⚙️ Configuration & Advanced Features
- Conflict Center
- Security and Privacy
- Troubleshooting
- Contributing
- License
- 🌐 True Peer-to-Peer Sync: Files are sent directly from one device to another. No cloud storage, no middleman.
- 🕵️♂️ LAN Discovery: Automatically find other devices on your local network without needing to copy/paste IDs.
- 🤝 Multiple Connection Methods: Connect via auto-discovery with a PIN, a unique device ID, a QR code, or (experimentally) a direct IP address.
- ⚙️ Powerful Sync Engine:
- Handles file/folder creation, deletion, and renaming.
- Efficiently syncs only the changes.
- Intelligently chunks large files to handle attachments and media.
- ⚔️ Conflict Management:
- Choose your preferred conflict resolution strategy: create a duplicate file (safest), last-write-wins, or attempt to auto-merge changes in Markdown files.
- A dedicated "Conflict Center" in the ribbon helps you review and resolve conflicts.
- 🎛️ Granular Control:
- Selectively include or exclude folders from sync.
- Optionally sync all file types (images, PDFs, etc.).
- Optionally sync your
.obsidianconfig folder (use with caution!).
- 🏡 Fully Self-Hostable: For ultimate privacy, you can run your own PeerJS signaling server.
- 📱 Cross-Platform: Works on Desktop (Windows, macOS, Linux) and Mobile (via PeerJS). LAN Discovery is desktop-only.
This plugin uses PeerJS, which leverages WebRTC technology. Think of it like this:
- The Matchmaker (Signaling Server): When you want to connect two devices, they both check in with a public "signaling server." This server is like a switchboard operator; it introduces your devices to each other and helps them establish a direct communication channel.
- The Direct Line (P2P Connection): Once the introduction is made, the signaling server steps away. Your devices then communicate directly with each other.
- Data Transfer: All your files, changes, and deletions are sent over this secure, direct, end-to-end encrypted channel. Your notes are never stored on any third-party server.
For LAN connections, the plugin can also use multicast UDP packets to broadcast its presence, allowing for automatic discovery without relying on an internet-based signaling server.
This plugin must be installed manually.
- Go to the Releases page on GitHub.
- Download the
main.jsandmanifest.jsonfiles from the latest release. - Navigate to your Obsidian vault's plugins folder. This is typically located at
<YourVault>/.obsidian/plugins/.- If you don't see a
.obsidianfolder, you may need to enable "Show hidden files" in your file explorer.
- If you don't see a
- Create a new folder inside the
pluginsdirectory. Name itobsidian-decentralized. - Copy the
main.jsandmanifest.jsonfiles you downloaded into this new folder. - Restart Obsidian or reload the plugins by going to
Settings->Community Pluginsand toggling a different plugin off and on. - Go to
Settings->Community Plugins. You should now see "Obsidian Decentralized" in the list. - Click the toggle to enable the plugin.
First, give your device a memorable name in the plugin settings (e.g., "My Desktop," "My Phone"). This makes it easier to identify.
Then, open the connection helper by clicking the Connect Devices button in settings, or the users icon in the ribbon.
Use this when both devices are on the same Wi-Fi network. This method does not require an internet connection.
On Device A (e.g., your Desktop):
- Open the Connection Modal.
- Go to
PeerJS Connection->One-Time Connection. - Click
Invite with PIN. - The modal will display a 4-digit PIN.
On Device B (e.g., your Phone):
- Open the Connection Modal.
- Go to
PeerJS Connection->One-Time Connection. - Click
Join a Network. - You should see "Device A" appear in the "Discovered on LAN" list.
- Tap on it and enter the 4-digit PIN from Device A.
You're connected!
Use this if your devices are on different networks, or if LAN discovery fails.
On Device A:
- Open the Connection Modal ->
PeerJS Connection->One-Time Connection. - Click
Show ID. A unique ID and a QR code for your device will be displayed. - Click
Copy ID.
On Device B:
- Open the Connection Modal ->
PeerJS Connection->One-Time Connection. - Click
Join a Network. - Paste the ID from Device A into the "Peer ID" field and click
Connect with ID. (Alternatively, if you're on mobile, you could scan the QR code).
Set a primary device (like your desktop) as a "companion" for your other devices (like your phone) for automatic reconnection.
- On your main device (e.g., Desktop): Get its ID using Method B (
Show ID). - On your secondary device (e.g., Phone):
- Open the Connection Modal ->
PeerJS Connection->Companion Mode. - Paste the ID of your main device into the "Companion's ID" field.
- Click
Pair.
- Open the Connection Modal ->
Now, your phone will automatically try to reconnect to your desktop whenever the plugin is active.
💡 Pro Tip: After connecting for the first time, it's a good idea to run a Force Full Sync. Click the
refresh-cwribbon icon and select the peer you want to sync with. This ensures both vaults are perfectly aligned.
All options are available in the plugin's settings tab (Settings -> Obsidian Decentralized). You may need to enable "Experimental Features" to see all options.
- Included folders: Only sync folders that are in this list (one path per line). If this is empty, all folders are synced by default.
- Excluded folders: Never sync folders in this list. This takes priority over the included list.
When a file is changed on two devices before they have a chance to sync, a conflict occurs. Choose how you want to handle this:
- Create Conflict File (Default & Safest): The incoming change is saved as a new file, e.g.,
My Note (conflict on 2023-10-27).md. You can then manually compare and merge them. - Last Write Wins: The version with the newest modification timestamp is kept, and the other is discarded.
- Attempt Auto-Merge: For Markdown files, the plugin will try to merge the changes automatically. If it can't merge cleanly, it will fall back to creating a conflict file.
- Sync all file types: By default, the plugin focuses on text files. Enable this to sync images, PDFs, audio, and other attachments.
- Sync '.obsidian' configuration folder: (DANGEROUS) Syncs your Obsidian settings, themes, and snippets. This can cause problems if your devices have different plugins, themes, or operating systems. Always make a backup before enabling this.
For completely offline, LAN-only environments where even a signaling server is not desired.
- One device (usually a desktop) acts as the Host.
- Other devices connect as Clients.
- Use the
Connectmodal ->Direct IPto configure. The Host will display its IP address and a PIN for clients to use.
For maximum privacy, you can run your own PeerServer. In the plugin's "Advanced Settings," enable "Use custom signaling server" and enter your server's details.
If a conflict occurs and a (conflict) file is created, a new icon (swords) will appear in the left ribbon. This is the Conflict Center.
- The icon shows a badge with the number of unresolved conflicts.
- Clicking it opens a modal listing all conflicts.
- Click
Resolveon any conflict to open a diff view, allowing you to compare your local version with the remote version and choose which one to keep.
- End-to-End Encryption: All data transferred between your devices is encrypted in-transit using DTLS (part of the WebRTC standard).
- No Cloud Storage: Your notes are never stored on any third-party server. They are only ever on your devices.
- Signaling Server: The only third-party interaction is with the signaling server, which is used solely to establish the initial P2P connection. It does not see or handle any of your note data. If you use the self-hosted option, you control this component as well.
- Plugin doesn't appear in Obsidian: After manual installation, if the plugin doesn't show up under Community Plugins, double-check that the folder structure is correct:
<YourVault>/.obsidian/plugins/obsidian-decentralized/and ensure this folder directly containsmain.jsandmanifest.json. - Connection Fails:
- Ensure both devices are connected to the internet (for the default PeerJS mode).
- Check for firewalls or aggressive ad-blockers (like Pi-hole) that might be blocking the connection to the PeerJS signaling server or the P2P connection itself.
- Double-check that you have copied/pasted the Peer ID correctly.
- Status is "❌ Sync Offline": The plugin couldn't connect to the signaling server. It will automatically keep retrying with an increasing backoff delay. Check your internet connection.
- LAN Discovery Doesn't Work: This feature requires UDP multicast, which is sometimes blocked by corporate networks, VPNs, or strict firewall rules. In this case, fall back to connecting via ID/QR Code.
Contributions, bug reports, and feature requests are welcome! Please feel free to open an issue or submit a pull request.
This plugin is licensed under the GNU General Public License v3.0. For the full license text, please see the LICENSE file included in the repository.
Special thanks to Ray Vermey for their guidance, encouragement and feedback.