Files
HermenixandClaude Opus 5 10176356b6 docs(mcp)!: mcp-v4, a second transport, and what its token is not
The contract said "stdio, and only stdio" and now describes two
transports, so it gets a version -- **v4**, because v3 (the live stream)
was published to main while this branch was in review.  Nothing here
breaks: no tool renamed, no argument reshaped, no resource moved, so a
client written against v2 over stdio still works unchanged.  v2 is the
only bump that took something away, and it took away five tools; v3 and
v4 are additive.

§1 is rewritten around the asymmetry rather than around the feature,
because the asymmetry is the part that is easy to get wrong later: stdio
is unauthenticated **on purpose** and that is now written down with its
argument, so the next reader does not "fix" it.  A stdio client spawns
the server, so it has already passed a filesystem permission check and
holds the broker's 0660 control socket either way -- unix permissions are
the gate, exactly as `mcp.enable`'s own option text has always said.  A
port is the first time the caller passed neither, which is the entire
reason the token exists.

§2 gains `HHSTREAM_MCP_STATE_DIR` (and why it is NOT `sessions.stateDir`:
that directory is 0700 owned by the broker's user and holds the audit
trail), the `serve --http` flags, and the `token` verbs with the three
decisions behind them -- digests not tokens, wall-clock expiry where
every broker deadline is BOOTTIME, and a flock because two processes
write the table.  §3 records that a token's toolsets intersect the
server's and cannot widen them.

§10 is new and is the part worth having: **what this is not.**  Not OAuth
2.1, not RFC 9728, no metadata discovery -- so a client that can only
*discover* an authorization server will not connect, and one that lets
you set a header will.  And a token narrows tools but not resources, so a
`frames` token can still read `hhstream://sessions`.  Both are now TODO
files with their own evidence and recommended routes, beside the two
limits the SDK imposes:

* `mcp-http-auth-is-not-oauth.md` -- medium, and the severity is about
  interoperability rather than exposure.  Nothing is weaker than it
  claims; what is missing is the part that lets a client somebody else
  configured connect without a human pasting a header.  It records that
  `ssh host hhstream-mcp` is genuinely the better answer for one operator
  with one machine, because that is what this competes with.
* `mcp-tokens-do-not-scope-resources.md` -- medium, and nothing at all
  until a second token is minted for someone else, at which point the
  restriction is narrower than it reads.

README gains the HTTP section with the three things to know before
enabling it (the unit's refusal and self-heal, no TLS, not OAuth);
README.dev gains the token commands in the dev-shell walkthrough and the
new check's row; ARCHITECTURE gains the two transports in its diagram and
the reason the shim has a state directory while owning no state about the
desktop.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KchcvnbfhhZhUHy83YL3Ya
2026-10-12 18:00:05 +00:00

13 KiB

Architecture

                     ┌──────────────────────────────────────────┐
                     │ hyprland-headless.service                │
                     │   Hyprland 0.56.2, no physical monitor   │
                     │   private XDG_RUNTIME_DIR, as `user`     │
                     │   outputs come from `outputs[]`          │
                     │   + one headless output per session      │
                     └───┬───────────┬───────────────┬──────────┘
                         │           │               │
       IPC: request /    │           │ Wayland       │ Wayland
       event sockets     │           │ session       │ (virtual pointer)
                         │           ▼               │
                         │  ┌────────────────────────┴─────────┐
                         │  │ hyprland-headless-stream.service │
                         │  │   hhstream-server                │
                         │  │     capture ──▶ one frame slot   │
                         │  │     accept  ──▶ thread per client│
                         │  └───────────────┬──────────────────┘
                         │                  │ AF_UNIX, mode 0660
                         │                  ▼
                         │   many clients ── hhstream-client / any reader
                         │
            ┌────────────┴──────────────┐      ┌──────────────────────────┐
            │ hhstream-sessions.service │─────▶│ hhstream-pointer.service │
            │   hhstreamd               │      │   one Wayland connection │
            │   registry, containers,   │ JSON │   one virtual pointer    │
            │   the pointer lease,      │ over │   per output             │
            │   the stream phrases      │ a    └──────────────────────────┘
            └────────────┬────────┬─────┘ private socket
                         │        │              ┌──────────────────────────┐
                         │        └─────────────▶│ hhstream-live.service    │
                         │     live.sock         │   one port (9988)        │
                         │                       │   grim ─▶ MJPEG per      │
                         │                       │   phrase, while watched  │
                         │                       └───────────┬──────────────┘
                         │                                   │ HTTP
                         │                         a browser ┘ /<phrase>/
                         │ AF_UNIX control.sock, mode 0660
                         ▼
                   hhstream session ...  (the CLI an agent drives)
                         ▲
                         │ in-process: argv in, exit code out
                         │
            ┌────────────┴──────────────┐
            │ hhstream-mcp              │  stdio: spawned per client
            │   23 tools  (the acts)    │◀─── an MCP client's JSON-RPC
            │   10 resources (the state)│  http: one unit, one port,
            └───────────────────────────┘        a bearer token per request

Six pieces, deliberately separate, and a seventh that is deliberately not a piece at all:

  1. The compositor (Hyprland, unchanged upstream) renders into virtual outputs. It knows nothing about frames on a socket.

  2. The frame server (hhstream) captures, holds exactly one frame, and publishes it. It owns the socket, the framing and the drop policy.

  3. The client is any process that can open a Unix socket and read the contract's byte format. The shipped hhstream-client is a convenience, not a requirement.

  4. The session broker (hhstreamd) starts allowlisted applications as tracked sessions, gives each one its own headless output and workspace (a container), reads the compositor back over its own IPC, and owns the pointer lease. It is the only part that keeps state across a restart.

  5. The pointer driver (hhstream-pointer) is a Wayland client of the same session that creates one zwlr_virtual_pointer_v1 per output. It holds no lease and no session state: the broker decides, the driver executes. It is a separate process because a Wayland client needs its own connection and a driver blocked on the compositor must not stall session lifecycle.

  6. The stream daemon (hhstream-live) publishes one session's output as MJPEG on one port, behind a four-word phrase, while somebody is connected. A third executor on the pointer driver's pattern and for its reasons: grim blocks tens to hundreds of milliseconds so it must not run where touch and kill are answered, and a LAN-facing HTTP parser must not run in the frame server whose one-socket contract cannot grow one. The broker owns the decision (which session, under which phrase, in the record); the daemon owns the port, the capture and the URL. It knows nothing about sessions or idle clocks — it publishes what it is told to publish, and reports a viewer count the broker chooses to read as activity.

And the seventh, which is a shim and not a layer:

  1. The MCP server (hhstream-mcp, docs/CONTRACT-mcp.md) is the CLI with a Model Context Protocol surface on it, so an agent reads state by URI and acts by calling tools instead of writing command lines. It is drawn above the CLI rather than beside the broker because that is where it sits: every tool and every resource builds the argv list the CLI's parser takes and runs the CLI's own handler in the same process, and it is the one component here that owns no state at all — not even the pointer lease, which is an explicit argument on every gesture tool. Add it to the diagram's list of things that can go wrong and nothing new appears: every failure it reports is the CLI's or the broker's, carrying their exit code.

    The split between its two halves is who decides, not what it costs. A resource is the host's to include (hhstream://sessions is state anyone may want in context); a tool is the model's to call (session_kill is a decision). That is why shot is both — a tool because deciding to look is an act, and hhstream://screen because a frame is also just state.

    It is also the only part with a third-party dependency (the mcp SDK), which is why it is a separate derivation (nix/mcp.nix) and why packages.hhstream — the compositor's own units — keeps the closure it had.

    It is the only component with two transports, and the only one that authenticates anything. Over stdio it does not, because there is nothing there to authenticate: the client spawns the process, so it has already passed a filesystem permission check and holds the 0660 control socket either way — unix permissions are the gate, and a token checked by a process the caller started guards a lock whose key is in the same pocket. Over HTTP (mcp.http.enable) it is a unit on a port, the caller passed no such check, and a bearer token is then the only gate there is. That asymmetry is the whole of why the credential exists, and it is also why this shim has a state directory of its own (mcp.stateDir) while owning no state about the desktop: the authorization table is about callers, not about sessions, and it has no business in the broker's 0700 directory beside the audit trail.

Why containers are outputs

A session's container is a headless output, not just a workspace, and the two consequences are the reason:

  • grim -o hh-<id> captures exactly one session, so one agent's screenshot cannot contain another's window;
  • zwlr_virtual_pointer_manager_v1 version 2 creates a pointer bound to an output, so a warp to (0.5, 0.5) is the middle of that session's screen and not the middle of the desktop. Version 1 is refused rather than used, because its coordinates are global and every click would land somewhere plausible and wrong.

The cursor itself is singular — there is one seat — so pointer access is serialised by a broker-wide lease: one holder, a TTL the broker enforces with its own sweeper, and buttons lifted on release or expiry. The lease disciplines these sessions; it does not enforce against a hostile client, which can create its own virtual pointer (that is what sandboxing, not the lease, would fix).

Why one frame, not a queue

The server keeps a single slot holding the most recent frame. Each client thread sends whatever is in that slot when it is ready. A client that cannot keep up therefore misses frames instead of forcing the server to buffer them: memory use does not grow with the number of stalled clients, and a stalled client cannot delay the others. See docs/CONTRACT.md for exactly what a client observes.

Capture

Capturing is a separate program (by default grim, a wlr-screencopy client) run inside the compositor's session and pointed at stdout. That choice is what keeps hhstream free of Wayland and GPU code — the awkward part lives in a tool that already exists and is already tested — and it is why the capture command is a module option: tests inject a fake, and a future backend (a native screencopy client, a hardware encoder) is a command-line swap rather than a rewrite.

The hardware requirement, stated plainly

Hyprland 0.56.2 asks aquamarine for its headless backend as mandatory (src/Compositor.cpp) and does not accept the DRM backend if it is unavailable. Aquamarine's headless backend still needs an EGL/GBM render node; there is no software-only path that works without one. Consequently a host with no graphics device at all (/dev/dri missing) cannot run this, and Pyprland fails with CBackend::create() failed! before any of its managers come up.

So the requirements are:

  • a render node, i.e. /dev/dri/renderD* — from a real GPU, a virtual GPU (virtio-gpu, virtio-gpu-gl, QXL) or a NixOS test VM's own QEMU display;
  • the video/render groups for whichever user runs it (the module sets them).

Testing, and what each layer proves

Layer Proves
tests/unit the framing, the capture wrapper and the server's client handling, with no compositor and no GPU
checks.vm-basic the module actually starts both units, the socket appears with the right owner/mode, the Hello parses and two frames arrive — with a fake capture program
checks.vm-hyprland the real thing: headless Hyprland comes up in the VM and grim captures a frame of the configured size
checks.vm-sessions the session broker side: a real application runs as a tracked session on the compositor, the compositor's IPC sees its window, the idle reaper fires for real (and does not fire when the session is touched), and a broker restart adopts its sessions back
checks.vm-ipc both IPC sockets exist at the names the contract freezes and fit in sun_path; hyprctl answers; and a subscriber on the event socket receives an openwindow for a window the test creates — the one assertion that can tell a working event socket from a silently truncated one
checks.vm-containers one hh-* output per session at the container mode, the application's window on it, a second window of the same application beside the first, an unmatched window quarantined instead of landing on whoever had focus, grim -o isolating one container, and teardown removing the output and releasing its workspace slot
checks.vm-pointer the driver binds a version-2 virtual pointer; acquire warps into the container and restores from the bookmark; a click arrives at the application, which reports the coordinates it was delivered at; a second acquire is BUSY naming the holder; an expired lease is swept and its held button lifted; a broker restart leaves the lock free, the bookmark intact and the driver reachable

The three session checks share one guest (checks/lib/session-machine.nix) and one set of test-script helpers (checks/lib/session-prelude.nix); the helpers contain no assertions, so each check's script is still a complete account of what it proves.

vm-hyprland is the only check that can fail for reasons outside this repo, so it is kept separate from vm-basic on purpose: when it fails, the compositor's log is the answer and the other two layers are already known good.

Run the VM checks one at a time. Each boots a guest with a software-rendered compositor; two at once on a two-core machine make the timing-sensitive assertions flake, and a flaky green is worth less than a slow one.