One office, one download: how the LAN-first P2P actually works

"The cloud fetches once per office, not once per editor" is the single biggest claim on our homepage. It's worth explaining exactly what's happening under that sentence, because none of it is magic. It's a fairly small, deliberate peer-to-peer layer sitting in front of a cloud fallback that's always there if the peer layer comes up empty.

The transport: a private swarm, not a public one#

Peer connections run over Iroh, a QUIC-based P2P library. "Private" isn't marketing language here; it's the actual protocol boundary. Every connection negotiates an ALPN (the protocol identifier QUIC peers use to agree what they're speaking) derived per-org: swarmfile-cidfetch/<hash of org + key + secret>. A peer from a different org, or without the swarm secret, can't negotiate that ALPN at all. There's no public BitTorrent-style DHT anywhere in the engine, and no code path that lets an unrelated machine discover your org's peers even if it wanted to.

Finding peers on the LAN#

On the same network, peers find each other via standard mDNS (the same mechanism Bonjour and AirPlay use), service type _swarmfile._udp.local.. It's event-driven, not a polling loop: the engine subscribes and reacts to advertisements as they arrive, filtering out VPN, tunnel, hypervisor, and bridge interfaces before registering so a Docker bridge or VPN adapter never gets treated as a real LAN. Peers are additionally filtered by a hash of the swarm's own key, so even two Swarmfile installs on the same physical network without the same credentials never merge into one swarm.

Some corporate networks block mDNS multicast outright. There's no error; the peers on that network just never resolve each other. For that case there's lan_from_office: when enabled, it merges hub-discovered peers that share your office_id into the LAN peer list directly, sidestepping multicast entirely. It's live-swappable without a restart, re-evaluated on a 60-second tick, distinct from (and much more frequent than) the 5-minute safety-net used by deliberate shard placement. They're two different subsystems that happen to share the word "LAN," worth not conflating.

The fallback chain on every read#

A block request tries, in order: LAN peers first (never rate-limited: they're free, so there's no reason to throttle them), then same-office peers reached over WAN, then other-office seed nodes, then other-office peers over WAN, with each WAN bucket sorted by measured round-trip time. If every peer in that list fails or comes up empty, the read falls through cleanly to R2, the cloud block store, with no error surfaced up the stack. Peer-to-peer is an optimization layered over a fallback that always works, not a load-bearing single point of failure.

Why "one download" needs no explicit step#

Here's the part that surprised us when we went looking for it in the code: there's no "publish" or "announce" step at all. The function that used to proactively push newly-fetched blocks out to peers is now a no-op, because any encrypted block sitting in a machine's local cache is already servable to a peer that asks for it (cleartext never crosses the peer plane, so a plaintext block is refused by design). The cid-fetch server reads directly out of the same block store the engine itself reads from. The first person in an office to open a file pulls those blocks from the cloud once; the moment they land, any LAN peer that asks for the same block gets it from that machine instead, automatically, with nothing to configure and nothing that has to succeed first.

The same logic applies to a file that's still being uploaded: if the machine asking for a range is on the LAN, it's served straight off the uploader's disk before those bytes have even reached the cloud. Serving that same request over WAN is deliberately avoided: it would mean sending the same bytes twice over the office's single uplink, once to the peer and once to R2, which is strictly worse than just waiting for the cloud copy.

What this doesn't solve#

"One office, one download" only works if some machine in the office actually has the blocks and is awake to serve them. A single editor working alone, or an office where everyone's laptop is closed overnight, gets no peer benefit: every read goes straight to the cloud. That's exactly the gap self-hosted seed nodes close: a machine that's always on, always holds the blocks, and turns "whoever happens to have it" into "something always does."