Local-first software, explained with one family and two phones

Local-first software keeps the primary copy of your data on your own devices and treats the network as a way to sync, not as the place your data lives. It should work offline, sync across your devices, let people collaborate, keep working if the company behind it disappears, and keep your data private and under your control.

This post explains the idea with one family and two phones, maps it to the ideals from the essay that named it, and shows where Havenfold stands against each one, including what it has not solved yet. Havenfold is pre-alpha: do not use it for real data.

Where the term comes from

"Local-first software" was named in a 2019 essay by Martin Kleppmann, Adam Wiggins, Peter van Hardenberg and Mark McGranaghan of the research lab Ink & Switch, titled "Local-first software: You own your data, in spite of the cloud". Their argument was that cloud apps made collaboration easy but took ownership away: your documents live on someone else's server, and if the service changes or closes, your work goes with it.

They set out ideals that local-first software should meet:

• Fast: actions respond without waiting for a server.
• Multi-device: data syncs across a person's devices.
• Offline: you can read and write without a network.
• Collaboration: several people can work on the same data.
• Longevity: data stays usable even if the vendor stops operating.
• Privacy: end-to-end encryption protects the data.
• User control: the vendor cannot restrict how you access or use your data.

One family, two phones

Picture Alex and Maya, the two example phones in Havenfold's demo, sharing a family notebook: the Wi-Fi password, a dentist appointment, the boiler's service date.

In a typical cloud app, Alex's note goes to a company's server first, and Maya's phone fetches it from there. If the server is down, or the company closes, or Alex's account is locked, the note is out of reach, even though it was typed on Alex's own phone.

In a local-first design, Alex's note is written to Alex's phone first. It is then sent, encrypted, to Maya's phone directly or through a helper that cannot read it. If both phones are offline, each still has the notebook as it last saw it. When they reconnect, their changes merge, and both end up with the same notebook without anyone choosing which version wins by hand.

The hard part is that last step. When two devices change the same data while apart, they need a rule for combining changes that gives the same result on every device, whatever order the changes arrive in.

How Havenfold maps to the ideals

Havenfold turns the devices a family or a small business already owns into their own end-to-end encrypted cloud, with no accounts and no centre. Its principles say it directly: "data stays in place, the cloud is an optional accelerator". Here is how it lines up with each ideal, honestly.

• Fast and offline: Shared data lives in collections on each device. Each change is an encrypted, signed operation, and devices merge operations field by field and reach the same state in any order.
• Multi-device: The project's demo starts two phones as separate processes running the real core, with no accounts, and shows a note written on Alex's phone appearing on Maya's phone. The demo runs on a local test network on one machine; nothing leaves that machine.
• Collaboration: Who may read and write a collection is recorded in the family's signed membership record. When someone leaves, a new key epoch starts and their later writes are excluded.
• Longevity: A family can keep a spare machine on as a Family Box. In the demo, Alex's phone and Maya's phone are both switched off at different moments, and Maya's phone gets the note from the box when it comes back. Havenfold's principles also promise no lock-in and export in an open format, and the repository includes a tool that opens an export container without installing Havenfold.
• Privacy: Content is end-to-end encrypted; the box holds sealed copies it cannot read. It still sees traffic metadata, and the project says so.
• User control: There are no accounts; identity lives on the device. The core is open source, and the project commits that the code will not move to a more restrictive licence.

What is not solved yet

Local-first is a direction, not a checkbox, and Havenfold is early on it:

• Pre-alpha: do not use it for real data. Formats may change before the first tagged release.
• Network between real homes: phone-to-phone and phone-to-box networking exists, but on phones it is still behind an experimental flag. The README describes "a first two-phone trial in a product app"; testing across real home networks is still missing.
• Offline delivery routes: the Hold and Mailbox routes, which let a device pick up messages sent while it was offline, are listed as missing in the status table, and the Mailbox is not in the repository yet.
• Real use: Havenfold has not yet run in a real home, and there has been no independent security audit.

Summary

• Local-first software keeps the primary copy of data on your devices and uses the network to sync.
• The term comes from Ink & Switch's 2019 essay, which set out ideals: fast, multi-device, offline, collaboration, longevity, privacy and user control.
• The hard part is merging changes made apart so that every device ends with the same result.
• Havenfold merges signed, encrypted operations field by field, uses a Family Box to bridge devices that are offline, and has no accounts.
• It is pre-alpha: phone networking is experimental, some offline routes are missing, and it is not for real data yet.