Use Cases

The headline use case is keeping a personal folder in sync across a couple of devices via S3-compatible storage. Beyond that, Dropbear's sync modes let the same binary serve several deployment shapes — backup-only phones, read-only mirrors, write-once archives — without forking the code path.

• Status & Drift Detection — what dropbear status shows, and how to read it

Each Dropbear root picks one of four sync modes at init time. The mode is bound to the root's identity in .dropbear/root.toml; there is no per-run --mode flag. The same binary, with the same bucket and the same blob store, can serve a phone that only pushes, a desk that only pulls, and an archive that never deletes — by choosing different modes.

The Four Modes

The non-obvious row is the last one: archive-only still records remote tombstones as "seen" (so it doesn't reprocess them on every sync), but never removes the matching local file. The archive is a one-way ratchet.

bidirectional — the default

Two laptops, one bucket. Both sides edit, both sides publish, both sides pull. New files propagate, modifications propagate, deletes propagate as explicit tombstones. If you don't have a specific reason to pick another mode, this is it.

$ dropbear init --root-id notes --device-id laptop --mode bidirectional \
    --remote-bucket my-bucket --remote-endpoint https://… ~/notes

upload-only — I am a source of truth

The bucket is a backup target. Use this when:

• A phone or camera should push photos out but never pull anything back in.
• A workstation publishes a directory the rest of the fleet consumes, and you don't want other machines' edits ending up in your local tree.
• You accept that "the bucket reflects me" — remote deletes never reach this device, remote files never appear in this device's filesystem.

The download phase and remote-tombstone application are both skipped; the rest of the pipeline (walk, manifest, blob upload, tombstone emit, head publish) runs normally.

$ dropbear init --root-id phone-photos --device-id phone --mode upload-only ...

download-only — I am a read-only consumer

You want to see what other devices have published, but never push anything back. Even edits made locally stay local — no manifest is built, no head is written, no blob is uploaded for this device. Use this when:

• A second machine should mirror a shared dataset without participating in it.
• A CI runner or sandbox mirrors content out of the bucket for builds.
• You want a "look but don't touch" device for a shared collection.

$ dropbear init --root-id shared-docs --device-id reader --mode download-only ...

archive-only — I am a write-once mirror

The bucket may change. The archive only grows. Use this when:

• A long-term archive drive holds photos, scans, or raw footage, and source devices may delete upstream (a phone running out of space) — but the archive should keep everything that ever reached it.
• A disaster-recovery target should not be able to be destroyed by activity on other machines. Tombstones are recorded as seen, but the file stays on disk.
• This is "the last copy" device. If everything else is wiped, the archive still has it.

$ dropbear init --root-id raw-photos --device-id archive --mode archive-only ...

In archive mode, the per-run sync result includes an archived_tombstones_skipped counter (and the ⊙ symbol in human output) so you can see how many remote deletes the archive declined to act on.

Choosing between download-only and archive-only

Both modes pull, neither publishes. The single question is what should happen when another device deletes a file?

• download-only honors the delete. Your local mirror faithfully tracks the bucket, including removals.
• archive-only ignores the delete. Your archive is a one-way ratchet — content accumulates and never gets pruned by upstream activity.

If your instinct is "I want a passive copy of what's in the bucket," you mean download-only. If your instinct is "I want a vault that captures everything that ever existed upstream," you mean archive-only.

What Sync Modes Do Not Do

• Per-path modes (e.g. "archive these directories, bidirectional those") — modes are whole-root. Per-path rules would live in a future rules feature.
• Per-run overrides — mode is identity, not invocation. Switching modes means editing root.toml.
• Quotas, retention, size caps — none of these exist. archive-only means "don't delete," not "delete after N days."

Manual Verification

If you want to sanity-check a mode before trusting it on real data, the shape is the same for all four:

1. Spin up two roots pointed at the same bucket (or local MinIO). Init root A as bidirectional. Init root B as the mode you're testing.
2. Put a file in A, run dropbear sync on A. Run dropbear sync on B. Observe what B did — or didn't do.
3. Delete the file in A, run dropbear sync on A (this emits a tombstone). Run dropbear sync on B. Observe how B handled the tombstone.

The table at the top of this page is the cheat sheet for what to expect at each step.