AI platform · IDE · agents · models
Ask in Clavue Chat

wss://relay.clavue.com/v2/channel

imux-link Relay

imux-link v3 is how the imux desktop and the mobile companion share one workspace. The phone prefers the Mac on the same LAN, then the zero-knowledge relay at wss://relay.clavue.com/v2/channel, then ordinary control-plane HTTP. The relay forwards sealed frames. It does not read them.

Overview

A paired phone is a client of one desktop device, not a second editor with its own files. Both sides speak the same 11-byte frame header whether the socket is local or the public relay. Membership issues a short-lived ticket. The payload key stays on the two peers.

  • Relay: wss://relay.clavue.com/v2/channel
  • Ticket: POST /api/membership/relay/ticket
  • Companion app docs: /docs/imux-mobile
  • Older one-time splice on /link stays compatible with relay-link v1

Three-tier routing

The phone races the routes and keeps the local one when it is up. Tier 1 is same-LAN WebSocket. The Mac advertises _imux-link._tcp over Bonjour and lists RFC1918 candidates in projection.meta.lanEndpoints. Tier 2 is the public relay. Tier 3 is control-plane HTTP (projection, heartbeat, proposal decide) when neither socket is usable. Local wins by a small bias (directBonusMs = 60). The selector does not flap faster than minSwitchCooldownMs = 30000, and a dead socket fails over immediately.

  • Tier 1 — LAN direct, for example ws://192.168.1.42:54321/v2/channel
  • Tier 2 — wss://relay.clavue.com/v2/channel
  • Tier 3 — Control-plane HTTPS on www.clavue.com / api.clavue.com
  • Desktop capability flags include lan_direct_v1 and live_pty_v1

Multiplexed channels Ch0–Ch4

After the JSON hello, binary frames share one socket. The header is 11 bytes: version 0x02, channel 0–4, flags, a big-endian sequence, and a big-endian length (max 1048576), then the opaque payload. Flag 0x01 means the payload is sealed. Flag 0x02 marks a keyframe. Flag 0x04 is ping/pong.

  • Ch0 — ping, pong, RTT. Highest priority. The relay echoes flag 0x04 or forwards it
  • Ch1 — control, approve/deny, keep/drop, terminal keystrokes. Never dropped
  • Ch2 — live PTY. Medium priority. A slow phone drops oldest frames. The latest keyframe is cached
  • Ch3 — imux.progress.v1 and agent events. A 256-frame ring replays seq after lastSeq on reconnect
  • Ch4 — bulk diff, file, and browser screenshot chunks. Yields to Ch0–Ch3. Diff payloads are capped at 48 KiB
Offset  Size  Field
0       1     version (0x02)
1       1     channel (0..4)
2       1     flags (0x01 sealed, 0x02 keyframe, 0x04 ping)
3       4     seq uint32 big-endian
7       4     length uint32 big-endian
11      n     payload

Zero-knowledge E2EE

Each peer sends an X25519 public key in the hello. Payloads with the sealed flag are ChaCha20-Poly1305 between the desktop and the phone. The relay checks the ticket, joins the room, and copies bytes. It does not decrypt. A client that reconnects with lastSeq greater than 0 can replay cached Ch3 frames and the latest Ch2 keyframe. Those cached frames are still sealed.

{
  "v": 2,
  "ticket": "<signedTicket>",
  "pubKey": "<base64-x25519-public-key>",
  "lastSeq": 0
}

Mobile companion pairing

The desktop registers as a device (GET/POST /api/membership/devices) and asks for a host ticket with deviceId plus deviceSecret, or the headers x-imux-device-id and x-imux-device-secret. The phone asks for a client ticket with the membership Bearer token, the same deviceId, and an optional clientId. The ticket names the room uid:did. One host is active. Several clients (phone and tablet) can attach. The relay answers with a ready frame that includes hostOnline and the peer public keys.

# Host (desktop)
curl -s https://api.clavue.com/api/membership/relay/ticket \
  -H "Content-Type: application/json" \
  -d '{"deviceId":"'"$DEVICE_ID"'","deviceSecret":"'"$DEVICE_SECRET"'"}'

# Client (phone)
curl -s https://api.clavue.com/api/membership/relay/ticket \
  -H "Authorization: Bearer $CLAVUE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"deviceId":"'"$DEVICE_ID"'","clientId":"iphone"}'

Security

The ticket is HMAC-SHA256 over a JSON payload (v, uid, did, role, cid, exp) and expires. Losing a phone unpairs that client. It does not reveal PTY bytes to the relay. Do not log deviceSecret. LAN sockets use the same handshake as the public relay, so a guest on the Wi-Fi still needs a ticket or device token. relay.clavue.com is on the exact-hostname SSO return allowlist, with www.clavue.com, chat.clavue.com, api.clavue.com, router.clavue.com, agent.clavue.com, mail.clavue.com, nas.clavue.com, track.clavue.com, and explorer.clavue.com, plus clavue.com, www.iccjk.com, iccjk.com, localhost, and 127.0.0.1. agent.clavue.com and mail.clavue.com are on that list.

Next