The contract said "stdio, and only stdio" and now describes two transports, so it gets a version -- but **v2.1 and not v3, because nothing breaks**. No tool renamed, no argument reshaped, no resource moved; a client written against v2 over stdio still works unchanged. v2 was a major bump because it *removed* five tools. A point release is what an additive change is. §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
182 lines
7.4 KiB
Markdown
182 lines
7.4 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.
|
|
|
|
## 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** — eight 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.
|
|
- **Tools are the acts** — twenty-one, 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_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-one 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. |