dotkeeper

How it works

Initialize

dotkeeper init on your first machine. Generates a Syncthing identity, scaffolds machine.toml.

Pair peers

Exchange device IDs between machines via machine.toml or dotkeeper peer add. P2P mesh — no central hub.

dotkeeper offers shows what peers have. dotkeeper subscribe github.com/foo/repo opts in. Files arrive in seconds.

Features

One-command onboarding

dotkeeper subscribe github.com/foo/repo on a fresh machine. The mesh seeds the working tree from any peer that has it. No manual git clone + track dance.

Self-tuning multi-transport

Syncthing, git push over SSH, and Mutagen coexist. A cost model picks per change and learns from every transfer. Active benchmarking refines per-folder predictions in the background.

Zero infrastructure

No cloud server, no VPN, no SSH tunnel required. Machines find each other via Syncthing's open discovery network and connect peer-to-peer.

Single binary

Syncthing is compiled into the dotkeeper binary. Download, run, done. No separate Syncthing installation, no conflicts with an existing setup.

Git history

Scheduled git auto-commit and push. Every change is versioned. Roll back to any point in time. Works with your existing remotes.

Conflict-free by design

Syncthing handles real-time sync. Git timers are staggered per machine (slot offsets) so pushes never collide.

Cross-platform

Linux, macOS, Windows, FreeBSD, OpenBSD, NetBSD. Platform-native service management: systemd, launchd, Task Scheduler, cron.

Privacy-first

No telemetry, no crash reporting, no usage tracking. Syncthing's full network stack for connectivity, with all reporting disabled.

Performance is a fail criterion

Idle steady-state CPU sits at ~0%. Hot-path benchmarks are gated by CI — perf regressions can't ship. Cold-start scans spread across time so the daemon stays invisible to the dev experience.

Architecture

                        +-------------+
                        |  Machine A  |
                        +-------------+
                         /           \
                        /             \
                       v               v
            +-------------+   <--->   +-------------+
            |  Machine B  |           |  Machine C  |    ...
            +-------------+           +-------------+
                  \                       /
                   \                     /
                    v                   v
                     +-----------------+
                     |   git remote    |   <- staggered
                     +-----------------+      backup slots

  Per machine:  ~/.config/dotkeeper/machine.toml + state.toml
  Per repo:     <repo>/.dotkeeper.toml  (local-only opt-in signal)

Isolated Syncthing

Runs on its own ports (API: 18384, sync: 12000, discovery: 11027). Never touches your existing Syncthing installation.

Three-file config

machine.toml — declarative local config. state.toml — tool-owned runtime state. .dotkeeper.toml — local per-repo desired state.

Smart .stignore

Auto-generated ignore patterns: build artifacts, lockfiles, editor state, SQLite journals. Syncs what matters, skips what doesn't.

Install

Download binary

Grab the latest release for your platform:

Download from GitHub

macOS / Linux (Homebrew)

brew tap corbet-labs/dotkeeper
brew install dotkeeper

Arch Linux (AUR)

yay -S dotkeeper-bin

Build from source

git clone https://github.com/corbet-labs/dotkeeper
cd dotkeeper
make install

Requires Go 1.26+ and git.

Commands

`dotkeeper init`	Initialize this machine
`dotkeeper identity`	Print this machine's name and device ID
`dotkeeper start`	Run the daemon (Syncthing + reconciler)
`dotkeeper reconcile`	Converge Syncthing and git now
`dotkeeper status`	Show full status
`dotkeeper health`	Operational dashboard with `--explain`, `--watch`, `--json`
`dotkeeper doctor`	Run diagnostic checks
`dotkeeper peer add/list/remove`	Manage imperative peers
`dotkeeper track <path>`	Register an out-of-root repo
`dotkeeper untrack <path>`	Remove an out-of-root override
`dotkeeper subscribe <git-url>`	Declare this machine wants the named repo (Phase 2)
`dotkeeper unsubscribe <git-url>`	Remove an imperative subscription
`dotkeeper subscriptions list`	Show merged subscription list with SOURCE column
`dotkeeper offers`	List folders peers are advertising that this machine could subscribe to
`dotkeeper conflict list`	List Syncthing sync-conflict files
`dotkeeper conflict resolve-all`	Auto-resolve trivial conflicts (dedup + 3-way merge)
`dotkeeper conflict keep <path>`	Keep current, drop the conflict variant
`dotkeeper conflict accept <path>`	Replace current with the variant and commit
`dotkeeper transport list`	List configured transports + availability
`dotkeeper transport status [peer]`	Per-peer reachability + cross-repo cost-model parameters
`dotkeeper transport repos`	Per-(transport, peer, repo) cost-model predictions
`dotkeeper bench-now`	Operator-triggered transport benchmark
`dotkeeper bare-init`	Configure peer-side git repos for direct `git push`
`dotkeeper version`	Print version and commit