Syncing the Vault to Your Mac

The Obsidian vault materializes on the server — the NAS, in a production deploy — under ROBOCO_VAULT_PATH. Obsidian itself is a desktop/mobile app, so to actually browse the vault you need that folder on the machine running it. This page is the full runbook for getting it onto your Mac, three ways, best first.

Real-time, two-way, no cloud hop, free. This is the right choice if you ever edit notes yourself — most importantly, dropping a note into RoboCo/Inbox/ for the #roboco intake loop.

  1. Install Syncthing on the NAS. Most NAS OSes either ship it in an app center or run it as a small Docker container — either works, it just needs to see the vault's root folder (e.g. /volume1/roboco/data/vault) on disk.
  2. Install Syncthing on the Mac.
    bash
    1brew install syncthing2brew services start syncthing
  3. Pair the two devices. Open the Syncthing web UI on each side (the NAS's container exposes one on its own port; the Mac's is at http://localhost:8384) and add the other as a remote device using its device ID — each UI shows its own ID and has an "Add Remote Device" flow that takes the other's.
  4. Share the vault folder from the NAS. In the NAS's Syncthing UI, share the vault root (the folder containing RoboCo/ and .obsidian/) with the Mac device.
  5. Accept it on the Mac. Syncthing prompts you to accept the incoming share and pick a local destination folder. Point Obsidian's "Open folder as vault" at that folder.
  6. Set both sides to Send & Receive, not Send Only / Receive Only. One-way sync means edits you make on the Mac (or the #roboco inbox loop reading them back) never reach the NAS.
  7. Ignore Obsidian's own transient window state. Add this to .stignore on both devices:
    text
    1.obsidian/workspace.json
    Without it, the NAS-side process and your Mac each rewrite workspace.json as they open/close panes, and Syncthing ping-pongs the two versions back and forth — harmless, but noisy. Everything else under .obsidian/ (themes, community-plugin settings, the shipped Bases/Dataview/Kanban config) is fine to sync as-is.
Already have a personal vault?

Run python -m roboco.vault relocate <path-to-your-vault> once (server-side) to graft the RoboCo/ subtree straight into your existing personal vault instead of syncing a second, separate one — your vault's own .obsidian/ config is never touched by the relocate. Then sync that one vault as above.

Conflicts are non-destructive: Syncthing writes a <name>.sync-conflict-<date>-<device>.md copy instead of overwriting, and because every note carries a stable aliases: [<id8>], a rename or an occasional conflict copy never breaks a wikilink pointing at it.

Option 2: SMB mount (simpler, read-mostly)

Good enough if you mostly read the vault on your Mac and rarely write to it.

  1. Share the vault's parent folder over SMB from the NAS (built into most NAS OSes' file-sharing settings).
  2. On the Mac: Finder → Go → Connect to Server → smb://<nas-address>/<share-name>.
  3. Point Obsidian's "Open folder as vault" at the mounted share.
Gotchas
  • Never let iCloud Drive also sync the same folder. iCloud and an SMB mount both trying to reconcile file versions on the same directory is a known way to corrupt an Obsidian vault's index. Keep a network-mounted vault out of ~/Library/Mobile Documents entirely.
  • Search and the graph view are slower over SMB than over local disk or a Syncthing-synced copy, since every read crosses the network.
  • No offline access. NAS down or Mac off the LAN/VPN means the vault is simply unreachable — there's no local cache to fall back on.
  • A network hiccup mid-write can leave .obsidian/workspace.json in a bad state (harmless — delete it, Obsidian regenerates it on next open) or, rarely, interrupt a note save.

Option 3: Obsidian Sync (paid)

Obsidian's own end-to-end-encrypted sync service, sold as a subscription add-on to the app. No NAS-side install at all — you'd instead treat the NAS folder as one synced vault among Obsidian Sync's own device list. Worth it if you want the vault on more devices (phone, iPad) without standing up any extra infrastructure yourself. If it's just a Mac you care about, Syncthing gets you the same result for free with one extra install.

Next

→ Obsidian Vault — what the vault is and how it's populated. → Deployment — where ROBOCO_VAULT_PATH and ROBOCO_DATA_DIR live in the compose layout.

llms.txt