How CRDT Sync Works: Offline-First by Design

What is a CRDT?

A Conflict-free Replicated Data Type (CRDT) is a data structure that can be edited independently on multiple devices and merged automatically without conflicts. Unlike traditional databases that require a central server to resolve edits, CRDTs guarantee that every device converges to the same state regardless of the order updates arrive.

Thumper-Run uses Loro, a high-performance CRDT library written in Rust, as its foundation. The CRDT architecture docs cover the implementation details.

The Offline-First Promise

You should be able to use your AI tools on a plane, in a cabin, or anywhere without internet. Thumper-Run is offline-first: every operation writes to a local CRDT document first. Sync happens later, when connectivity is available. There is no spinner, no "waiting for server," and no data loss if your connection drops mid-session.

How Sync Works

When two devices connect—either directly or through a relay—they exchange CRDT operations. Each operation carries a unique timestamp and device ID. The merge algorithm applies operations in causal order, producing an identical result on both devices.

Current supported relay-assisted sync is server-assisted and uses encrypted transport. CRDT convergence does not itself establish private E2EE, and the relay may handle content or keys needed by the enabled workflow.

Transport and Security Modes

HTTP, WebSocket, direct, relay, and federation transports describe how bytes move. The CRDT security mode separately describes authentication, authorization, and encryption. Availability depends on the product build and configuration; private E2EE modes remain gated. See the platform docs for the current matrix.

Multi-Device Pairing

To authorize supported multi-device workflows, you pair devices using the available enrollment ceremony. Pairing establishes device identity and permissions for that workflow. It does not by itself establish private E2EE; see the E2EE design status for the remaining custody and protocol gates.

Conflict Resolution Example

Imagine you rename a workflow to "Portrait v2" on your laptop while your desktop renames it to "Portrait Final." With a traditional file sync tool, you would get a conflict—two copies of the file with garbled names.

With CRDTs, the merge algorithm applies a deterministic rule: last-writer-wins on scalar fields like names, and union merge on collections like tags. Both devices converge to "Portrait Final" (the later edit) with no manual intervention. The earlier name is preserved in the document history if you ever need to recover it.

Why Not Dropbox?

File-sync tools like Dropbox operate at the file level. If two devices edit the same JSON file, one version wins and the other is lost (or you get a "conflicted copy"). CRDTs operate at the field level—two devices can edit different fields of the same document simultaneously and merge cleanly.

This is especially important for AI workflows, where a single project might include prompts, model references, generation settings, and output metadata all in one document. Field-level merge means you never lose work.

For the full technical dive, read the CRDT concept docs and the sync architecture page.

Ready to try it? Download Thumper-Run free →