Plugin Overview

Live Cursor is an advanced, offline-first, zero-cloud collaborative sync engine designed specifically for private Obsidian vaults. By leveraging Yjs conflict-free replicated data types (CRDTs) and local background daemons, it lets you edit vaults simultaneously with team members without exporting your data to third-party databases.

Key Capabilities

Technology Stack

Manual Installation

While Live Cursor is available via the Obsidian Community Plugins marketplace, you can also install it manually by following these lightweight packaging steps.

1. Grab Compiled Releases

Download the latest compiled release bundle from GitHub. The plugin directory requires three fundamental assets:

• main.js — The compiled execution logic.
• manifest.json — Metadata containing configuration permissions.
• styles.css — Custom rendering styling for peer cursors and flags.

2. Place Assets in Vault

Move these assets to your target vault's hidden plugin directory:

# Create the target directory inside your Obsidian vault plugins folder
mkdir -p .obsidian/plugins/live-cursor

# Copy your downloaded release files into the directory
cp main.js manifest.json styles.css .obsidian/plugins/live-cursor/

3. Reload Plugins

Navigate to Obsidian Settings > Community Plugins, click Check for updates, and toggle Live Cursor to enabled.

Plugin Settings Reference

Vault Quickstart

To synchronize vaults, a background sync database must be running. We provide an embedded sync server inside the plugin settings or a detached Docker container for remote execution.

Bootstrap local server in 15 seconds

1. Open Obsidian Settings > Live Cursor.
2. Click the Launch Setup Wizard button inside the control panel.
3. Under Step 1: background server, click the switch to boot the secure local daemon process.
4. Under Step 2: Profile setup, type your display name and pick your cursor color banner.
5. You are now ready to collaborate! Share your local network address (e.g., ws://192.168.1.100:1234/sync) with teammates.

Connecting Remote Teammates

Once your daemon is running, teammates connect by entering your server's WebSocket URL into their plugin settings. There are three network topology options:

Daemon Infrastructure

The Live Cursor daemon process is structured in TypeScript, utilizing a low-overhead SQLite storage mechanism and a WebSocket listener to relay operations.

Docker Container Deployment

If you prefer a headless server running on a NAS, server, or cloud node, deploy the precompiled Alpine Docker container.

# Deploy the Docker container on port 1234
docker run -d \
  --name live-cursor-daemon \
  -p 1234:1234 \
  -v /volume1/obsidian/data:/app/data \
  -v /volume1/obsidian/backups:/app/backups \
  -e PORT=1234 \
  -e DB_PATH=/app/data/live-cursor.db \
  live-cursor/daemon:latest

Docker Compose (Recommended)

For persistent, auto-restarting deployments, use the official Compose manifest:

version: '3.8'
services:
  live-cursor:
    image: ghcr.io/live-cursor/sync-server:latest
    container_name: live-cursor-server
    restart: unless-stopped
    ports:
      - "1234:1234"
    volumes:
      - ./data:/app/data
      - ./backups:/app/backups
    environment:
      - PORT=1234
      - ADMIN_USER=admin
      - ADMIN_PASS=yourpassword

Environment Parameters

The daemon respects standard environmental variables for easy tailoring:

Network Protocol

Communication between Obsidian clients and the local sync daemon occurs over binary WebSockets utilizing custom packaging structures derived from the Yjs protocols.

Operational Packets

Packets are framed with a single-byte prefix indicating message type. The payload consists of standard Uint8Array binary frames.

{
  "message_types": {
    "0": "SyncStep1 (Client sends their local state vector)",
    "1": "SyncStep2 (Daemon replies with missing updates)",
    "2": "SyncUpdate (Real-time delta keystrokes and selections)",
    "3": "AuthRequest (Daemon challenges client validation signature)"
  }
}

Connection Lifecycle

Lazy Flush Interval

To maintain standard vault format compatibility, the daemon doesn't just store edits in SQLite. Every 15 seconds of idle inactivity, it flushes the parsed, compiled Markdown buffer directly back to a human-readable .md file in your backups directory.

CRDT Merge Logic

Conflict-free Replicated Data Types (CRDTs) form the mathematical foundation of Live Cursor's concurrent editing capability.

Why git diffs fail real-time edit resolution

Git utilizes line-based three-way merges. If two authors edit different portions of the exact same line at the same time, Git is unable to resolve order, prompting a merge conflict.

Yjs manages text as a doubly linked list of character chunks. Each chunk contains:

• ID: A unique key containing the author's client code and an incremental sequence number.
• Origin Left / Origin Right: Pointers targeting the adjacent characters at the time the keystroke was pressed.

This guarantees that even if 10 people type concurrently inside the same paragraph, all keystrokes are merged in exactly the same deterministic order across every single peer.

Awareness Protocol

Alongside document sync, Live Cursor propagates real-time awareness state — lightweight JSON objects broadcasting each peer's cursor position, selection range, and collaborator name. Awareness updates are never persisted to SQLite; they are ephemeral and discarded when a client disconnects.

// Live Cursor sets collaborator awareness on each file sync
provider.awareness.setLocalStateField('user', {
  name: settings.nickname || settings.username || 'Collaborator',
  color: settings.cursorColor || '#6366f1',
  colorLight: (settings.cursorColor || '#6366f1') + '33'
});

Tailscale Setup

Tailscale is the recommended networking solution for sharing your Live Cursor daemon with remote teammates. It creates an encrypted peer-to-peer mesh network (using WireGuard® under the hood) where every device gets a stable private IP address — no port forwarding, no firewall rules, no dynamic DNS needed.

Step 1 — Install Tailscale on the Host Machine

The host machine is the device running the Live Cursor daemon (local background process or Docker container). Install Tailscale on this machine first.

# Install Tailscale on Debian/Ubuntu
curl -fsSL https://tailscale.com/install.sh | sh

# Authenticate and connect to your tailnet
sudo tailscale up

# Confirm your Tailscale IP (100.x.x.x range)
tailscale ip -4

# Install via Homebrew
brew install tailscale

# Start and authenticate
sudo tailscaled &
tailscale up

# Or download the App from the Mac App Store (recommended)
# https://apps.apple.com/app/tailscale/id1475387142

# Download installer from https://tailscale.com/download/windows
# Or install via winget:
winget install tailscale.tailscale

# After installation, sign in from the system tray icon
# Confirm your Tailscale IP
tailscale ip -4

# docker-compose.yml — Live Cursor + Tailscale sidecar
version: '3.8'
services:
  tailscale:
    image: tailscale/tailscale:latest
    hostname: live-cursor-node
    environment:
      - TS_AUTHKEY=${TS_AUTHKEY}
      - TS_STATE_DIR=/var/lib/tailscale
    volumes:
      - tailscale-state:/var/lib/tailscale
      - /dev/net/tun:/dev/net/tun
    cap_add:
      - NET_ADMIN
    restart: unless-stopped

  live-cursor:
    image: ghcr.io/live-cursor/sync-server:latest
    network_mode: "service:tailscale"
    volumes:
      - ./data:/app/data
      - ./backups:/app/backups
    environment:
      - PORT=1234
      - ADMIN_USER=admin
      - ADMIN_PASS=yourpassword
    restart: unless-stopped
    depends_on:
      - tailscale

volumes:
  tailscale-state:

Step 2 — Install Tailscale on Teammate Devices

Each collaborator installs Tailscale on their device and joins your tailnet (Tailscale network). You can invite them via email from the Tailscale admin console.

• Download from tailscale.com/download for all platforms including iOS and Android.
• Once connected, every device sees others via stable 100.x.x.x IPs — these never change.
• For Obsidian mobile users, Tailscale runs in the background and maintains the VPN tunnel automatically.

Step 3 — Configure Live Cursor to Use Tailscale IP

Once Tailscale is running on all devices, update the Live Cursor server URL to point to the host machine's Tailscale IP instead of its local LAN address:

# In Obsidian → Settings → Live Cursor → Server URL
# Replace with the host machine's Tailscale IP:

ws://100.x.x.x:1234/sync

# Example with a specific IP:
ws://100.64.0.12:1234/sync

# To find the host's Tailscale IP, run on the host machine:
tailscale ip -4

Step 4 — Using MagicDNS (Optional but Recommended)

Tailscale's MagicDNS feature assigns human-readable hostnames to every device on your tailnet, so you never need to remember IP addresses.

# Enable MagicDNS in the Tailscale Admin Console:
# https://login.tailscale.com/admin/dns

# Then use the hostname instead of IP in Live Cursor:
ws://my-desktop.tail12345.ts.net:1234/sync

# Or if you set a custom domain:
ws://live-cursor-node:1234/sync

Network Topology with Tailscale

Tailscale ACL — Restricting Access

For organizations, you can restrict which Tailscale devices can reach your Live Cursor daemon using Access Control Lists (ACLs) in the admin panel.

{
  "acls": [
    {
      "action": "accept",
      "src": ["tag:obsidian-collab"],
      "dst": ["tag:live-cursor-server:1234"]
    }
  ],
  "tagOwners": {
    "tag:obsidian-collab": ["autogroup:member"],
    "tag:live-cursor-server": ["autogroup:admin"]
  }
}

Troubleshooting Tailscale Connectivity

Frequently Asked Questions