Connection Modes

A Crosslink host decides how a phone can reach it. There is nothing to configure to make that work on the same Wi-Fi, and nothing to sign up for to make it work from another network: no ngrok token, no Cloudflare account, no port forwarding, no DNS, no public IP to look up. The mode is a host-side setting, because only the host can open a socket or ask a router for a port. It is not something the browser can switch.

const server = createCrosslinkServer({
  application: { id: "com.example.app", name: "My App", version: "1.0.0" },
  networkMode: "auto",           // the default
  lan: { enabled: true, bind: "all" }
});

The four modes

Mode	What the host advertises	Use it when
`auto` (default)	Its own address on this network, plus any signaling/relay you configured	You want the thing to work with no decisions
`local-only`	Its own address on this network, and nothing else	The host must never be reachable off the local network
`lan-and-relay`	This network, plus a signaling/relay service	Phones may be on other networks and you run (or point at) a relay
`remote`	This network, plus a public address with a confirmed router mapping	A phone on cellular or another Wi-Fi must reach the host directly

What ends up in the QR

The pairing QR carries a list of routes rather than a single URL, tagged by kind, in the order the client should try them:

crosslink://pair?v=2
  &e=lan~ws://192.168.1.83:54676,wan~ws://203.0.113.9:54676
  &c=754524531
  &a=com.crosslink.chat
  &n=Crosslink+Chat
  &f=110ed6212454f46f

The client tries each in turn and uses the first that answers. That is why a scan works on the sofa and still works on cellular without you choosing anything. Two rules the host holds to, and which you can rely on:

A private address is never advertised as a public one. A 192.168.x.x, 10.x.x.x or 172.16.x.x address is only ever tagged lan. It is never dressed up as a wan route.
A route is only listed if it exists. A wan endpoint appears only after a router mapping actually succeeded. If networkMode: "remote" cannot produce one, getPairingCode() throws with the reason instead of quietly handing back a LAN-only QR.

`auto`

The default. The host listens on every interface and advertises that address. If you also passed signalingUrl/relayUrl, those are advertised too. Pairing runs over whichever route answers — including straight to the host, with no service in the middle at all.

`local-only`

Same as auto, minus anything brokered: no signaling, no relay, no dev-time service discovery. The QR contains exactly one route, on this network. Use it when reaching the host from elsewhere would be a defect, not a feature.

`lan-and-relay`

Adds a signaling and relay service, for phones that can reach neither the host’s LAN address nor a public one. The relay forwards ciphertext; it cannot read or alter your data, and it is not a trust anchor.

npm run stack   # signaling on :8081, relay on :8082
CROSSLINK_SIGNALING_URL=http://127.0.0.1:8081 \
CROSSLINK_RELAY_URL=http://127.0.0.1:8082 \
npm run dev -w @crosslink/demo-chat

See Self-hosting to run these somewhere durable.

`remote`

Asks the router for an inbound port using NAT-PMP, PCP or UPnP — whichever the router speaks — and advertises the resulting public address as a wan route. This is the mode that makes a QR scanned at home keep working from a coffee shop. It also has real preconditions, which are covered in Remote access, including the case where your ISP puts you behind carrier-grade NAT and no amount of software can fix it.

CROSSLINK_NETWORK_MODE=remote npm run dev -w @crosslink/demo-chat
# or, in an app:
#   networkMode: "remote"

remote implies bind: "all" — a mapping to a loopback-only listener would map nothing — and it fails loudly rather than falling back.

GET STARTED

BUILD

CONCEPTS

CLIENT

CONNECTIONS

SECURITY

GUIDES

REFERENCE

RESOURCES

Connection Modes

Connection Modes

The four modes

What ends up in the QR

`auto`

`local-only`

`lan-and-relay`

`remote`

​Connection Modes

​The four modes

​What ends up in the QR

​auto

​local-only

​lan-and-relay

​remote

Connection Modes

The four modes

What ends up in the QR

`auto`

`local-only`

`lan-and-relay`

`remote`