How the Protocol Works

Documentation / Contents - CyThrough

• Overview of CyThrough
  • What It Is
  • What It Is Not
  • The Three Programs
  • In This Book
• Setting Up
  • What You Need
  • Build and Install
  • Setup With the GUI
  • Setup Without the GUI
  • Lab Auth File
  • Hardware Display Attach
  • Check That It Works
  • Common Mistakes
• Using CyThrough
  • Connect and Catalog
  • Launch and Running
  • Materialize On Desktop
  • Published Apps Menu
  • Quality and Encryption
  • Stopping Apps and the Daemon
• Command Line
  • cythrough Viewer
  • cythroughd Daemon
  • cythrough-prefs Launcher
  • Password and Knock Order
  • Environment
• How the Protocol Works
  • Framing
  • Channels
  • HELLO and Auth
  • Catalog and Launch
  • Pixels and Input
  • Capabilities and Codecs
  • Manager and Backend
• Keys and Shortcuts
• Files and Paths
  • Client Conf
  • Daemon Conf
  • Catalog Cache
  • Desktop Launchers
• Copyright

How the Protocol Works

CyThrough's viewer wire is a framed TCP stream after AUTH. It is not VNC and not the old CyBeam Windows agent. Magic byte 'T' (0x54) rejects a leftover CyBeam agent on the same port at the first byte.

Design detail lives in the tree as docs/protocol.md. This card is the operator view: enough to understand logs, caps, and why setup choices matter.

Framing

Every message:

+0  u8   magic     0x54 'T'
+1  u8   version   1
+2  u8   channel
+3  u8   type
+4  u32  length    payload bytes following (big-endian)

Multi-byte fields are always big-endian. Pixel payloads follow the negotiated pixel_order; they are not wire integers.

Channels

• 1 control -- HELLO, auth, catalog, launch, ping, bye, session stop
• 2 window -- create, map, configure, close
• 3 pixels -- FRAME_BEGIN / TILE / FRAME_END / PAINT_ACK
• 4 input -- key, button, motion, wheel
• 5 clipboard -- reserved
• 6 audio -- reserved

HELLO and Auth

Client sends HELLO with protocol major/minor, pixel layout, tile size, codec list, caps, optional desk size, optional app_id, quality, glyph cache. Server answers HELLO_ACK with the intersection (client codec order preserved).

If CY_CAP_AUTH is negotiated, the server sends AUTH_CHALLENGE. The client replies AUTH_RESPONSE with password bytes (not a digest). AUTH_OK or AUTH_DENIED follows. ATTACH binds the session. An optional app_id from HELLO is launched only after AUTH_OK + ATTACH -- never before auth.

Crypto (when enabled) wraps the session after knock/AUTH. --no-crypto turns SPA and AEAD off entirely; identity auth still runs. --no-knock keeps AEAD but skips the UDP SPA door knock.

Catalog and Launch

• APP_REQUEST / APP_ITEM / APP_END -- publish catalog
• APP_LAUNCH / APP_LAUNCHED -- start one published id
• APP_KILL / APP_KILLED -- stop one app
• WIN_LIST_* / WIN_ACTIVATE -- window list helpers
• SESSION_STOP -- tear down owned apps for the user
• CATALOG_CHANGED -- server notifies; client may APP_REQUEST again

--list-apps on the viewer is AUTH + catalog without opening a display session. --watch-catalog stays connected for CATALOG_CHANGED.

Pixels and Input

The server encodes damage tiles (not full frames by default). Codecs include CACHE_REF, COPYRECT, SOLID, LZ4, PAL8, RAW, QOI, QOI_LZ4, XOR_LZ4, HEXTILE, GLYPHS, and related helpers. The viewer decodes and blits (MIT-SHM when available; --noshm forces the slow path).

Input channel forwards keys, buttons, motion, and wheel to the published app. Remoted apps keep their own accelerators; the viewer has no Motif chrome of its own.

Capabilities and Codecs

Capability bits advertise optional features (input window id, window close, auth, applist, winlist, OR atomic paint, draw ack, crypto). Peers intersect. Missing optional HELLO fields read as zero so short HELOs stay valid.

Quality modes (auto / smooth / fast / fastest) bias encoder choices on the wire without changing the frame header layout.

Manager and Backend

On the daemon host, a manager process owns knock, AUTH, and catalog. A backend child owns the X seat (dummy Xvfb or --hw display) and pushes pixels. Fd handoff and the Running registry are local to the daemon; they are not the viewer TCP document. Dummy Xvfb dirs under /tmp are adopted or reaped across daemon restarts so orphans do not sit on init forever.