Local-first · OrbitDB · libp2p · IPFS pinning
orbitdb-relay
A long-running pinner and signaling node for OrbitDB and libp2p apps.
Local-first apps keep their working data on user devices and replicate peer to peer. But browser peers sit behind NAT, go offline, and need somewhere durable to keep shared content. orbitdb-relay is that node: it bridges browsers over circuit relay, replicates OrbitDB databases, pins the media they reference in Helia, and serves it back over a small HTTP API.
Current package version: v0.10.1
Data stays with users
Replication is OrbitDB's job
The relay never invents its own replication protocol. OrbitDB owns /orbitdb/heads/*, oplog merges, identities, and access control. The relay is a well-behaved extra peer: it opens the same databases, keeps them open, and lets OrbitDB do the syncing.
How recovery worksInfrastructure on demand
Availability while peers are offline
Real networks still need signaling, bootstrap, and pinning. The relay bridges browser peers over circuit relay v2, pins referenced media in Helia, and keeps shared content reachable through /ipfs/<cid> long after the original writer has closed their tab.
From write to durable content
What the relay does on every sync
The relay learns database addresses from live pubsub activity, opens them, and lets OrbitDB replicate — then pins the media those records point at.
- A browser opens an OrbitDB database and subscribes to its pubsub topic
- The relay discovers the topic and opens the same database
- OrbitDB exchanges log heads; the relay replicates the oplog
- The relay extracts media CIDs and pins them in Helia
- Later peers sync through the relay and fetch pinned content
- POST /pinning/sync recovers a stuck database on demand