dropbear

Personal Dropbox, More Cuddly

Single-user file sync between local folders and S3-compatible object storage. The bucket stores content-addressed (SHA-256) blobs, per-device JSON manifests, and tombstones — never a POSIX filesystem. Local state lives in SQLite; each synced root carries its identity in .dropbear/root.toml.

What it does

• Bidirectional sync with explicit tombstones for deletes and conflict files instead of auto-merge.
• Removable-drive safe — a missing root is offline, never an inferred deletion.
• On-demand downloads ("shelving") — remote files can live as zero-byte stubs and materialize when you fetch them.
• Daemon mode — a background supervisor watches N roots with a filesystem watcher, remote head polling, a loopback status API, and systemd/launchd packaging.
• Sync modes per root: bidirectional, upload-only, download-only, archive-only.

Non-goals: multi-user, FUSE, realtime collaboration, POSIX-on-S3, full ACL preservation.

Install

brew tap tfks/tap https://git.tfks.net/tfks/homebrew-tap.git
brew install tfks/tap/dropbear   # installs dropbear + dropbear-tray (builds from source)

Then bootstrap the background service — create the credentials env file and run dropbear daemon install; see wiki/runbooks/homebrew-install.md. Manage the folders the daemon watches with dropbear roots list|add|remove (edits daemon.toml in place; --restart applies immediately).

Quick start (from a checkout)

just setup              # check prereqs, configure git hooks, download modules
just build              # compile ./bin/dropbear

# point a folder at a bucket (credentials via env: DROPBEAR_S3_* or AWS_*)
dropbear register ~/Sync \
  --root-id home --device-id laptop \
  --remote-bucket my-bucket --remote-endpoint https://…
dropbear sync ~/Sync    # upload/download pending changes
dropbear status ~/Sync  # health report: identity, classification, conflicts, peers, drift

Run dropbear --help for the full command set. Highlights: register, scan, plan, sync, fetch, shelve, restore, status, clean, gc, retire, daemon, roots.

Development

just            # list every recipe
just check      # format + vet + lint (run after edits)
just validate   # check + tests + secrets scan + dep audit (CI gate)

Where to look next

• wiki/PROJECT.md — current state, direction, and the index of architectural decisions (wiki/decisions/).
• wiki/runbooks/ — operational workflows, also runnable as /runbooks:<name> slash commands.
• AGENTS.md — the operating manual for humans and AI agents working in this repo.
• openspec/ — proposals and specs for in-flight and shipped changes.
• doc/ — feature and use-case notes.