OmniRoute Sync

Sync your Obsidian vault between desktop and mobile over Tailscale. No cloud services. No third-party sync. Just your devices, your network, your data.

Features

• Tailscale-based sync — Direct device-to-device connection. No cloud intermediary.
• Smart filtering — Automatically skips notes tagged private, personal, or draft. Only syncs your work/technical notes by default.
• Backlink-aware prioritization — Notes with more [[wikilinks]] and inbound backlinks sync first. Your most connected notes are always up to date.
• End-to-end verification — Every push is confirmed. You see ✓ when files land, ⚠ when verification fails.
• Conflict resolution — When both devices edit the same note, both versions are preserved. Resolve from the settings panel.
• Debug mode — Per-category logging (sync, push, pull, conflicts, filter, network) with an in-plugin log viewer. Export logs for bug reports.

Requirements

• Obsidian 1.4.0+ on both desktop and mobile
• Tailscale installed and logged in on both devices
• Both devices on the same Tailscale network

Install on Desktop

1. Download the latest release or build from source:

   git clone https://github.com/branben/obsidian-omniroute-sync.git
   cd obsidian-omniroute-sync
   npm install
   npm run build

2. Copy the built plugin into your vault's .obsidian/plugins/ folder:

   mkdir -p <YOUR_VAULT>/.obsidian/plugins/omniroute-sync
   cp dist/main.js manifest.json styles.css <YOUR_VAULT>/.obsidian/plugins/omniroute-sync/

3. Open Obsidian → Settings → Community plugins → Enable OmniRoute Sync.
4. The server starts automatically. Check the status bar: OmniRoute: server :27781.

Install on Mobile

You need the same three files on your mobile device (main.js, manifest.json, styles.css). Transfer them using any of these methods:

Working Copy (Git)

# From your vault directory — commit the plugin files first
cd <YOUR_VAULT>/.obsidian/plugins/omniroute-sync
git add main.js manifest.json styles.css
git commit -m "Add OmniRoute Sync plugin"
git push

# On mobile, clone/pull the vault via Working Copy
# Then copy the plugin files to .obsidian/plugins/omniroute-sync/

AirDrop

• Select main.js, manifest.json, and styles.css on your Mac.
• AirDrop them to your iPhone/iPad.
• Use the Files app to move them into <VAULT>/.obsidian/plugins/omniroute-sync/.

After copying, open Obsidian on mobile → Settings → Community plugins → Enable OmniRoute Sync.

Configuration

Open Obsidian → Settings → OmniRoute Sync.

Server (Desktop)

Setting	Default	Description
Server Port	27781	HTTP server port (requires restart)
Auto-start	On	Start the server automatically when the plugin loads
Auth Token	(empty)	Optional bearer token for API authentication. Leave empty to disable.

Client (Mobile)

Setting	Default	Description
Desktop address	(empty)	Tailscale MagicDNS name, IP (100.x.y.z), or URL of your desktop
Auto-discovery	On	Automatically find your desktop on the Tailscale network
Connection timeout	5000	Request timeout in milliseconds

Sync

Setting	Default	Description
Sync on save	On	Automatically push files when saved locally
Background sync interval	30	How often to sync on mobile (seconds). Set to 0 to disable.

Filter

Setting	Default	Description
Exclude tags	private, personal, draft	Comma-separated tags to exclude from sync
Minimum backlinks	0	Only sync notes with at least this many inbound [[links]]. Set to 0 to sync all.
Include private notes	Off	Sync notes tagged private or with private: true in frontmatter

Debug

Available when Debug mode is enabled:

Setting	Default	Description
Log sync operations	On	Log sync cycles
Log push operations	On	Log individual file pushes
Log pull operations	On	Log individual file pulls
Log conflicts	On	Log conflict detection and resolution
Log filter decisions	On	Log which files pass/fail the filter
Create conflict files	On	Save .conflict.md files on same-mtime edits

The Debug section also includes an in-plugin log viewer with Refresh, Clear, and Export buttons.

Finding Your Desktop Tailscale IP

macOS / Linux:

tailscale ip -4

Windows (PowerShell):

tailscale ip -4

Alternative — use MagicDNS: If Tailscale MagicDNS is enabled, use your device's Tailscale hostname (e.g., my-macbook.ts.net) instead of the raw IP.

Commands

Open the command palette (⌘+P on desktop, swipe down on mobile):

Command	Description
Toggle server / Toggle connection	Start/stop the sync server (desktop) or connect/disconnect (mobile)
Sync now	Trigger an immediate bidirectional sync
Browse remote vault	List files on the remote device
Search remote vault	Search notes on the remote device
Pull file from remote	Pull a specific file from the remote device
Push current file	Push the currently open file to the remote device
Test connection	Test connectivity to the desktop server
Discover desktop on Tailscale	Search for your desktop on the Tailscale network
View sync log	Open the debug log viewer

Conflict Resolution

When both devices edit the same note between syncs, the plugin creates a .conflict.md file containing the version that was NOT chosen. You'll see a notice in the settings panel:

• Keep local — Overwrite the remote file with your mobile version
• Keep remote — Delete the conflict file and keep the desktop version
• Keep both — Leave both versions in place

Troubleshooting

"Server error" in status bar: The server failed to start. Check that port 27781 is not in use:

lsof -i :27781

"Configure desktop Tailscale IP": Enter your desktop's Tailscale IP or MagicDNS name in Settings → OmniRoute Sync → Desktop address.

Files not syncing: Check the filter settings. Notes tagged private, personal, or draft are excluded by default.

Too many .conflict.md files: Disable conflict file creation in Settings → Debug → Create conflict files.

License

MIT