Obsidian Syncthing Setup

Properties1
tagsguides

4 min read

Obsidian + Syncthing Setup Guide (Mac + Android)

Summary: How to view/edit the repo in Obsidian on Mac/Android via Syncthing (VPS as always-on peer) — pairing steps, vault setup, editing workflow, troubleshooting. The vault IS the repo; edits auto-commit to GitHub.

Date: 2026-08-14 Purpose: View/edit the Hermes knowledge base (the GitHub repo) in the Obsidian app on your Mac and Android phone — with the graph view, backlinks, and search — synced via the VPS.

Architecture

VPS (Syncthing daemon, folder = /opt/data/hermes-repo)   ← already configured
   ↕ Syncthing (ignores .git, .secrets, binaries)
Mac (Syncthing → ~/hermes-repo)  →  open in Obsidian as vault
Android (Syncthing app → local folder)  →  open in Obsidian as vault
  • The GitHub repo stays the single source of truth. Edits you make in Obsidian sync to the VPS via Syncthing, then the VPS daemon auto-commits + pushes them to GitHub (2-minute debounce).
  • The .stignore file (already in the repo) stops .git, secrets, binaries, and Obsidian per-device state from syncing.
  • Staggered versioning is ON on the VPS only (keeps 5 versions, 30 days) — accidental deletions are recoverable.

Part 1 — Mac

1. Install Syncthing (GUI)

Easiest: Syncthing.app (community macOS wrapper) or Homebrew:

brew install --cask syncthing

Then start it: open the app, or brew services start syncthing. The web UI opens at http://127.0.0.1:8384.

2. Get your Mac’s Device ID

In the Syncthing UI (bottom right): Actions → Show ID (or Settings → This Device). Copy it — you’ll send this to me so I can authorize it on the VPS. It looks like:

XXXXXXX-YYYYYYY-ZZZZZZZ-AAAAAAA-BBBBBBB-CCCCCCC-DDDDDDD-EEEEEEE

3. Pair with the VPS

Once you’ve sent me your Device ID, I’ll add it to the VPS and share the hermes-repo folder. On your side, in Syncthing UI:

  1. Add Remote Device: paste the VPS Device ID SC6VG7I-DTYO6HY-JCFUNN4-AJFEOKF-XZNBNIX-LEMW4BR-HNP5JO3-NBV2OAZ
  2. Click Add Device — the folder-share prompt appears; accept hermes-repo
  3. Choose a local path: ~/hermes-repo (must be EMPTY — it will download the ~40 MB)

Wait for the initial sync (bottom status bar). ~810 files.

4. Open in Obsidian

  1. Install Obsidian from obsidian.md (free)
  2. First launch → Open folder as vault → select ~/hermes-repo
  3. You now have the full graph view (sidebar icon), backlinks, and search on your docs
  4. (Optional but recommended) Install the Hermes Agent plugin from Community Plugins → gives the Smart Graph (semantic links) + chat with the gateway

5. Editing workflow

  • Edit any note in Obsidian → Syncthing syncs it to the VPS within seconds → the daemon commits + pushes to GitHub within ~2 min → the web site (hermesvps.pages.dev) updates on the next deploy.
  • Keep the app running (or at least open it regularly) so changes flow.

Part 2 — Android

  1. Install Syncthing (F-Droid) from the Play Store or F-Droid — the official app
  2. Open it → Add Device → paste the same VPS Device ID above → Add
  3. When the folder-share prompt appears, accept hermes-repo, choose local folder /storage/emulated/0/Documents/hermes-repo (or wherever)
  4. Wait for initial sync (~40 MB — do this on Wi-Fi)
  5. Battery optimization: Android may kill Syncthing in the background. Go to Settings → Apps → Syncthing → Battery → Unrestricted so it stays alive. (Syncthing shows a persistent notification when running.)
  6. Install Obsidian from Play Store → Open folder as vault → select the synced folder
  7. Optional: use Syncthing’s manual sync button when you open the app if you want to force an immediate pull

Troubleshooting

ProblemFix
Mac/Android shows “no such device”Device ID typo — IDs are case-sensitive, use the exact string
Folder not offeredI must have added your device on the VPS side first — send me your ID
Edits not appearing on GitHubCheck the VPS daemon log: tail -f /opt/data/logs/sync-daemon.log
Conflict files (.sync-conflict-*)Rare (single user). Send me the filename; git history is the undo
Obsidian shows “vault not found”The folder must be the one Syncthing downloaded INTO (contains .md files at root, e.g. index.md, guides/)

What NOT to put in the vault

The .stignore already blocks these, but FYI: scripts with credentials (scripts/, hermes-config/, profiles/), the .git folder, and binaries are not synced. The full repo stays on the VPS + GitHub.

Part of the knowledge-base system — see guides/knowledge-base-visualization-comparison.md for the full architecture.

Graph View

Backlinks