LAN Vault Sync — Obsidian Plugin

Real-time, conflict-free vault synchronization across your local network — no cloud, no server, no subscription.

Edit on your Mac and see changes appear instantly on your iPhone. All traffic stays on your LAN.

Why LAN Vault Sync?

Most sync solutions route your notes through a third-party server. LAN Vault Sync is different:

Zero cloud — data never leaves your local network
Zero configuration — devices discover each other automatically via UDP broadcast
Zero conflicts (for text) — Yjs CRDT merges concurrent edits at the character level, the same technology that powers Google Docs-style collaboration
Zero subscription — fully open source and free forever

Features

Feature	Details
Real-time sync	File changes pushed to all peers within seconds via WebSocket
CRDT text merge	Markdown / text files merged automatically at character level using Yjs — no conflicts, no data loss
Binary file sync	Images, PDFs, and other attachments synced via SHA-256 hash comparison
Auto-discovery	Devices find each other via UDP broadcast — zero configuration needed
Manual peers	Add peers by `IP:port` for networks where broadcast is blocked
QR code pairing	Generate a QR code on desktop; scan with your phone to add the peer instantly — no typing required
Offline-friendly	Edit while offline; changes are merged automatically on reconnect
P2P architecture	Every device is equal — no central server or hub required
Conflict backups	Binary-file conflicts are backed up before overwrite so nothing is lost

How It Works

Device A (Mac)                        Device B (iPhone / iPad)
┌──────────────────┐  WebSocket P2P  ┌──────────────────┐
│  Obsidian        │◄───────────────►│  Obsidian        │
│  + LAN Vault Sync│   Yjs CRDT      │  + LAN Vault Sync│
└──────────────────┘   updates       └──────────────────┘
         ▲                                    ▲
         │         UDP broadcast              │
         └────────────────────────────────────┘
               (auto-discovery, LAN only)

On startup, each device announces itself via UDP broadcast and listens for announcements from peers.
Devices establish WebSocket connections to each other (every node is both server and client).
File tree metadata is exchanged; missing or changed files are requested.
Text files (.md, .txt, etc.) sync via Yjs CRDT — edits from multiple devices are merged automatically, even if made simultaneously while offline.
Binary files (images, PDFs, etc.) sync via SHA-256 hash comparison; the most-recently-modified version wins.

Installation

From Obsidian Community Plugins (coming soon)

Open Settings → Community Plugins → Browse
Search for LAN Vault Sync
Click Install, then Enable

Manual Installation

Go to the Releases page and download the latest main.js, manifest.json, and styles.css.
In your vault, create the folder .obsidian/plugins/lan-vault-sync/.
Copy the three downloaded files into that folder.
In Obsidian, go to Settings → Community Plugins, toggle off Restricted Mode, and enable LAN Vault Sync.

Usage

Quick Start

Install the plugin on two or more devices connected to the same Wi-Fi or LAN.
Open Obsidian on each device.
The plugin automatically discovers peers and begins syncing within seconds.

QR Code Pairing (Recommended for Mobile)

The easiest way to connect a phone or tablet — no typing required:

On the desktop (Mac / Windows / Linux): open Settings → LAN Vault Sync and find the QR Code Pairing section. A QR code is displayed automatically.
On your phone / tablet: scan the QR code with the system camera (or any QR scanner).
The camera will prompt you to open Obsidian. Confirm — the plugin automatically adds the desktop's IP:port as a peer and shows a notification.

Tip: If your desktop has multiple network interfaces (e.g. Wi-Fi + Ethernet), use the dropdown above the QR code to select the correct IP before scanning.

Manual Peer Connection

Auto-discovery uses UDP broadcast, which is blocked on some managed Wi-Fi networks (guest networks, corporate networks). In that case:

On Device A: open plugin settings and note the displayed IP address and port (default: 53712).
On Device B: go to Settings → LAN Vault Sync → Manual Peers → enter 192.168.x.x:53712.
Alternatively, use the command palette: LAN Vault Sync: Add Manual Peer.

Status Bar

The plugin shows a status indicator in the Obsidian status bar:

Icon	Meaning
🔴	Sync disabled or no peers found
🟡	Discovering peers
🟢	Connected and syncing

Commands

Open the command palette (Cmd/Ctrl + P) and search for:

LAN Vault Sync: Toggle — start or stop the sync service
LAN Vault Sync: Open Sync Panel — open the sidebar panel with connected peers and sync log
LAN Vault Sync: Add Manual Peer — add a peer by IP:port

Settings

Setting	Default	Description
Enable Sync	On	Master on/off switch
Device Name	Auto-generated	Friendly name shown to other peers
Port	`53712`	WebSocket listening port
Ignored Paths	`.obsidian/`, `.trash/`	Glob patterns excluded from sync
Sync Check Interval	`30s`	Period between full file-tree verification passes
Debug Logging	Off	Write verbose logs to the developer console

Technical Details

Architecture

Topology: Peer-to-peer mesh — each node runs a WebSocket server and connects to every known peer as a client
Text sync: Yjs CRDT with fast-diff for efficient delta computation
Binary sync: SHA-256 hash comparison; full file transferred when hashes differ
Discovery: UDP broadcast on port 53713 (same subnet only)
CRDT persistence: Yjs document states saved to .obsidian/plugins/lan-vault-sync/crdt-state/
Conflict backups: Overwritten binary files backed up to .obsidian/plugins/lan-vault-sync/conflicts/

Conflict Resolution

File type	Strategy
Text (`.md`, `.txt`, `.canvas`, …)	Yjs CRDT — automatic, lossless merge at character level
Binary (images, PDFs, audio, …)	Last-write-wins by modification timestamp; previous version backed up

Mobile Compatibility

Mobile devices (iOS / Android) act as WebSocket clients only — they cannot run a server due to OS restrictions.
A desktop device must be reachable on the network to act as a server for mobile clients.
Auto-discovery may not work on mobile; use QR Code Pairing or Manual Peers as a fallback.
Sync resumes automatically when the Obsidian app returns to the foreground.

Privacy & Security

All traffic is LAN-only. No data is sent to any external server.
Communication is plain WebSocket (ws://) within your local network. Do not enable this plugin on public or untrusted networks.
No analytics, telemetry, or account required.

Requirements

Obsidian v1.4.0 or later
All devices on the same local network (same Wi-Fi or Ethernet segment)
For mobile sync: at least one desktop device must be running and reachable on the LAN

Development

# Clone and install
git clone https://github.com/your-username/obsidian-lan-vault-sync
cd obsidian-lan-vault-sync
npm install

# Development build — watch mode (auto-recompile on save)
npm run dev

# Production build
npm run build

# Run tests
npm test

Enable the Hot Reload community plugin in Obsidian to automatically reload the plugin after each build.

See doc/debug-and-testing.md for a full multi-device test guide.

Roadmap

QR code pairing — scan to add a peer instantly (mobile-friendly)
End-to-end encryption (TLS / WireGuard)
Sync progress indicator per file
Selective sync (include/exclude folders per peer)
Conflict resolution UI for binary files
mDNS / Bonjour discovery as alternative to UDP broadcast

Contributing

Pull requests and issues are welcome. Please open an issue before submitting a large PR.

License

MIT

Acknowledgements

Yjs — CRDT framework by Kevin Jahns
ws — WebSocket library for Node.js
fast-diff — fast string diff
Obsidian — the best local-first knowledge base

LAN Vault Sync

Description

Reviews

Stats

Latest Version

Changelog

README file from