Introduction

Crosslink is a framework for securely connecting a web or mobile interface to an application running on another device. Any app on your computer can talk to any app on your phone or browser over an end-to-end encrypted channel — paired once by scanning a QR code, then reconnected automatically forever after.

What problem does it solve?

Every app reinvents device pairing: ad-hoc tokens, hand-copied keys, homegrown crypto, brittle sockets. Crosslink packages the hard parts once: Open-source developers also hit a distribution wall when a desktop project needs a mobile companion. Native iOS and Android apps bring store publishing fees, signing and review requirements, duplicated platform code, and sometimes proprietary licensing. Crosslink lets those projects ship an installable browser or PWA companion with a $0 app-store publishing fee, while keeping the host and companion open source.

Concern	What Crosslink gives you
Pairing	Single-use 9-digit code + QR; SAS verification words; fingerprint pinning
Identity	One Ed25519 key per installation; revocation lists persisted locally
Crypto	X25519 + HKDF handshake (“CLX1”), XChaCha20-Poly1305 session frames
Authorization	Capability grants per device, host-authored policy, per-use consent
RPC	Typed request/response, streaming progress chunks, event subscriptions
Transports	LAN WebSocket -> crosslink relay -> WebRTC DataChannel, auto-fallback
Reconnect	Exponential backoff, offline call queueing, subscription restore
Secrets	Host seed in the OS keychain; browser seed under a non-extractable WebCrypto key
Observability	Structured, redacting `Logger` threaded through every layer
Pairing UI	A drop-in pairing card: QR, code, expiry, device list, revocation
Mobile onboarding	First-pair, SAS, Add to Home Screen, Continue in Browser
PWA infrastructure	Generated manifest, service worker, icons, and the browser SDK, served for you
Offline experience	A cached Crosslink shell that opens and reconnects when your desktop is off

What you build, and what Crosslink builds

Crosslink is batteries-included on purpose. You do not write a pairing screen, a QR, an install flow, a service worker or a reconnect page — those are the framework’s, and they look and behave the same in every Crosslink application.

Crosslink owns	You own
Pairing card, QR, 9-digit code	Your desktop application UI
Mobile pairing, code entry, SAS	Your mobile application UI
Add to Home Screen, Continue in Browser	Your RPC methods and business logic
Manifest, service worker, icons, SDK delivery	Your app name, icon and colours
Offline, reconnecting and revoked screens
The Crosslink mark and attribution

A complete mobile integration is one config field and one callback:

createCrosslinkServer({
  application: { id: "com.example.notes", name: "Notes", accentColor: "#f97316" },
  mobile: { entry: "./mobile/index.html" }
});

crosslink.onConnected((rpc) => renderNotes(rpc));

When should I use Crosslink?

You have an app on a desktop/server and want a phone to control it
You need a phone-as-remote pattern (remote desktop, presentation control, media remote)
You want to let users pair devices without accounts, OAuth, or cloud sync
You need encrypted RPC between processes on different devices
You’re building an Electron/Tauri app that needs a companion mobile interface

Real-world use cases

Use case	Host	Client
Media remote	Desktop music player	Phone browser
Presentation control	Desktop slideshow	Phone browser
Remote terminal	Server CLI	Phone browser
Smart home	Home server	Any device
File transfer	Desktop app	Phone browser
Device dashboard	IoT device	Phone browser
Game second screen	Desktop game	Phone browser

Architecture overview

User scans QR
      |
Crosslink landing page
      |
Add to Home Screen (optional)
      |
Crosslink PWA / Client
      |
Encrypted connection (E2E)
      |
Desktop / Server application (Host)

In more detail:

+-----------------+   LAN / WebRTC / relay    +----------------+
|  App A (host)   | <== E2E encrypted ======> | App B (phone)  |
|  Node.js SDK    |      CLX1 sessions        | Browser SDK    |
+-----------------+                            +----------------+
        ^                ^      ^
        +-- signaling ----+      +-- relay (dumb pipe) --------+

The signaling service helps devices find each other and route pairing codes. The relay forwards encrypted traffic when a direct connection isn’t possible. Both services see zero plaintext.

What the services do

Service	Purpose	Sees traffic?	Required?
Signaling	Presence directory + pairing-code router	Hashed codes + opaque blobs only	Only for cross-network pairing
Relay	Encrypted pipe for NAT traversal	Ciphertext only (cannot decrypt)	Only for cross-network connectivity
LAN	Direct WebSocket on local network	N/A (no service)	Same-network only

Security architecture

Client
   |
   | encrypted (XChaCha20-Poly1305)
   v
Signaling / Relay (untrusted)
   |
   | encrypted
   v
Host

Services are untrusted by design:

Signaling sees only hashed codes and opaque signed blobs
Relay sees only ciphertext
Compromising either cannot forge, decrypt, or substitute identities

Crosslink provides the transport and authentication primitives. Your application is responsible for:

Validating input at the RPC layer (schema validation)
Rate limiting at the application level
Logging security-relevant events
Implementing proper error handling
Following the principle of least privilege in capability design

Key properties

No accounts required — devices pair by scanning a QR code
End-to-end encrypted — the relay and signaling servers never see your data
Forward secrecy — every session uses fresh ephemeral keys
Capability-based permissions — granular access control per device
Transport agnostic — works over LAN, relay, or WebRTC with automatic fallback
Cross-platform — Node.js, browsers, Electron, Tauri

How it differs from alternatives

Alternative	Limitation	Crosslink advantage
REST API + API keys	Keys must be shared somehow	QR pairing, no shared secrets
OAuth	Requires accounts + cloud	No accounts, fully local
SSH tunneling	Complex setup, not user-friendly	Scan QR, done
WebSocket manually	No encryption, no auth	Full E2E encryption + auth
TURN/STUN	Requires infrastructure	Self-hostable, LAN fallback

Packages

Package	Purpose	Install
`@crosslink/sdk-node`	Host SDK for Node.js	`npm install @crosslink/sdk-node`
`@crosslink/sdk-browser`	Client SDK for browsers	`npm install @crosslink/sdk-browser`
`@crosslink/core`	Core engine (crypto, sessions, RPC)	`npm install @crosslink/core`
`@crosslink/protocol`	Wire protocol specification	`npm install @crosslink/protocol`
`@crosslink/webrtc-adapter`	WebRTC DataChannel transport	`npm install @crosslink/webrtc-adapter`
`@crosslink/react`	React bindings (hooks + provider) over the browser SDK	`npm install @crosslink/react`

Next steps

Quickstart

Get a working connection in under 5 minutes

Architecture

Understand how the pieces fit together

Security

Crypto choices, threat model, and security invariants

Self-Hosting

Deploy your own signaling and relay

GET STARTED

BUILD

CONCEPTS

CLIENT

CONNECTIONS

SECURITY

GUIDES

REFERENCE

RESOURCES

What problem does it solve?

What you build, and what Crosslink builds

When should I use Crosslink?

Real-world use cases

Architecture overview

What the services do

Security architecture

Key properties

How it differs from alternatives

Packages

Next steps

Quickstart

Architecture

Security

Self-Hosting

​What problem does it solve?

​What you build, and what Crosslink builds

​When should I use Crosslink?

​Real-world use cases

​Architecture overview

​What the services do

​Security architecture

​Key properties

​How it differs from alternatives

​Packages

​Next steps

Quickstart

Architecture

Security

Self-Hosting

What problem does it solve?

What you build, and what Crosslink builds

When should I use Crosslink?

Real-world use cases

Architecture overview

What the services do

Security architecture

Key properties

How it differs from alternatives

Packages

Next steps