Live Share

Real-time collaborative editing for Obsidian. Share your vault with others and edit together with live cursors, file sync, presence tracking, and end-to-end encryption.

Quick Start

1. Start the Server

cd server && npm install && npm run build && npm start

Runs on http://localhost:3000. Verify: curl http://localhost:3000/healthz

2. Install the Plugin

Build from source:

cd plugin && npm install && npm run build

Copy into your vault:

mkdir -p /path/to/vault/.obsidian/plugins/obsidian-live-share
cp plugin/main.js plugin/styles.css manifest.json \
   /path/to/vault/.obsidian/plugins/obsidian-live-share/

Or install via BRAT for automatic updates.

Enable Live Share in Settings > Community Plugins.

3. Configure

Open Settings > Live Share and set your Server URL, Display name, and Shared folder (leave empty for the whole vault).

4. Collaborate

Host: Run Live Share: Start session from the command palette. An invite link is copied to your clipboard.

Guest: Run Live Share: Join session and paste the invite link. Files sync automatically.

Features

• Real-time editing - Yjs CRDT-powered character-level sync with live cursors and selections
• File sync - Creates, deletes, renames, and binary files sync automatically
• End-to-end encryption - AES-256-GCM with PBKDF2 key derivation; passphrase never leaves the invite link
• Presence panel - See who's connected, what file they're viewing, follow/summon/kick users
• Permissions - Host can set guests to read-write or read-only (enforced server-side), with per-file overrides
• Guest approval - Optionally require host approval before guests can join
• Kick protection - Kicked users must be re-approved by the host to rejoin, even when approval is not required
• Host transfer - Hand off the host role to another participant
• Presentation mode - Auto-broadcast your navigation to all participants
• Canvas collaboration - Real-time sync of .canvas files
• Cross-platform support - Windows filename character mapping for seamless sync between platforms
• Offline queue - File operations are buffered when disconnected and replayed on reconnect
• Auto-reconnect - Optionally rejoin the previous session on startup

Commands

Settings

Server Configuration

File Exclusion

Exclude files from sync by adding glob patterns in Settings > Live Share > Excluded patterns.

Default excludes: .obsidian/**, .trash/**.

Example patterns: drafts/**, *.tmp, private/**.

How It Works

The system uses a stateless relay server and two WebSocket channels:

• Yjs sync (/ws-mux/:roomId) - Multiplexed binary channel for Yjs CRDT updates and cursor awareness per file
• Control (/control/:roomId) - JSON messages for file operations, presence, permissions, and session lifecycle

The host's vault is the source of truth. Text files sync character-by-character via Yjs. Binary files transfer as base64 with automatic chunking (up to 50 MB).

Security

• E2E encryption (AES-256-GCM, PBKDF2 100k iterations) for file content in control messages
• Timing-safe token comparison on all auth checks
• Server-side enforcement of read-only permissions and host-only operations
• Path traversal protection, rate limiting, payload size limits
• Use TLS (wss://) to encrypt all traffic including Yjs sync data

See docs/security.md for the full threat model.

Development

# Server: 108 tests
cd server && npm run dev && npm test && npm run lint

# Plugin: 310 tests
cd plugin && npm run dev && npm test && npm run lint

Disclosures

Network use. This plugin requires a relay server. All sync, file transfer, and presence data is sent over WebSocket connections to a server URL you configure. You can self-host the included server. File content can be end-to-end encrypted so the server cannot read it.

Optional account. GitHub OAuth login is available but not required. Without it, a local anonymous ID is generated.

License

This project is licensed under the MIT License. See LICENSE for details.