Skip to content

Run a relay ​

A relay introduces peers and federates with the others. It carries signaling only, so it needs little: a free Cloudflare account, or a machine at home.

On Cloudflare, in a few minutes ​

Deploy to Cloudflare

The button creates the Worker and its D1 database in your Cloudflare account, applies the database migrations, makes the relay's identity and keeps it as an encrypted Worker secret (never printed), and deploys it to <worker>.<account>.workers.dev. Right after, the relay joins the overlay through its seed relays. No custom domain is needed.

From a terminal instead:

bash
npm install freertc
npx freertc            # the setup wizard: Wrangler config, D1, identity, deploy

Seed relays are ordinary Wrangler variables, for example "KADEMLIA_BOOTSTRAP_URLS": "wss://peer.ooo/ws,wss://decentralize.ooo/ws". A relay with no seeds simply runs on its own.

On your own machine ​

bash
git clone https://github.com/draeder/freertc && cd freertc && npm install
node scripts/node-relay.mjs

It listens on port 8788 (ws://<host>:8788/ws) and federates with the cloud relays by default. Behind NAT it takes a public address through a tunnel to a public relay, and browsers reach it over a punched WebRTC connection. PeerPigeon peers prefer a healthy local relay over a cloud one.

Its own name and certificate ​

A local relay can have a name on your domain and a Let's Encrypt certificate, so browsers anywhere reach it as wss://<name>:8443/ws:

bash
npx freertc name --domain example.com

Your FreeRTC Worker keeps the name and the only DNS token; the relay asks it. From then on the relay points <first 16 characters of its id>.example.com at your public address, renews its certificate, and asks your router to forward port 8443.

For tests ​

bash
FREERTC_FEDERATION=off node scripts/node-relay.mjs

With federation off, nothing reaches the public relays. Use it for tests with many peers (wurl is made for them): every peer's signaling counts against a public relay's daily limits.

Settings ​

Variable
FREERTC_FEDERATION=offA relay on its own, for tests
FREERTC_NAMES=offNo name or certificate
FREERTC_IDP=offDon't keep PigeonIdP account records
FREERTC_TLS_PORTThe wss:// port with a name (default 8443)
RELAY_CAPACITYHow many peers it takes (Worker variable)

peer.ooo · peer to peer on PeerPigeon