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](/features/status) — 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

| Mode            | Pulls remote content | Applies remote deletes | Publishes own changes |
| --------------- | ------------------ | -------------------- | --------------------- |
| `bidirectional` | yes                | yes                  | yes                   |
| `upload-only`   | no                 | no                   | yes                   |
| `download-only` | yes                | yes                  | no                    |
| `archive-only`  | yes                | **no — keeps local** | no                    |

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.

```shell
$ 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.

```shell
$ 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.

```shell
$ 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.

```shell
$ 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.