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