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

# Links

> Encrypted connections between devices

## What is a link?

A link is an established encrypted connection between a host and a client. It represents the active session over which RPC calls and events flow.

## Link lifecycle

```text theme={null}
1. Pairing     -- QR scan, identity exchange, SAS verification
2. Connection  -- X25519 key exchange, session key derivation
3. Active      -- RPC calls, events, streaming
4. Disconnect  -- Graceful shutdown or network loss
5. Reconnect   -- Automatic reconnection with backoff
```

## Link states

| State                   | Description                                          |
| ----------------------- | ---------------------------------------------------- |
| `offline`               | Not connected, no active session                     |
| `discovering`           | Looking for the host                                 |
| `pairing`               | Pairing in progress                                  |
| `connecting`            | Establishing connection                              |
| `direct`                | Active session over LAN or WebRTC, RPC available     |
| `turn-relayed`          | Active session over a TURN relay, RPC available      |
| `crosslink-relayed`     | Active session over the relay service, RPC available |
| `reconnecting`          | Lost connection, attempting to restore               |
| `unauthorized`          | Host rejected this device                            |
| `revoked`               | Device access was revoked                            |
| `protocol-incompatible` | Host/client protocol versions don't match            |

## Creating a link

### From host perspective

```js theme={null}
// Server automatically manages links
const server = createCrosslinkServer({ /* ... */ });

// Listen for connections
server.typedOn("deviceConnected", ({ deviceId, transport }) => {
  console.log(`Client ${deviceId} connected via ${transport}`);
});

// List paired devices
const devices = server.listDevices();
```

### From client perspective

```js theme={null}
const client = await CrosslinkClient.create({ /* ... */ });

// Pair and connect
await client.pairFromQr(uri, ["app.control"]);
const rpc = await client.connect(["app.control"]);

// Monitor connection state
client.onStateChange((state) => {
  console.log("State:", state);
});
```

## Multiple links

A host can maintain multiple simultaneous links:

```text theme={null}
Host
├── Link 1: Client A (phone) -- WebSocket
├── Link 2: Client B (tablet) -- WebRTC
└── Link 3: Client C (laptop) -- relay
```

Each link has its own:

* Encryption keys
* Granted capabilities
* Sequence counters
* Connection state

## Link persistence

Links persist across network interruptions:

* The session key remains valid
* Reconnection uses exponential backoff
* RPC calls queue during disconnection
* Subscriptions restore automatically

## Security per link

Each link has independent security:

* Unique session key (forward secrecy)
* Independent capability grants
* Separate sequence counters
* Isolated error handling

## Link events

| Event          | Description                  |
| -------------- | ---------------------------- |
| `connected`    | Link established             |
| `disconnected` | Link closed                  |
| `error`        | Link error occurred          |
| `reconnecting` | Reconnection attempt started |
| `reconnected`  | Reconnection successful      |