Zero-Cloud Obsidian Sync: Real-Time Mobile Replication with Syncthing and Tailscale

One of the greatest strengths of Obsidian is that your notes are just a local folder of Markdown files. There are no proprietary database blobs, no vendor lock-in, and no mandatory cloud accounts. Your thoughts, journal entries, code snippets, and research remain entirely under your control.

However, the moment you want to access that knowledge base on your smartphone, you run straight into the Mobile Synchronization Dilemma:

• First-Party Obsidian Sync is polished and encrypted, but requires a recurring monthly subscription per user.
• Commercial Cloud Drives (Google Drive, Dropbox, OneDrive) require clunky third-party synchronization bridges on mobile, frequently mangle file timestamps, and expose your unencrypted personal notes to commercial data aggregators.
• Git Sync (obsidian-git) is fantastic on desktop, but on mobile it introduces battery drain, merge conflicts, and awkward commit-and-push friction when you just want to jot down a quick thought.

If you already operate a Linux workstation and a homelab, there is a vastly superior, 100% self-hosted alternative: Syncthing paired with Tailscale.

By combining Syncthing’s continuous peer-to-peer block-level replication with Tailscale’s zero-config WireGuard mesh network, you can achieve instant, zero-cloud synchronization between your Linux laptop and Android phone.

In this guide, I will walk through the architecture, the exact setup process, and—most importantly—the real-world Android filesystem edge cases and ignore patterns you must solve to keep 20,000+ notes and attachments in perpetual harmony.

1. The Architecture: Direct P2P Mesh Synchronization

The goal of this architecture is complete data sovereignty, zero cloud intermediaries, and immediate, seamless updates whether you are sitting at your desk or connected over cellular data on the other side of the world.

                           +------------------------+
                           |  Home Wi-Fi Network    |
                           |  (Local Subnet / LAN)  |
                           +-----------+------------+
                                       |
                   +-------------------+-------------------+
                   |                                       |
                   v                                       v
        +---------------------+                 +---------------------+
        |    Linux Laptop     |  Direct LAN     |    Android Phone    |
        |   (Obsidian Vault)  |<===============>|   (Obsidian App)    |
        |  192.168.1.x:22000  |  TLS 1.3 P2P    |  192.168.1.y:22000  |
        +---------------------+                 +---------------------+
                   ^                                       ^
                   |                                       |
                   +-------------------+-------------------+
                                       |
                           +-----------+------------+
                           |  Tailscale WireGuard   |
                           |  (Encrypted Overlay)   |
                           |  100.x.x.a <-> 100.x.x.b|
                           +------------------------+
                           [When Traveling / Remote]

Why Syncthing + Tailscale?

1. Block-Level Incremental Sync: When you append three lines to a 50 KB Markdown note, Syncthing only transmits the changed cryptographic blocks over the wire—not the entire file.
2. End-to-End Encryption: Communication between paired devices uses TLS 1.3 with mutual certificate verification. No intermediate server can read your notes.
3. Dual-Path Connectivity:
   • At Home: Syncthing detects devices on the local subnet and streams data directly over high-speed local Wi-Fi.
   • Away from Home: Instead of falling back to slow, bandwidth-throttled public relay servers, Syncthing connects directly peer-to-peer over your private Tailscale WireGuard tunnel at full 5G/broadband speed.

2. Step-by-Step Implementation

Step 1: Install & Enable Syncthing on Linux

On Fedora, Debian, or Ubuntu, install Syncthing and enable it as a user systemd service so it runs continuously in the background without needing a terminal open:

# Fedora
sudo dnf install -y syncthing

# Debian / Ubuntu
sudo apt install -y syncthing

# Enable and start user service
systemctl --user enable --now syncthing

Verify that the local management Web UI is accessible by visiting http://localhost:8384 in your browser.

Step 2: Install Verified Syncthing on Android

Because the Google Play Store is flooded with clones, repackaged forks, and adware, verify that you install a trusted open-source client:

• Recommended: Syncthing-Fork by Felix Ableitner (com.github.catfriend1.syncthingandroid), available on F-Droid and Google Play. It features vastly improved battery management, active maintenance, and proper integration with modern Android Scoped Storage.
• Alternative: Official Syncthing by The Syncthing Foundation (com.nutomic.syncthingandroid).

Upon launch, grant the necessary storage permissions so the app can read and write to your device’s document storage.

Step 3: Pair Devices Securely

1. In the Android Syncthing app, open the side menu and tap Show Device ID (or show the QR code).
2. On your laptop’s Syncthing Web UI (http://localhost:8384), click Add Remote Device in the bottom right corner.
3. If both devices are on the same local Wi-Fi, your phone will likely appear under Nearby Devices. Otherwise, enter the Device ID manually.
4. Name the device (e.g. Linux-Laptop or Android-Phone) and click Save.
5. Within seconds, a prompt will appear on your phone: “Device [Laptop] wants to connect”. Tap Accept.

Step 4: Share the Vault Folder

1. In your laptop’s Web UI, click Add Folder:
   • Folder Label: Obsidian Vault
   • Folder ID: obsidian-vault (Keep this simple and identical on both ends)
   • Folder Path: The absolute path to your vault (e.g. ~/Vault/Personal)
2. In the Sharing tab, check the box for your mobile device.
3. In the File Versioning tab, select Simple Versioning (keeping 5 versions). This creates a local safety net against accidental deletions.
4. Click Save.
5. On your phone, accept the incoming folder invitation and select your mobile storage destination:Documents/Obsidian/Personal

3. The Three Critical Gotchas (And How to Fix Them)

Setting up Syncthing takes five minutes. But if you stop here, you will inevitably encounter sync conflicts, broken UI states, and mysterious “Out of Sync” errors.

Here are the three real-world edge cases you must solve:

Gotcha 1: The Android Filesystem Character Trap (EINVAL)

Linux filesystems (ext4, Btrfs, ZFS) allow virtually any character in a filename except the forward slash (/) and null byte. It is extremely common for technical notes, book titles, and downloaded academic papers to contain colons (:):

Research/Papers/Distributed Systems: Towards Fault-Tolerant Architectures/paper.pdf

The Problem: Android’s storage layer (emulated FAT/exFAT/FUSE) strictly forbids Windows-restricted characters:

• Colon (:)
• Question mark (?)
• Asterisk (*)
• Pipe (|)
• Double quotes (")
• Angle brackets (<, >)

When Syncthing tries to create a folder or file containing a colon on Android, the operating system throws an EINVAL (Invalid Argument) I/O error. The file is permanently marked as “Out of Sync” on mobile, and synchronization stalls.

The Fix: Audit your vault for illegal Android characters and rename them before syncing:

# Find any directory or file with a colon in your vault
find ~/Vault -name "*:*"

# Rename to replace colons with dashes
mv "Path/With: Colon" "Path/With - Colon"

Gotcha 2: The Obsidian Workspace Conflict Loop

Obsidian stores your open tabs, panel layout, and cursor positions in .obsidian/workspace.json.

On desktop, you might have four split panes and a graph view open. On mobile, you have a single vertical tab. If you synchronize workspace.json, every time you switch devices Obsidian will try to force the desktop layout onto the mobile screen and vice versa, triggering endless sync conflicts (workspace.sync-conflict-...json).

The Fix: You must configure an ignore file. In the root of your vault, create a .stignore file:

(?d).obsidian/workspace.json
(?d).obsidian/workspace-mobile.json
(?d).stversions
(?d).DS_Store

Why the (?d) prefix?
The (?d) flag tells Syncthing that this pattern is safe to delete if another device deletes the parent directory. Without it, Syncthing might refuse to delete a directory because it contains an ignored file.

Gotcha 3: The 0-Byte File Stumble

Some legacy notes or empty placeholder files (.ods, .txt, .tmp) have a size of exactly 0 bytes. On certain versions of Android’s Storage Access Framework (SAF), zero-byte file allocations can fail to report completion, causing Syncthing to flag the file as un-synced.

If an empty file refuses to sync, either delete it or add it to .stignore:

(?d)Path/To/empty_file.ods

Once .stignore is updated, Syncthing immediately clears the error queue and returns to 100% Up to Date.

4. Unlocking Remote Sync: Bypassing Public Relays with Tailscale

When both devices are on your home Wi-Fi, Syncthing syncs over LAN at maximum throughput. But what happens when you step out of the house?

By default, Syncthing uses Global Discovery and Public Relays. If direct NAT traversal fails, your traffic bounces through a third-party community relay node. While encrypted, public relays are severely rate-limited (often 50–200 KB/s) and can take minutes to establish a connection.

The Tailscale Fix: Direct WireGuard Mesh Routing

If both your Linux laptop and your phone have Tailscale installed, they each have a static, 100% private IP address within your CGNAT range (e.g. 100.64.0.10 and 100.64.0.20).

Instead of letting Syncthing guess how to reach your devices over the public internet, you can explicitly configure it to use your private Tailscale tunnel.

1. Configure the Remote Device on Your Phone:

In the mobile Syncthing app, edit your laptop’s device settings and update Addresses:

tcp://100.64.0.10:22000, dynamic

(Replace 100.64.0.10 with your laptop’s actual Tailscale IP).

2. Configure the Remote Device on Your Laptop:

In your laptop’s Web UI (http://localhost:8384), edit your mobile device settings and update Addresses:

tcp://100.64.0.20:22000, dynamic

(Replace 100.64.0.20 with your phone’s actual Tailscale IP).

Why the , dynamic Suffix Matters

Notice that we append , dynamic after the Tailscale IP.

This tells Syncthing:

1. First, attempt a direct connection over your encrypted Tailscale WireGuard tunnel (100.x.x.x).
2. If both devices happen to be on the same local Wi-Fi, fall back to local LAN discovery for even lower latency.

With this configuration, your vault synchronizes at full 5G speed across cellular networks without a single byte touching a public relay server.

5. Taking It Further: The Always-On Homelab Sync Hub

There is one limitation to a direct two-device setup: your laptop must be powered on and awake for your phone to receive updates.

If your laptop is asleep in your backpack while you’re commuting, you won’t be able to sync changes made on your phone until you open the laptop again.

If you have a homelab server, a Raspberry Pi, or a NAS that runs 24/7, you can turn it into an always-on Syncthing Hub:

                         +-----------------------+
                         | 24/7 Homelab NAS/Pi   |
                         | (Syncthing Container) |
                         +-----------+-----------+
                                     ^
                                     | (Tailscale Mesh)
                    +----------------+----------------+
                    |                                 |
                    v                                 v
         +---------------------+           +---------------------+
         |    Linux Laptop     |           |    Android Phone    |
         |    (Workstation)    |           |   (Mobile Device)   |
         +---------------------+           +---------------------+

In this triangle topology:

1. Your phone syncs to the homelab server immediately over 5G.
2. Whenever you open your laptop, it pulls the latest notes from the server in seconds.
3. You achieve cloud-like continuous availability with 100% self-hosted infrastructure.

6. Closing the Loop: The Shared Mobile AI Brain with Gemini Scribe

Once your vault synchronizes continuously in the background, you unlock a superpower that goes far beyond simply reading or editing notes on your phone: mobile parity with your workstation CLI AI assistant (agy).

The Problem with Consumer Mobile AI

If you use the standard Gemini consumer app on your phone, it lives in a silo. It has zero visibility into your local Obsidian notes, your homelab server topology, your active projects, or the technical breakthroughs you logged on your workstation an hour ago. Every time you ask it a question on the go, you have to re-explain the context from scratch.

Running Gemini Inside Obsidian Mobile

By installing the community plugin Gemini Scribe on Obsidian Mobile, you turn your phone into an autonomous AI node that operates directly on your local Markdown tree.

Configuring it with your Google AI Studio API key (gemini-2.5-flash or gemini-2.5-pro) and enabling Agent Mode (Tool Calling) equips the mobile model with file-level read, write, search, and patch capabilities across your entire vault.

The Secret: Vault-Driven Prompt Templates

A common point of confusion when setting up Gemini Scribe is that there is no static “System Prompt” text box in the plugin settings. Instead, Gemini Scribe stores prompt templates as first-class Markdown files inside your vault under:

gemini-scribe/Prompts/*.md

Because your entire vault is synchronized via Syncthing, you can create or update this prompt template on your laptop, and it replicates to your phone in seconds.

To make the mobile agent mirror the exact rules and memory structure of your laptop’s agy assistant, create gemini-scribe/Prompts/antigravity.md:

---
name: "Antigravity Assistant"
description: "Autonomous pair programmer and personal assistant matching agy rules"
version: 1
override_system_prompt: true
tags: ["agy", "assistant", "system"]
---

You are Antigravity, an autonomous AI pair-programmer and personal assistant working directly inside the Obsidian vault.

### Core Operating Directives:
- Consult `Meta/antigravity-memory.md` for infrastructure topology, smart home devices, and fleet notes.
- Consult `Meta/states/antigravity.md` for current active focus and recent milestones.
- Keep answers concise and direct: Conclusion first, zero fluff.
- When asked about fleet status, tape backups, or homelab services, use your vault tools to read the relevant notes in `Meta/` (e.g. `Meta/tape-backups.md`).
- If recording significant updates, breakthroughs, or learnings, append them to `Meta/agent-log.md`.
- Maintain data integrity and follow the Forward-Fix Only policy across all notes and configurations.

Notice the frontmatter flag override_system_prompt: true. This instructs Gemini Scribe to replace its default system instruction with your custom prompt.

Activating on Mobile (30 Seconds)

1. Open the Gemini Scribe chat window in Obsidian Mobile.
2. Tap the Session settings gear icon at the top of the chat panel.
3. Under Prompt template, select Antigravity Assistant from the dropdown.
4. Done.

True Two-Way Persistent Context

Now, the feedback loop is complete:

1. On the Road: You swipe down on your phone, open Gemini chat, and ask: “What is the status of our remote LTO-4 tape backups and NAS fleet?”
2. Tool Execution: Gemini Scribe calls its local file tools, inspects Meta/antigravity-memory.md and Meta/tape-backups.md directly from your device storage, and answers instantly with full, accurate context.
3. Session Archiving: Gemini Scribe automatically saves the conversation as a timestamped Markdown note under gemini-scribe/Agent-Sessions/ (or your preferred Meta/ directory).
4. Seamless Return: Syncthing quietly streams the mobile session note back to your workstation over Tailscale. When you sit down at your desk and launch agy in your terminal, the agent is already aware of what you discussed and decided on your phone.

7. Summary: Complete Control Over Your Knowledge Base

By combining Obsidian, Syncthing, Tailscale, and Gemini Scribe, you get the holy grail of modern note-taking:

Your notes belong to you. With a few minutes of setup and the proper ignore rules, you can carry your entire digital brain—and an autonomous AI assistant that knows everything you know—in your pocket without sacrificing privacy, speed, or sovereignty.