> ## Documentation Index
> Fetch the complete documentation index at: https://crosslink.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Connection Modes

> The four network modes a Crosslink host can run in, what each one advertises, and when to use it.

# 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.

```ts theme={null}
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.

```bash theme={null}
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](/guides/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](/guides/remote-access), including the case where your ISP puts
you behind carrier-grade NAT and no amount of software can fix it.

```bash theme={null}
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.