Local Sync

🔄 Local Sync

Zero-cloud · Zero-conflict · Zero‑config — LAN bidirectional sync for Obsidian vaults

---

---

✨ Features

🔗 LAN Direct Sync Peer‑to‑peer WebSocket/WSS connection. Zero cloud dependency — your data stays on your network.

🤝 Zero‑Conflict CRDT Yjs CRDT automatically merges concurrent text edits. No manual conflict resolution. Ever.

🔒 TLS Encrypted WSS transport with auto‑generated ECDSA P‑256 certificates. Certificate PIN verification prevents MITM attacks.

📡 Auto Discovery UDP broadcast finds devices on the same LAN. No IP typing needed.

🔐 Security First PSK challenge‑response authentication. Path traversal protection against rogue file writes.

🎯 Selective Sync Exclude folders & file types. Ignore .trash, .tmp, node_modules — your choice.

🖥️ Cross‑Platform macOS (NSFileCoordinator aware) Linux (writeFile + chmod)
Windows (write + lock‑retry)

🔌 Zero Config Install, set IP (or auto‑discover), and go. Certificates auto‑generate on first launch.

---

🚀 Quick Start

Installation

📁 Plugin ID: local-sync · Folder: your-vault/.obsidian/plugins/local-sync/

1. Download the latest release from the Releases page
2. Copy main.js + manifest.json + styles.css to your-vault/.obsidian/plugins/local-sync/
3. Open Obsidian → ⚙️ Settings → Community plugins → Enable Local Sync

Usage

💡 Pro tip: On the same subnet? Enable UDP discovery for zero‑config auto‑connect.
🔒 TLS is on by default with auto‑generated ECDSA P‑256 certificates.

---

🏗️ Architecture

┌──────────────────────────────────────────────────┐
│              UI Layer                            │
│  SettingTab / ConflictModal / StatusBar          │
│  └─ TLS settings, fingerprint display, reset     │
├──────────────────────────────────────────────────┤
│           Service Layer                          │
│  SyncEngine + CrdtEngine(Yjs) + ConflictDetector │
├──────────────────────────────────────────────────┤
│         Discovery Layer                          │
│  UDP broadcast + QR pairing (desktop↔mobile)     │
├──────────────────────────────────────────────────┤
│          Security Layer                          │
│  TLS encryption + PSK auth + path validation     │
│  └─ CertManager (ECDSA P‑256, auto‑generate)     │
├──────────────────────────────────────────────────┤
│       Network & IO Layer                         │
│  WebSocket(WSS/WS) + chokidar + OsWriter         │
│  └─ http/https dual‑protocol server              │
└──────────────────────────────────────────────────┘

Module Overview

---

🔄 How It Works

Sync Flow

┌─────────────────────────────────────────────────────────────────────┐
│                        Initial Sync                                │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  Device A ── FILE_LIST_BATCH (manifest, 100 files/batch) ──→ Device B │
│                ←── FILE_LIST_ACK (missing + different) ──────────┤  │
│                ── FILE_RESPONSE (missing files, 10 concurrent) ──→   │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────────┐
│                     Incremental Sync                               │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  File change detected                                                │
│      ├── TEXT (.md/.txt/.canvas) → CRDT incremental update          │
│      └── BINARY (.png/.pdf/.zip) → Full file transfer               │
│                                                                     │
│  Both paths: protected by recentlyPushed(2s) + originDeviceId       │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

TLS Handshake

Client (WSS)                  Server (WSS)
     │                            │
     │──── wss://connect ──────→│  TLS 1.2/1.3 handshake
     │←── TLS established ─────│  Transport encrypted
     │                            │
     │── cert-fingerprint ────→│  Exchange SHA‑256 fingerprints
     │←── cert-fingerprint-ack─│  PIN verification
     │                            │
     │── PSK challenge ───────→│  Inside encrypted channel
     │←── authenticated ──────│
     │                            │
     │── sync data (encrypted) →│  All traffic protected

Conflict Resolution

Synchronization Safeguards

---

🔒 TLS Encryption (v1.1.0)

No CA needed. No OpenSSL setup. No external dependencies. Just works — with or without TLS.

---

📊 Project Stats

---

🛠️ Development

# Clone & build
git clone https://github.com/liuboacean/obsidian-local-sync-plugin.git
cd obsidian-local-sync-plugin
npm install
npm run build     # Production build (main.js)
npm run dev       # Watch mode (for Hot Reload plugin)
npm test          # Run all 148 tests

# Quick local test with two vaults:
cp main.js manifest.json styles.css /path/to/vault-a/.obsidian/plugins/local-sync/
cp main.js manifest.json styles.css /path/to/vault-b/.obsidian/plugins/local-sync/
# Open both vaults in Obsidian, enable plugin, connect

---

📋 Changelog

---

🗺️ Roadmap

• Yjs CRDT auto‑merge
• PSK auth + path security
• UDP auto‑discovery
• Cross‑platform file writer
• TLS encryption (WSS) ← v1.1.0
• Mobile client support (P2)
• Sync history viewer (P2)
• Diff preview before sync (P2)

---

🤝 Contributing

PRs are welcome! Check the issues for areas to contribute.

📄 License

MIT © 2026 Obsidian Local Sync Team

---

Made with ❤️ for the Obsidian community