Build with Freehop
Gates introduce peers. Media stays inside the session.
Freehop is a JavaScript SDK with bundled TypeScript declarations for adding peer-to-peer audio, video and data to browser and desktop apps: small meeting rooms, calls inside existing tools, shared workspaces, communities and games. Keep your own UI, room flow and account system; Freehop supplies the connection and media controls. Its initial target is small rooms of 2 to 8 people; that is a starting target, not a measured hardware limit. Gates never carry media. If you run a session host or gateway on infrastructure you pay for, its media bandwidth and compute can still appear on your bill.
Freehop is alpha software. Its developer-built home-lab setup passed 40 of 40 simulated-network runs across three browser engines on 2 October 2026. Release checks for alpha.6 on 10 October passed 208 unit tests, local browser suites and TypeScript consumer checks; every lab scenario last ran once more with Chromium for alpha.5 on 9 October, and the three-engine, three-trial matrix has not been rerun. This was not an independent lab evaluation or a test on real internet connections. Freehop has not yet been verified on physical home routers, 4G/5G carrier networks, corporate networks or mobile browsers. See Limits before you depend on it.
Choose your starting point
- TypeScript: typed sessions, events and backend APIs from the npm package.
- Use cases: recipes for meeting rooms, embedded calls, shared workspaces, desktop tools and communities.
- Browser games: Three.js worlds with a voice/video overlay and small shared events.
- Electron: the same client, plus a desktop participant’s gateway.
- Build with AI: a scoped build brief for your coding agent, or a checklist for your own implementation.
- Demos: Hopper and a live call with connection inspection, with source you can inspect.
Freehop supplies connections and media controls. Your app supplies its interface, accounts, persistence and any AI services.
The one rule
By default, a byte of media only crosses machines that belong to the call: the two people talking, another participant, or the machine that hosts the session. The one exception is a TURN relay your app opts into as a last resort. A session host or gateway you operate can carry media and incur costs; signalling gates never carry media.
Classic WebRTC deployments fall back to a TURN relay that the operator rents. Every relayed minute of every call flows through that relay, and the operator pays for the bandwidth. By default Freehop does without that fallback and uses routes that stay inside the session:
| Step | Path | What carries the media |
|---|---|---|
| 1 | direct | Nothing in between: LAN, IPv6, or addresses discovered with STUN |
| 2 | gateway | A desktop participant's own gateway, reachable through their router's port mapping |
| 3 | relay | The gateway of another session member, such as the session's host node |
| 4 | bridged | Another participant, who forwards the media because it is in the call anyway |
| unreachable | Nothing: an honest status when no route exists inside the session |
Applications that want one more chance can opt into two last resorts before unreachable: port prediction for NATs that hand out ports in order, and their own TURN relay. Both are off by default; a relay you add carries only the calls that would otherwise fail, and its bandwidth is yours.
The paths and escalation page explains when each step is tried and how long it gets.
What you run
| Piece | Runs on | Job |
|---|---|---|
| Authority | Your backend | Decides who is in a room and hands each member a ticket |
| Gate | Any server, any number of them | Passes sealed envelopes between peers that announce the same room tag |
| Client | Every browser or desktop renderer | Joins with the ticket, negotiates media and climbs the path ladder |
| Desktop gateway (optional) | A participant's desktop app | Opens the participant's own front door: TURN plus a router port mapping |
| Host node (optional) | The machine that hosts the session | Joins without media and offers its gateway to the session |
A gate carries tens of kilobytes per call setup and almost nothing afterwards, because signalling moves onto the peers' own data channels once they are connected. Clients use every gate in their ticket, peers on different gates still meet through each other, and calls keep running when every gate goes down. A gate can even be a public WebTorrent tracker (bt+wss://…), so a room can run with no server of your own at all. The live call on this site works that way.
The network profiles
The documentation follows the same people through every page, so you can compare their paths:
| Person | Network | Simulated test profile |
|---|---|---|
| Ana | Home Wi-Fi behind an ordinary home router | eim |
| Ben | A phone hotspot behind a carrier NAT that picks a new random port for every destination (a symmetric NAT) | random |
| Kai | Another phone hotspot with the same kind of NAT as Ben | random |
| Cleo | A fibre line with a public address | public |
| Dani | The desktop app, behind a home router that supports UPnP, PCP or NAT-PMP | upnp |
| Omar | An office network that blocks all UDP | udpblock |
| Ivy | A network with IPv6, where IPv4 UDP is blocked | v6 |
| Gus | A guest network that only lets traffic through to the gate's host | gateonly |
The test-profile column names the Linux kernel NAT profile used to simulate each network in Freehop's home-lab network tests. Physical carrier networks, offices and guest networks are not part of that evidence.
Status
The browser client has zero runtime dependencies. The gate uses ws; the gateway uses Node.js built-ins. All 15 public entry points include TypeScript declarations. Hopper and the live call are working examples; the use-case recipes show how to adapt the SDK to your app.
Where to go next
- Quickstart: the five pieces of an integration, with code.
- Examples: try Hopper or inspect a real call in the live demo.
- Gates: what a gate is, and what it can and cannot see.
- Paths and escalation: how a pair of peers finds its route, with an interactive path finder.
- Cost model: where bandwidth and compute costs fall.
- Live call: a real call in your browser, introduced by public trackers only.