Local-first documents that sync peer to peer

What is Swarmbase?

Swarmbase is a set of composable TypeScript libraries that let you build applications where documents live on user devices and sync directly between peers — encrypted, signed, and content-addressed. There is no application database server. Relays carry ciphertext without seeing plaintext.

Encrypted by default

By default, every change is signed with ECDSA P-384 and encrypted with AES-GCM before it leaves the device. Relays and remote stores see only opaque ciphertext. (Signing can be configured via enableSigning.)

No application database server

Helia and libp2p provide storage and peer-to-peer transport. You run relay nodes for NAT traversal — no Postgres, no Redis, no application backend.

CRDT adapters

Use Yjs or Automerge documents. Replicas converge after valid updates are delivered, without a central consensus service. Battle-tested merge semantics with Swarmbase’s security model.

Composable, not monolithic

Six libraries — use only what you need. Core (collabswarm), CRDT adapters (Yjs, Automerge), UI bindings (React, Redux), and client-side indexing.

A Yjs document in a few lines

Once a Swarmbase node is configured with the Yjs adapter, documents feel like familiar CRDT shared types wrapped in encryption and access control:

import { Collabswarm, SubtleCrypto, defaultConfig,
  defaultBootstrapConfig } from '@swarmbase/collabswarm';
import { YjsProvider, YjsACLProvider,
  YjsKeychainProvider, YjsJSONSerializer } from '@swarmbase/collabswarm-yjs';

// The application must supply an ECDSA P-384 key pair:
const userKeyPair = await crypto.subtle.generateKey(
  { name: 'ECDSA', namedCurve: 'P-384' },
  true,
  ['sign', 'verify'],
) as CryptoKeyPair;

const swarm = new Collabswarm(
  userKeyPair.privateKey,
  userKeyPair.publicKey,
  new YjsProvider(),
  new YjsJSONSerializer(),
  new YjsJSONSerializer(),
  new YjsJSONSerializer(),
  new SubtleCrypto(),
  new YjsACLProvider(),
  new YjsKeychainProvider(),
);
await swarm.initialize(defaultConfig(defaultBootstrapConfig([])));

// Optionally connect to bootstrap peers:
// await swarm.connect(['/dns4/relay.example.com/tcp/443/wss/p2p/12D3...']);

const todos = swarm.doc('/todo-list');
await todos.open();

todos.subscribe('ui', (state) => {
  render(state.getArray<string>('items').toArray());
});

await todos.change((state) => {
  state.getArray<string>('items').push(['Ship it']);
});

The repository contains runnable examples that show provider setup, identity creation, and connecting peers. See the quick start to run them locally.

Illustrative encrypted Yjs sync

Try edits on either in-page replica, disconnect them, and reconnect to merge the queued Yjs updates. The simulation boundary and omitted Swarmbase subsystems are listed directly below the demo.

This simulation needs JavaScript and the Web Crypto API. See therunnable repository examples instead.

Initializing simulation…

Illustrative simulation: this runs real Yjs delta/merge via Swarmbase’s YjsProvider and uses its SubtleCryptohelper for AES‑GCM encryption and ECDSA P‑384 signatures. It is not protocol-equivalent to Swarmbase networking and does not exerciseCollabswarmDocument, ACL or key onboarding, Helia or a blockstore, libp2p or GossipSub, or any real transport. See therunnable examples for full application setups.

How it works

1. Edit locally. A provider applies each change to the local CRDT replica. The application sees changes immediately — no network round-trip.
2. Sign, encrypt, publish. Swarmbase signs the sync message with the writer’s ECDSA P-384 key, encrypts the serialized envelope with the document’s AES-GCM key, and publishes the CID to connected peers via GossipSub.
3. Verify and merge. Recipients fetch the encrypted block, verify the signature, decrypt the payload, and apply the CRDT update. The Yjs or Automerge layer reconciles concurrent edits without conflicts.

Swarmbase currently verifies encrypted document retrieval across a Circuit Relay boundary in CI. Broader partition/rejoin, persistence, and production deployment coverage remains active work.

Key design choices

Choice	Rationale
End-to-end encryption	Document plaintext never touches a server. AES-GCM content encryption, ECDSA P-384 signing.
Content-addressed storage	Every block is addressed by its SHA-256 hash (CID). Blocks are immutable — no overwrites, no conflicts.
Shadow sync graph	Changes form a DAG, not a linear history. Concurrent edits coexist; the CRDT layer resolves them.
CRDT-agnostic core	Swarmbase wraps Yjs and Automerge without coupling to either. Swap CRDT implementations without changing your application.
libp2p networking	Battle-tested peer-to-peer stack: WebSockets, WebRTC, WebTransport, Circuit Relay v2, GossipSub.
K-of-Q quorum loading	Before trusting a document state, verify it with K-of-Q bootstrap peers. Prevents loading a fork.
BeeKEM key sharing	Dynamic group key encapsulation. Add and remove readers without re-encrypting the document.

See the architecture page for detailed diagrams of the data flow, networking stack, and encryption model.

How Swarmbase compares

Tool	Use case	Server role
Swarmbase	Encrypted peer-to-peer CRDT documents	Self-hosted relay/bootstrap; document payloads end-to-end encrypted
Yjs	High-performance CRDT runtime	Bring or configure a sync provider
Automerge	JSON-like CRDT documents	Configure Repo storage/network adapters
Liveblocks	Real-time presence + collaboration	Managed backend service
RxDB	Local-first NoSQL database	Flexible replication to many backends
Jazz	Local-first relational database	Managed or self-hosted sync server
Electric Sync	Sync Postgres data to clients	Postgres read-path sync engine

Swarmbase is designed for end-to-end encrypted documents that sync through self-hosted relay infrastructure without exposing document plaintext. Relays can still observe connection and traffic metadata. See the full comparisons for detailed trade-offs against each project.

Built in the open

Swarmbase is young enough that careful bug reports, API feedback, documentation, and unusual network tests can materially shape the project.

Run the examples

Start with the browser applications and inspect the matching Playwright acceptance tests.

Read the docs

Understand the architecture, learn the concepts, and try the cookbook recipes.

Join the conversation

Browse open issues or ask a question in GitHub Discussions.

Contribute

Check the roadmap, the help wanted list, and the contributing guide.

Quick start

Why Swarmbase?

Architecture