Skip to main content

What is orbitdb-relay?

orbitdb-relay is a long-running pinner and signaling node for apps built on OrbitDB, Helia, and libp2p. It is the durable, internet-reachable peer that a local-first, peer-to-peer app leans on when its browser peers cannot reach each other on their own.

It does four things:

  1. Signaling & bridging — runs a libp2p circuit relay v2 server plus pubsub peer discovery, so browser peers behind NAT can find and dial each other.
  2. Replication — opens the same OrbitDB databases your app uses and lets OrbitDB's native sync protocol replicate the oplog into the relay.
  3. Pinning — extracts media CIDs (for example imageCid) from replicated records and pins them in its Helia/IPFS blockstore, so content survives after the original writer goes offline.
  4. HTTP surface — exposes /health, /multiaddrs, /pinning/*, /ipfs/<cid>, and a Prometheus /metrics endpoint from a small built-in HTTP server.

When you need a relay​

You reach for orbitdb-relay when the "everyone is a peer" model breaks down in practice:

  • Browser peers are behind NAT. Two browsers usually cannot dial each other directly. A publicly dialable relay gives them a rendezvous point and a circuit to connect through.
  • Peers go offline. In a purely peer-to-peer app, data that only lives in one person's browser disappears when they close the tab. A relay keeps a replicated copy and pins the referenced media.
  • You want durable media. OrbitDB replicates the oplog; the images and files it references live in IPFS. The relay pins those CIDs so later peers can fetch them.
  • You need an operational contract. Peer-to-peer replication is eventually consistent with no delivery deadline. The relay adds a bounded, observable POST /pinning/sync recovery path and a health/metrics surface you can monitor.

What it is not​

  • Not a reimplementation of OrbitDB replication. The relay does replicate — but it does so as an ordinary OrbitDB peer, using OrbitDB's own protocol. Heads exchange, oplog merges, identities, signatures and access control all stay with OrbitDB; the relay adds availability, not a second replication mechanism. See Peer recovery for the boundaries it respects.
  • Not a central database. The peer directory holds discovery metadata only — no application entries — and is lost on restart.
  • Not an authenticated gateway, and not pinned-only by default. /ipfs/<cid> is unauthenticated, and the default fallbackMode is pinned-first-network-fallback: content the relay has not pinned is fetched from the public IPFS network and served. Anyone who can reach the HTTP port can therefore pull arbitrary CIDs through the relay. Restrict it to trusted networks, put an authenticating proxy in front, or run the library with pinningHttp.fallbackMode: 'pinned-only' so it serves only what it has pinned.

How it fits in a local-first stack​

The relay is deliberately optional and replaceable. An app can run entirely peer to peer and only start (or point at) a relay when a team needs help connecting or keeping shared data available.

Where to go next​