Obsidian 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

Command	Description	Access
Start session	Create a room and start hosting	Anyone
Join session	Join via invite link	Anyone
End session	End the session for all participants	Host
Leave session	Leave the session	Guest
Copy invite link	Copy invite to clipboard	Anyone in session
Show collaborators panel	Open the presence sidebar	Anyone
Focus participants here	Send a "look here" notification	Anyone in session
Summon all participants here	Navigate all users to your cursor	Host
Summon a specific participant	Navigate one user to your cursor	Host
Reload all files from host	Re-download shared files	Guest
Toggle presentation mode	Auto-broadcast navigation	Host
Transfer host role	Offer host role to another user	Host
Set file permissions	Per-file read-only/read-write	Host
Show audit log	View session event log	Host
Log in with GitHub	GitHub OAuth authentication	Anyone
Log out	Clear stored authentication	Anyone

Settings

Setting	Default	Description
Server URL	http://localhost:3000	Your Live Share server address
Server password	—	Optional server password
Display name	Anonymous	Your name shown to collaborators
Cursor color	#7c3aed	Your cursor color in the editor
Shared folder	—	Subfolder to share (empty = whole vault)
Require approval	false	Require host approval for guests
Approval timeout	60	Auto-deny join requests after N seconds (0 = disabled)
Notifications	true	Toggle non-critical status notices
Auto-reconnect	true	Rejoin previous session on startup
Debug logging	false	Write debug logs to a vault file
Excluded patterns	—	Glob patterns for files to exclude from sync

Server Configuration

Variable	Default	Description
PORT	3000	Server port
SERVER_PASSWORD	—	Restrict access to authorized clients
TLS_CERT / TLS_KEY	—	Enable HTTPS/WSS
REQUIRE_GITHUB_AUTH	false	Require GitHub OAuth
GITHUB_CLIENT_ID	—	GitHub OAuth client ID
GITHUB_CLIENT_SECRET	—	GitHub OAuth client secret
JWT_SECRET	—	JWT signing secret (required with auth)
CORS_ORIGIN	*	Allowed CORS origins

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.