Background Sync

Keep Notes Synced While You Work

Background sync keeps your notes synchronized even when Strayfiles isn’t open. A lightweight daemon runs in the background, providing full bidirectional sync between your local files and Stray Cloud.

How It Works

You close Strayfiles
    ↓
Background sync daemon starts automatically
    ↓
Watches your note folders for changes
    ↓
Listens for cloud updates from other devices
    ↓
Syncs bidirectionally (Local ↔ Cloud)
    ↓
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

Bidirectional Sync

The daemon syncs in both directions automatically:

Local → Cloud:

Event	What Happens
File created/modified	Content synced to Stray Cloud
File deleted	Note removed from cloud
File renamed/moved	Path mapping updated
Frontmatter added manually	Note auto-registered to database

Cloud → Local:

Event	What Happens
Note created on another device	File materialized to ~/.strayfiles/notes/
Note content updated	Local file updated (preserving frontmatter)
Note deleted from cloud	Local file removed

Auto-Registration

If you manually add strayfiles frontmatter to a file:

---
strayfiles:
  enabled: true
  id: "your-uuid-here"
---

The daemon automatically:

1. Detects the frontmatter
2. Registers the note in the database
3. Creates a device mapping
4. Syncs metadata (workspaces, tags, alias) to cloud

This means you can add files to Strayfiles without using the app—just add the frontmatter and the daemon handles the rest.

File Materialization

Notes created on other devices appear locally in ~/.strayfiles/notes/. Each materialized file includes full frontmatter with the note’s UUID, so it stays synced across all your devices.

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 (LaunchAgent)
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

“File with frontmatter not appearing in app”:

• Verify the frontmatter syntax is correct (YAML format)
• Check that strayfiles.enabled: true is set
• Ensure the file is in a watched directory
• Check daemon logs for registration errors

“Notes from other devices not appearing locally”:

• Files materialize to ~/.strayfiles/notes/ by default
• Check that the directory exists and is writable
• Verify realtime connection in daemon logs