Files
hyprland-headless-stream-pl…/README.md
T
HermenixandClaude Opus 5 f83717ba71 Merge feat/mcp-server (9708154) into feat/mcp-auth
The base branch moved twelve commits while this work was in flight --
including the per-session live stream and its own contract bump -- so this
integrates rather than leaving a PR nobody can merge.  Six files
conflicted; the interesting resolutions are the two that were not
textual.

**The contract is mcp-v3.1, not v2.1.**  This branch bumped v2 -> v2.1 for
an additive change; `feat/mcp-server` bumped v2 -> v3 for the live stream,
also additive.  Both point releases, both correct, and they cannot both be
the same document.  So v3 stands as written and the HTTP transport is the
point release on top of it, by the same rule each of us applied
independently: v2 is still the only major bump, because it is still the
only one that removed anything.

**The counts are no longer literals.**  This branch asserted `21 tools` and
`5 resources` in `checks/vm-mcp-http.nix` and `5` in `test_mcp_http.py`;
the stream added two tools and one fixed resource, so the surface is 23
and 6.  Rather than re-hardcode numbers that will go stale again, the
check now counts against `--list-tools` and `--list-resources` -- the
server's own table -- and the unit test against `resources.FIXED`.  That
is the lesson 9708154 ("count the unnarrowed resources against the
listing, not a literal") had already learned on the other side of this
merge, arrived at twice.  A stale number here would have failed in a way
indistinguishable from the HTTP transport dropping tools, which is the
one thing those subtests exist to catch.

The rest were additive on both sides and both halves are kept: the TODO
table, the checks wiring, the README check rows, the architecture diagram
(their 23/10 counts with this branch's two-transport annotation).
`nix/module.nix` needed reconstructing -- git interleaved the bodies of
`hhstream-live` and `hhstream-mcp` because both units land between the
same surrounding lines -- so the live unit is taken verbatim and the MCP
unit placed after it, with this branch's options, tmpfiles entry,
firewall rule, two assertions and two warnings re-applied on top.

One thing deliberately NOT touched: the v3 change table cites `§6` for the
idle-clock exception, but the rule it means is `§8`. That is the other
branch's prose and its author's call, not something to quietly rewrite in
a merge.

Verified after resolution: 394 unit tests pass, and the module evaluates
with both units, the right ExecStart, one firewall port and both
warnings.

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

230 lines
9.6 KiB
Markdown

# hyprland-headless-stream-plugin
A Nix flake that runs a **headless Hyprland session** and publishes its frames on
a **persistent Unix socket**, so any process that can open a socket can see the
screen without owning a display.
Two parts:
- **NixOS module** — `services.hyprland-headless-stream`: starts Hyprland with
no physical monitor, and a small frame server beside it.
- **Package** — `hhstream` — the frame server (publishes frames) and its client
(reads them). Pure Python standard library.
```nix
{
inputs.hhstream.url = "git+https://<host>/git/<owner>/hyprland-headless-stream-plugin.git";
# in your host config
imports = [ inputs.hhstream.nixosModules.default ];
services.hyprland-headless-stream = {
enable = true;
# Optional: the default is one 1280x720@30 rule with an empty name, which
# is Hyprland's wildcard and applies to whatever outputs the GPU has.
outputs = [ { width = 1920; height = 1080; refresh = 60; } ];
};
}
```
Then any consumer:
```bash
hhstream-client --socket /run/hypr-stream/stream.sock --count 1 --out frame.png
```
The socket is a plain file descriptor: the server serves every client that
connects, and keeps running when one disconnects.
## Watching a session: one port, a phrase per session
A session can publish its own screen on a web page, so a person can watch what
an agent is doing from a phone. One port for the whole machine, and a path that
is four words and a short tail:
```bash
hhstream session stream enable chromium-k3f9d2
# http://127.0.0.1:9988/amber-otter-lantern-harbor-7k2qp/
```
That URL is the whole interface — a browser `<img>` is the entire client, over
MJPEG — and the phrase in it is its **only** protection. No TLS, no second
factor: anyone who can reach the port and guess four words can watch. It is
never written to the audit log, and `stream list` does not print it.
Four things worth knowing before switching one on:
- **It is per session and off by default.** A session does not stream because
it exists; it streams because somebody enabled it. What is published is that
session's own container output, never the main one — the main output carries
every other session, and putting it behind one session's phrase is the
mistake this refuses to make.
- **The phrase survives a restart.** It lives in the session's record, so
somebody you read it out to keeps the URL you gave them. `disable` then
`enable` rotates it.
- **Capture runs only while somebody is connected.** An enabled stream nobody
is watching costs no `grim` and no CPU.
- **Watching counts as activity.** This is the one exception to "`touch` is the
only mark of activity": about once a minute the broker notices a connected
viewer and resets that session's idle clock, so a long job you are watching
on a phone is not reaped at three hours. An enabled stream with nobody
watching keeps nothing alive.
```nix
services.hyprland-headless-stream.sessions.stream = {
enable = true; # runs hhstream-live; turns no stream on
# bind = "0.0.0.0"; # and openFirewall, to reach it from another device
# openFirewall = true;
};
```
Loopback by default, where the path to a phone is `ssh -L 9988:127.0.0.1:9988`.
`hhstream session start <app> --stream` starts an application and prints its
URL in one go, which is the usual way an agent sets one up.
## Driving it from an agent: the MCP server
`hhstream-mcp` is the `hhstream` CLI behind a [Model Context
Protocol](https://modelcontextprotocol.io) surface, so an agent can look at this
desktop, put an application on it, and aim its one pointer and keyboard at that
application without writing command lines. The interface is frozen in
`docs/CONTRACT-mcp.md`.
It is split the way the protocol splits things:
- **Resources are the state** — ten of them, read by URI, and reading one
changes nothing. `hhstream://status` is whether the desktop is up,
`hhstream://sessions` is what is running, `hhstream://sessions/<id>/logs` is
an application's own output, `hhstream://pointer` is who holds the input
lease, `hhstream://screen` is a frame of the screen, `hhstream://streams` is
what is being published and who is watching.
- **Tools are the acts** — twenty-three, one per CLI verb that does something.
`session_start` puts an application on the screen, `pointer_acquire` takes the
input lease, `keyboard_type` types, `session_stream_enable` publishes the
screen for a person to watch, `session_kill` ends a session.
A host decides what state to put in front of its model; the model decides what
to do. That is the whole of the split, and it is why `shot` is still a tool
(capturing is an act at a moment) while `hhstream://screen` exists beside it.
It is a thin wrapper and nothing more: every tool and every resource builds the
argv list the CLI's own parser takes, runs the CLI's own handler, and maps what
came back. The idle clock, the pointer lease, the allowlist and the exit-code
table all stay where they were.
Install it with the module — off by default, because it is the surface through
which a language model starts processes on this machine:
```nix
services.hyprland-headless-stream = {
enable = true;
sessions.enable = true; # the session, pointer and keyboard tools need the broker
mcp.enable = true; # puts `hhstream-mcp` on the system PATH
};
```
Then register it with a client. The default transport is **stdio** — one
process per client, spawned by the client, no port and no daemon — so the whole
configuration is a command and an environment:
```json
{
"mcpServers": {
"hhstream": {
"command": "hhstream-mcp",
"env": {
"HHSTREAM_SOCKET": "/run/hhstream/control.sock",
"HHSTREAM_FRAME_SOCKET": "/run/hypr-stream/stream.sock"
}
}
}
}
```
Both variables are the CLI's own and both are shown at their defaults, so they
can be left out unless this machine moved a socket. The account the client runs
as needs what the CLI needs: membership of the compositor's group (`hhstream`)
to read the frame socket, and of the broker's to reach the control socket. The
server cannot recover that for itself the way the CLI does — see
`docs/CONTRACT-mcp.md` §5 — so if `shot` reports it cannot read the socket, the
answer is `"command": "sg", "args": ["hhstream", "-c", "hhstream-mcp"]` or an
account in the group.
`hhstream-mcp --list-tools` and `--list-resources` print the two tables and
exit, which is the quickest way to check an install.
If twenty-three tools is more than a client has room for, `--toolsets` narrows
what is offered to whichever families are wanted — `frames`, `sessions`,
`pointer`, `keyboard`:
```json
{ "command": "hhstream-mcp", "args": ["--toolsets", "frames,pointer,keyboard"] }
```
Resources are deliberately *not* narrowed by it: they are the host's context,
not the model's tool budget. The server holds no state and caches no lease, and
the pointer lease is an explicit argument on every gesture tool for exactly that
reason.
### Over a port instead, for a client that cannot spawn a process
`mcp.http.enable` serves the same surface over Streamable HTTP, as a unit,
behind a bearer token:
```nix
services.hyprland-headless-stream.mcp.http.enable = true; # 127.0.0.1:9989/mcp
```
```console
$ sudo -u hermes hhstream-mcp token mint --label laptop --expires-in 90d
hhsmcp_…
minted a7k2qp (laptop), expires 2026-01-09T12:00:00Z, toolsets all.
This is the only time the token is shown.
```
```json
{
"mcpServers": {
"hhstream": {
"url": "http://127.0.0.1:9989/mcp",
"headers": { "Authorization": "Bearer hhsmcp_…" }
}
}
}
```
**stdio stays unauthenticated and that is not an oversight.** A stdio client
spawns the server, so it has already passed a filesystem permission check and
holds the broker's socket either way — a token there would be a lock whose key
is in the same pocket. A port is the first time the caller is someone who did
neither, which is the entire reason the token exists. The two options are
independent; neither implies the other.
Three things worth knowing before enabling it:
- **The unit refuses to start until a token exists**, and retries every five
seconds, so it comes up on its own moments after the first `token mint`. A
listener that `401`s every request is almost always a forgotten mint, and
`systemctl status hhstream-mcp` says so in as many words.
- **There is no TLS.** The token crosses the wire in clear text. Loopback is the
default and an SSH tunnel is the simplest way to reach it from elsewhere; a
LAN bind wants a reverse proxy, and the module warns about it.
- **It is not MCP's OAuth profile.** A client that can only discover an
authorization server will not connect; one that lets you set a header will.
See `docs/TODO/mcp-http-auth-is-not-oauth.md`.
`token list` shows the ids, labels and last use; `token revoke <id>` takes
effect on the next request with no restart. A token can carry its own
`--toolsets`, which is the only way to give two clients different tool budgets
from one process — though it narrows tools and *not* resources, which is
`docs/TODO/mcp-tokens-do-not-scope-resources.md`.
| Document | What it is |
|---|---|
| `docs/CONTRACT.md` | the wire protocol and the module surface — the interface other people build against |
| `docs/CONTRACT-sessions.md` | the broker, the containers and the input lease |
| `docs/CONTRACT-mcp.md` | the MCP surface: the resource URIs, the tool names, their arguments and the error mapping |
| `docs/ARCHITECTURE.md` | how the pieces fit: compositor, capture, server, client |
| `README.dev.md` | how to build, test and hack on it |
| `examples/README.md` | the demo that films the screen: `agent-eyes-demo.py` |
Status: work in progress — the module and the test suite are being built.