5.7 KiB
Limitations
VaultLink works well for most Obsidian vaults, but has some constraints you should know about.
File Type Limitations
Mergeable Files
Only .md and .txt files get automatic conflict-free merging.
For other file types, a one-sided change is retained. Concurrent unmergeable changes keep the server's version and archive displaced local bytes for recovery. Review recovery artifacts when both devices edit a binary file.
Binary Detection
Files are treated as binary if they:
- Contain NUL bytes (
0x00) - Fail UTF-8 validation
Binary files within .md or .txt extensions follow the same unmergeable-content policy.
Performance Constraints
Server Limits (Configurable)
| Resource | Default | Maximum Tested |
|---|---|---|
| Clients per vault | 256 | ~256 |
| Database connections | 12 | 20 |
| Max file size | 512 MB | 4096 MB |
| Request timeout | 60s | 180s |
| WebSocket cursor timeout | 60s | 300s |
| Database busy timeout | 3600s | - |
Vault Size
- Small vaults (< 1000 files): Excellent performance
- Medium vaults (1000-10000 files): Good performance
- Large vaults (> 10000 files): Works, but initial sync slower
No hard file count limit—constrained by disk space and sync time.
Resource Usage
Rough estimates (varies by vault size and activity):
- RAM: ~50-200 MB base + ~1-5 MB per active client
- CPU: Low (< 5%) for typical usage, spikes during merges
- Disk: Vault size + version history (grows over time)
Version History
Storage
- All versions stored indefinitely (no automatic cleanup)
- Each vault is a separate SQLite database
- Deletion removes file-manifest membership; content history remains readable
Growth: Version history grows with every change. A 10 MB vault with frequent edits might grow to 100+ MB over months.
Active journals, immutable merge bases and request receipts must not be independently deleted. There is no automatic safe history-pruning protocol.
Implications
- Disk usage grows over time
- Database size affects backup time
- No built-in retention policy
Merge Quality
Text Merging
VaultLink uses word-level tokenisation for merging:
Parent: "The quick brown fox"
User A: "The quick red fox"
User B: "The very quick brown fox"
Result: "The very quick red fox" ← Both changes preserved
Imperfect scenarios:
- Complex nested Markdown (tables, code blocks)
- Simultaneous edits to the same sentence
- Large structural changes (moving sections around)
Merged files may require manual review; there is no measured universal conflict-success rate.
Scalability
SQLite Limitations
- One SQLite database per vault
- Single-server architecture (no built-in clustering)
- Write serialisation through database
For high concurrency: Consider multiple vaults instead of one massive shared vault.
Horizontal Scaling
Not currently supported. Running multiple servers requires manual vault partitioning.
Network Requirements
Latency
- Real-time sync typically < 500ms on good connections
- Mobile/slow networks: 1-5s latency possible
- Timeout failures on very slow connections (> 60s)
Offline Behaviour
- Clients queue changes locally
- On reconnect, sync all changes since last connection
- Conflicts resolved automatically (for mergeable files)
Limitation: No offline conflict preview—merged result appears after reconnect.
Security
No End-to-End Encryption
- Server sees all file contents
- Transport encryption only (WSS/TLS)
- Trust your server
Workaround: Self-host on infrastructure you control.
Authentication
- Token-based only (no OAuth, SAML, etc.)
- Tokens configured in server config file
- No runtime user management
Restored backups
Restore server databases while the server is stopped. API v5 clients detect a changed history even when version numbers are reused. Clean files reconcile with the restored server; unsent edits are preserved as separate local documents. Clients and server must be upgraded together. This does not replace independent backups or protect against arbitrary physical-media corruption.
Known Edge Cases
Simultaneous Deletes and Edits
User A deletes note.md
User B edits note.md
Result: Manifest deletion removes the file; unsent edited bytes are retained for recovery.
Content updates do not restore deleted membership. The client retains displaced bytes in its local recovery directory.
Large File Uploads
Files > 100 MB may time out on slow connections. Increase response_timeout_seconds or split large files.
Mobile Sync
- Mobile networks may drop WebSocket connections frequently
- Client auto-reconnects, but causes sync delays
- Battery impact from constant reconnections
What VaultLink is NOT
- Not a backup solution: Version history helps but isn't a backup (make backups!)
- Not Git: No branching, no commit messages, no diffs to review before merge
- Not encrypted storage: Server sees everything
- Not multi-master: One server, multiple clients (not peer-to-peer)
Recommendations
Good Use Cases
- Personal multi-device sync (< 10 devices)
- Small team collaboration (< 20 people)
- Primarily text/Markdown content
- Trusted server environment
Poor Use Cases
- Large teams (> 50 concurrent users per vault)
- Primarily binary files (images, videos, large PDFs)
- Untrusted server (need E2E encryption)
- Highly regulated environments (HIPAA, etc.)