# syncroot

> Keep the same working folder on a laptop, workstation, and remote machines.
> syncroot synchronizes files directly between trusted devices, with no central
> syncroot server or account.

syncroot is a Rust daemon for trusted LANs, private mesh networks, and other
existing networks. It does not provide application-layer encryption, a relay,
NAT traversal, or per-path permissions.

Status: pre-launch. Wire and disk formats may change without migration. Run the
same build everywhere, keep a backup, and do not use syncroot as the only copy
of irreplaceable data. Files larger than 20 MiB are currently ignored.

## What users can rely on

- A file is readable only after its complete, hash-verified contents arrive.
- Every change records the device that originated it.
- Each peer orders its own changes; per-peer progress distinguishes not written
  from not arrived.
- Chunks are content-addressed.
- Connected devices eventually converge, with no latency bound.
- Concurrent versions receive deterministic conflict names. syncroot preserves
  them but cannot decide which edit is semantically correct.

## Boundaries

- Use trusted peers only; every folder member can write anywhere.
- Synchronized files cannot provide an atomic claim, compare-and-swap, or
  cross-path arrival ordering.
- Keep a backup because deletes propagate.
- Roster removal, snapshot join, compaction, garbage collection, symlink and
  metadata synchronization, relay, NAT traversal, and application encryption
  are not implemented.

## Connect two devices

First device:

    systemctl --user enable --now syncroot
    syncroot listen laptop.mesh.example
    syncroot init ~/shared
    syncroot invite ~/shared

Second device:

    systemctl --user enable --now syncroot
    syncroot listen desktop.mesh.example
    syncroot connect ~/shared 'syncroot://laptop.mesh.example:9494/abc123'
    syncroot status

The inviting peer may be temporarily offline during `connect`; syncroot saves
the invite and retries in the background.

## Convention for autonomous writers

- Give each agent `agents/<agent-id>/` and make every other path read-only.
- Create write-once names containing a ULID or content hash.
- Use journal directories with one file per entry, not one shared append-only
  file.
- Identify artifacts in markers by path, byte length, and hash because separate
  paths may arrive in either order.
- Check `syncroot status <root> --json` before treating a missing result as
  unfinished work.
- Use an external coordination store when work needs exactly one owner.

## Documentation

- User guide: https://syncroot.dev/readme.md
- Agent conventions: https://syncroot.dev/agents.md
- Benchmark method: https://syncroot.dev/benchmarks.md
- Source and issues: https://github.com/yuvadm/syncroot

License: Apache-2.0.