Electron

The runnable examples/electron-chat app is the reference integration. It keeps Crosslink in Electron’s main process and gives the sandboxed renderer narrow IPC operations for status, pairing sessions/mode changes, messages, revocation, and pairing lifecycle events. A custom PairingSource adapts that bridge to the same createPairingCard() used by HTTP-hosted desktop pages; the example does not implement its own QR, code, refresh, or invalidation UI.

npm install
npm run dev -w @crosslink/example-electron-chat

Crosslink connect widget with a QR code and short pairing code

Process boundary

Process	Holds	Must not hold
Main	Crosslink host, identity, grants, relay tokens, approval UI	Remote renderer code
Preload	Narrow validated IPC wrappers and event subscriptions	Raw `ipcRenderer`
Renderer	Display state and user input	Node.js, filesystem, keys, service tokens

The example uses contextIsolation: true, sandbox: true, nodeIntegration: false, webSecurity: true, a restrictive CSP, denied permissions, denied navigation/windows, and exact IPC sender validation. Its UI loads through a registered secure custom protocol rather than file://.

Host configuration

const host = createCrosslinkServer({
  application: { id: "com.example.app", name: "My Electron App" },
  storageDir: path.join(app.getPath("userData"), "crosslink"),
  capabilities: [
    { id: "app.read", title: "Read app data", risk: "low" },
    { id: "app.change", title: "Change app data", risk: "medium" }
  ],
  lan: { enabled: true, bind: "all" },
  networkMode: "lan-and-relay",
  signalingUrl: process.env.CROSSLINK_SIGNALING_URL,
  relayUrl: process.env.CROSSLINK_RELAY_URL,
  signalingToken: process.env.CROSSLINK_SIGNALING_TOKEN,
  relayToken: process.env.CROSSLINK_RELAY_TOKEN,
  security: {
    hybridPq: "preferred",
    maxDevices: 12,
    maxActivePairingSessions: 2,
    pairingRateLimitMs: 5_000
  },
  pairing: {
    autoApprove: false,
    notifyApprovalRequest: (request) => showNativeNotification(request),
    approve: (request) => showNativeApprovalDialog(request)
  }
});

Crosslink probes Electron safeStorage after app.whenReady() and stores only its encrypted ciphertext under userData. If OS encryption is unavailable it uses the encrypted-file backend; it never silently selects plaintext.

Reachable from any network

Use authenticated HTTPS signaling and relay endpoints for predictable remote reachability:

CROSSLINK_NETWORK_MODE=lan-and-relay \
CROSSLINK_SIGNALING_URL=https://signal.example.com \
CROSSLINK_RELAY_URL=https://relay.example.com \
CROSSLINK_SIGNALING_TOKEN='from-your-secret-manager' \
CROSSLINK_RELAY_TOKEN='from-your-secret-manager' \
npm run dev -w @crosslink/example-electron-chat

The example refuses non-HTTPS service URLs. For a direct router mapping, set CROSSLINK_NETWORK_MODE=remote; startup fails if it cannot establish a real remote route. Never expose a renderer HTTP control panel on 0.0.0.0; only the encrypted Crosslink transport should bind to the LAN/public interface.

Package installers

npm run dist -w @crosslink/example-electron-chat

electron-builder produces macOS, Windows, or Linux artifacts on the matching host OS. Production releases still need your platform signing identity, notarization, and update-signing configuration.

Do not enable autoApprove in a distributed app. A notification is advisory; only the local approval callback can authorize the pairing.

GET STARTED

BUILD

CONCEPTS

CLIENT

CONNECTIONS

SECURITY

GUIDES

REFERENCE

RESOURCES

Process boundary

Host configuration

Reachable from any network

Package installers

​Process boundary

​Host configuration

​Reachable from any network

​Package installers

Process boundary

Host configuration

Reachable from any network

Package installers