Limits
If no route works within the session, Freehop reports unreachable.
Freehop is alpha software. Its network tests ran in a developer-built home-lab setup with simulated NATs; they are not independent or real-world network testing. This page lists what it cannot do by design, the browser quirks it works around, and what has not been verified yet. Read it before you depend on Freehop.
Limits by design
Networks that only reach the gate
Gus is on a guest network that lets traffic through to the gate's host and to nothing else. Envelopes reach the gate, so Gus can be introduced, but there is no machine in the session his media could travel to. Carrying it through the gate would mean the operator carries media, which is exactly what Freehop rules out. Freehop reports such pairs as unreachable (home-lab test scenario gate-only).
A separately configured session gateway, or your own TURN relay (the opt-in turn option), can help only if the network permits a route to its media transport. Running it on the gate’s host does not by itself bypass firewall rules. Its owner supplies the media bandwidth; the gate remains signalling-only.
Two hard networks and nobody else
Two browser-only participants who are both behind hard NATs or UDP-blocking networks, with no IPv6, no gateway in the session and no third participant, cannot connect (home-lab test scenario hard-pair). Any one of these changes that: a desktop participant with a reachable gateway, a host node, or a third participant who reaches both and can forward.
The home lab confirms two more pairs that stay unreachable without help: a home router against a strict NAT (eim-random), and a UDP-blocked browser against a home router (udpblock-eim). Two opt-in last resorts change that before unreachable is reported. Your own TURN relay (turn) connected two strict NATs and two UDP-blocked peers in the lab (hard-pair-turn, udpblock-pair-turn); its bandwidth is yours. Firefox through that relay is work in progress: in the relay-only browser test it gets no audio in one direction, also on alpha.5. Port prediction (portPrediction) targets NATs that hand out ports in order; it never fires for random NATs and is not yet verified on real networks, so it stays off by default.
When a pair is unreachable, Freehop keeps retrying with ICE restarts after 30, 60, 120 and 240 seconds, then every 300 seconds, at almost no cost to the gate. Show your users an honest message, such as "voice unavailable on this network", rather than silence.
Small rooms
Rooms are a full mesh with an initial target of 2 to 8 participants. Eight came from the original product target, not a benchmark establishing the largest reliable room. Every participant sends its media to every other participant, so upstream grows with the room: at five participants with video, each one sends about 4 × 332 kbit/s before overhead.
limits.maxPeers defaults to 8 remote peers per client, so the client limit alone allows a nine-person mesh. It is a local resource limit, not room admission control: excess peers are ignored without a "room full" event, and larger rooms can form an incomplete mesh. Enforce your product's room-size limit in the backend before issuing tickets; createAuthority() does not enforce it for you. The browser-only live demo has no backend and recommends rooms of up to 8 people.
More people do not increase capacity as they would in a file-sharing swarm. The trackers introduce peers; they never carry media. A host node provides a TURN gateway for pairs that need it, preserving their encrypted traffic. It does not turn the mesh into an SFU where each participant uploads one stream for redistribution. Larger voice-only rooms need separate load testing before changing the limit.
There are no capacity benchmarks for 32, 64 or 128 participants yet. Raising maxPeers also requires checking the gate’s membership limit and the client’s discovery bounds; it does not by itself establish support for a larger room. Room population and the number of simultaneous camera streams are separate capacity decisions.
Trust and privacy
- IP addresses. Direct paths expose network addresses to other participants. Gate and tracker operators see connecting IP addresses too. Freehop does not offer an IP-anonymity mode.
- Members trust each other for signalling. All members share one room key, so any member can forge envelopes in the room's name. Removing someone always requires a key rotation.
- Gateway credentials. A gateway relays only between people in its own session, so its credentials cannot be used to reach other internet hosts. Inside the session, a member can use its share of the gateway's quota until the credentials expire or the room rotates.
Forwarding
Bridged media is decoded and re-encoded by the forwarding participant, which costs CPU and some quality. Forwarded video is capped at 200 kbit/s.
Practicalities
- Freehop is alpha software. Install the current npm alpha with
npm install freehop@alpha. - Host nodes need a runtime with a global
WebSocket(Node.js 22 or newer) and at least one Freehop gate (wss://) in their tickets; they do not use tracker gates. - Public WebTorrent trackers are third-party services. When you use them as gates, their availability is outside your control; list more than one.
Gateway recovery
Gateway availability is assessed at startup. Automatic recovery after a router mapping disappears or the external address changes is still pending, as is reclaiming permanent UPnP mappings left after a crash. See the architecture for the gateway model and its limits.
Browser quirks Freehop works around
- Chromium and simultaneous ICE restarts. In home-lab browser tests, simultaneous restarts (glare) intermittently left the polite side's senders silent after its restart offer was rolled back. Freehop lets only one side restart.
- WebKit and TURN URLs. Playwright 1.62's WebKit build rejects
?transport=in TURN URLs (WebKit bug 320931). The client detects this and falls back to UDP-only TURN URLs for that engine.
Not yet verified
The following environments and workloads remain unverified:
- Physical networks: real home routers, 4G and 5G carrier NAT (usually with IPv6), a UDP-blocking corporate network, and routers without UPnP, PCP or NAT-PMP.
- Application performance under load: CPU, rendering and responsiveness while calls run alongside a meeting UI, shared workspace or game.
- iOS Safari and Android browsers. Only desktop engines were tested.
- Media quality under real load, including how much upload a forwarding participant on home broadband can spare.
- Port prediction on real networks: carrier NATs that hand out ports in order. The Linux lab cannot simulate them.
The network test results list exactly what has been verified.
Next
Freehop comes with no warranty. Read the license and disclaimer.