Skip to main content
No. On the same network the phone dials the host’s own address. From another network, networkMode: "remote" asks the router for an inbound port over NAT-PMP, PCP or UPnP — automatically, with nothing to configure. Where that is impossible (carrier-grade NAT, a network you do not control), a relay carries the connection over outbound sockets only. No. With no services at all, a phone pairs and connects directly to the host over the address in the QR:
There is no signaling service in that path, and none is required: the whole claim / challenge / SAS / complete exchange runs on the host’s own socket. A signaling and relay pair is an addition, for phones that can reach neither the host’s LAN address nor a public one. See Connection modes for the four host modes and Self-hosting to run those services yourself.

What happens when the host goes offline?

The client detects the disconnection and enters reconnect state:
Offline call queueing: idempotent methods are queued and replayed after reconnection.

Route priority

The pairing QR lists every route the host genuinely has, tagged by kind, and the client tries them in this order:
A route appears in the QR only if it exists. A private address is only ever tagged lan; it is never advertised as though it were reachable from the internet. Once connected, WebRTC upgrade can move traffic onto a direct peer-to-peer DataChannel, which matters mainly for relayed sessions.

Network topology support

Same network (LAN)

  • Host binds ws://0.0.0.0:port (with bind: "all")
  • Client discovers host via signaling presence or manual config
  • Lowest latency, no external services
If the host machine is on more than one network at once (Wi-Fi + a wired adapter, two Wi-Fi radios, a VPN, etc.), address auto-detection just grabs the first non-internal interface it finds and may pick one your phone can’t reach. Pin the address explicitly instead:
or set CROSSLINK_LAN_HOST=192.168.1.42 in the environment — no code change needed. The reference PWA’s dev server (apps/demo-pwa) reads the same variable for its QR code.

Cross-network (relay)

  • Host allocates channel on relay
  • Client joins via channel ID
  • Works through CGNAT, firewalls, double-NAT
  • Adds one network hop

Mixed (LAN + relay)

Client automatically uses the best available transport.

NAT traversal

Two independent mechanisms, used for different things: Getting an inbound port (networkMode: "remote") uses NAT-PMP (RFC 6886), PCP (RFC 6887) and UPnP IGD, plus STUN (RFC 5389) to learn the public address. The router’s own report wins over STUN when they disagree, since a VPN changes what STUN sees. Details and limits: Remote access. Getting through a NAT you cannot map uses a relay: both sides make outbound connections and the relay forwards encrypted frames between them. This works through CGNAT, double NAT and restrictive firewalls, at the cost of one hop. The relay only ever sees ciphertext.

Firewall considerations

In production, signaling and relay run behind a reverse proxy on port 443 (WSS mandatory).

Bandwidth

The relay adds overhead for encrypted traffic. Reduce relay usage by upgrading to WebRTC:

Offline behavior

When the host is unreachable:
  • Idempotent RPC calls are queued and replayed after reconnection
  • Non-idempotent calls fail immediately with not_connected
  • Event subscriptions are restored after reconnection
  • Transport hints are persisted locally for faster reconnection