README file from
GithubNAS Vault Sync
Sync your Obsidian vault with your own NAS (or any WebDAV server) — no subscription, no third-party cloud. Works on desktop and mobile.
Built as a personal replacement for paid sync services: your notes travel only between your devices and a server you own.
Features
- Two-way sync over WebDAV (tested against Synology WebDAV Server / Apache mod_dav)
- Mobile support (iOS/Android) — uses Obsidian's
requestUrl, no Node APIs - Unicode-safe — NFC/NFD canonical path layer, so Korean/Japanese/accented filenames sync correctly between macOS, Windows, and mobile
- Causal conflict resolution — per-device shard indexes with causal supersession (
prevhash chain). Sequential edits merge silently even with device clock skew; only true concurrent edits become conflicts, and the losing version is always preserved in_sync-conflicts/ - Deletion safety — deletes propagate as tombstones; local deletions go to
.trash/, never destroyed immediately - Mass-delete guard — if a cycle would delete more than max(50, 5%) of your files, it is blocked until you explicitly approve
- Resilient transfers — per-file retry with backoff, checkpoint every 200 files, offline cycles resume where they left off
- Third-party plugin friendly — write-back rehash + suppression window prevents infinite ping-pong with plugins that rewrite files on modify (e.g. update-time-on-edit)
Setup
- Enable a WebDAV server on your NAS (e.g. Synology: WebDAV Server package, HTTPS only). Create a dedicated user with access to a share such as
obsidian-sync. - Install this plugin, then open its settings:
- Server URL:
https://your-nas.example.com:5006/obsidian-sync/your-vault - Username / password of the dedicated account
- Press Test connection
- Server URL:
- Run Sync now (command palette, status bar on desktop, or add the command to your mobile toolbar). The first sync bootstraps safely: it never propagates deletions and preserves both sides of any difference.
Sync behavior
- Desktop: syncs on startup, after file changes (debounced), and on an interval (default 5 min).
- Mobile: iOS/Android cannot sync in the background (a platform restriction that applies to all sync solutions). Sync runs when the app is open, on the interval, or manually.
- Progress is shown as a file count. Logs: command Show sync log.
Commands
- Sync now
- Show sync log
- Reset skipped-file list — retry files that repeatedly failed
- Approve mass delete once — run a blocked mass deletion on the next cycle
- Rebuild remote index — recovery tool; re-reads the whole remote tree (downloads everything once)
Security notes
- Use HTTPS only. Create a NAS account dedicated to sync with access to a single share.
- Credentials are stored in the plugin's
data.jsoninside your vault. If your vault is a git repository, add.obsidian/plugins/*/data.jsonto.gitignore— the plugin warns you if it is not covered.
License
MIT