Background Sync

Keep Notes Synced While You Work

Background sync keeps your notes synchronized even when Strayfiles isn’t open. A lightweight process runs in the background, watching for file changes and syncing them to Stray Cloud automatically.

How It Works

You close Strayfiles
    ↓
Background sync starts automatically
    ↓
Watches your note folders
    ↓
Detects file changes
    ↓
Syncs to Stray Cloud (encrypted)
    ↓
You open Strayfiles
    ↓
Background sync stops (app takes over)

When to Use Background Sync

Background sync is useful when you:

• Edit notes with other tools (VS Code, vim, etc.) while Strayfiles is closed
• Want changes to sync immediately without opening Strayfiles
• Work across multiple devices and want them always in sync

Enabling Auto-Start

1. Open Strayfiles
2. Go to Settings > Sync
3. Toggle “Auto-start background sync” on

When enabled, the sync process starts automatically when your computer boots and runs quietly in the background.

Manual Control

You can also control background sync from the command line:

# Start sync manually (runs in foreground, Ctrl+C to stop)
strayfiles --serve

# Check if background sync is running
strayfiles --status

Automatic Handoff

Strayfiles handles the transition automatically:

Scenario	What Happens
Open Strayfiles	Background sync stops, app syncs
Close Strayfiles	Background sync resumes
Both running	App takes priority

You don’t need to manage this—it just works.

Logs

Background sync logs to ~/.strayfiles/daemon.log. Check this file if sync isn’t working as expected.

Platform Support

Platform	Auto-Start Method
macOS	launchd (Login Items)
Linux	systemd user service

Troubleshooting

“Sync not running”:

• Check strayfiles --status
• Verify you’re signed into a Pro account
• Check logs at ~/.strayfiles/daemon.log

“Changes not syncing”:

• Ensure encryption password is set
• Check internet connection
• Verify Pro subscription is active