Protocol reference
The normative phux wire protocol, versioned with phux-protocol.
Full source summary
The normative phux wire protocol, versioned with phux-protocol. Start with the tutorial for one complete connection, then use the framing, workload authentication, L1 terminal, L3 metadata, input, and encoding pages as the source of truth for implementations.
Server sends terminal bytes. Client sends structured input. Both sides run the same terminal engine, so there is no second screen model in the middle.
Files
| File | Owns |
|---|---|
| TUTORIAL.md | Start here: a complete session walkthrough (HELLO → attach → output → input → detach) |
| proto.md | Framing, version negotiation, capabilities, flow control, transport |
| workload-auth.md | Endpoint-neutral phux-workload/v1 proof, canonical endpoint-owned scopes, registry intersection, and live revocation |
| L1.md | Terminal substrate — the REQUIRED conformance tier |
| L2.md | Reserved, unused — no collection tier (dissolved per ADR-0030) |
| L3.md | Metadata storage — OPTIONAL |
| input.md | INPUT_KEY / INPUT_MOUSE / INPUT_FOCUS / INPUT_PASTE / INPUT_RAW |
| appendix-encoding.md | Encoding primitives and the normative payload shape (positional, big-endian, length-prefixed) |
| appendix-reserved.md | Reserved discriminant ranges |
| CHANGELOG.md | Wire-format change log, version-stamped |
Version
The current protocol version lives in crates/phux-protocol/src/
(grep PROTOCOL_VERSION). The top entry in CHANGELOG.md
must match it; CI gate spec-version-sync enforces this.
phux deprecations reference
Deprecated spellings the current binary still accepts, each pinned with its replacement and lifecycle releases; empty when nothing is currently deprecated.
Protocol 101: a complete session walkthrough
One phux session traced end to end, from HELLO to detach: what each step does, the wire frames it sends, and why the design lands where it does.