Quick start

This walkthrough takes you from nothing to a running two-way sync, safely. It assumes you’ve installed the binaries and that proton-drive is logged in.

Use a disposable folder first

Sync is bidirectional and deletions propagate. For your first run, use a throwaway local folder and a throwaway remote folder you don’t mind losing. Read Deletions & the safeguard before pointing this at real data.

1. Create a local folder

mkdir -p /tmp/proton-sync-demo

2. Preview the plan (--dry-run)

Always do this before a folder’s first real sync. Dry-run scans locally, lists the remote, reads any existing index read-only, prints the plan as JSON, and exits — without uploading, downloading, deleting, or writing the index.

proton-syncd \
  --local-root /tmp/proton-sync-demo \
  --remote-root /Drive/RemoteFolder \
  --dry-run

Look at the summary block, and especially at destructive_actions — the number of deletes and purges the run would perform. On a first sync of a fresh pair it should be 0 (the first pass is a non-destructive merge). See Dry-run preview for how to read the output.

3. Start the daemon

Once the plan looks right, run the daemon in the foreground:

proton-syncd \
  --local-root /tmp/proton-sync-demo \
  --remote-root /Drive/RemoteFolder

It reconciles once on startup, then watches the folder and reconciles on changes, on a periodic timer, and on demand. Stop it with Ctrl+C or SIGTERM; it removes its socket on shutdown.

By default the daemon keeps all of its state — the SQLite index, its status/metrics sidecars, and the instance lockfile — in a <local-root>/.sync/ directory that the engine always ignores. The control socket lives at $XDG_RUNTIME_DIR/proton-sync.sock.

4. Drive it from another terminal

The control CLI talks to the running daemon over its Unix socket:

proton-sync status      # is it running? what did it just do?
proton-sync history     # recent sync summaries and errors
proton-sync syncnow     # sync now and watch it finish
proton-sync pause       # stop automatic + manual sync
proton-sync resume      # resume

Output is a concise human-readable summary (the daemon answers instantly, even mid-sync); add --json to any command to get the raw response object for scripts. See the CLI reference for every command.

5. Approve your first deletion

The delete-approval guard is on by default, so the first time you delete a synced file and reconcile, the deletion is withheld rather than applied. List and approve it:

proton-sync pending                 # what's withheld, and in which direction
proton-sync approve notes/old.txt   # approve one item
proton-sync syncnow                 # apply it now

This is deliberate — see Delete approval to configure it (including turning it off globally or per folder).

Prefer a config file

Passing long paths on every invocation gets old. Put them in a TOML file and load it with --config:

proton-sync.toml

local_root = "/tmp/proton-sync-demo"
remote_root = "/Drive/RemoteFolder"
scan_interval_secs = 300

proton-syncd --config proton-sync.toml

Explicit CLI flags still override file values. See Configuration.

Or use the desktop app

If you’d rather not touch a terminal, launch the desktop app. Its onboarding wizard walks you through the same four steps — check the CLI, choose the folder pair, review the dry-run plan, and start the service — and then gives you live status, conflict resolution, and a tray icon. See Desktop app overview.

Next

• How sync works — what each action means and why.
• Running as a service — keep it running with systemd.
• Selective sync — sync only part of a folder.