`checks.vm-mcp-http` -- the sibling of `vm-mcp`, on the same session machine. That one proves the *surface* over a pipe; this one proves the two things stdio does not have: a unit systemd supervises, and a credential on the way in. So there is one tool call and one resource read here, just enough to show a request reached the broker through an authenticated session, and the weight is on the refusals, the state directory's permissions, and the unit's lifecycle. **The first subtest is the one that justifies the file.** The server exits 2 while the authorization table is empty, which leaves a freshly provisioned machine in a failed state on purpose -- and that trade is only sound because the unit retries, so the first `token mint` brings it up with no `systemctl start`. That self-heal lives in `StartLimitIntervalSec = 0` and nothing in Python can test it. If it regresses, every machine that enables the option comes up dead and stays dead, and this is the only thing that would notice. Also asserted, and each for a reason rather than for coverage: the state directory is 0700 and owned by the account that mints tokens (which is also the proof an operator *can* mint one on a machine configured this way); the table is 0600 and does not contain the token; the port is on loopback and **not** in the firewall, because neither default may become implied; the refusals are 401 with an empty body and no echo; two tokens served by one process see different tool budgets, which is the whole argument for putting toolsets on a token; a revocation takes effect on the next request with no restart, because an operator who must restart a service to lock someone out does not have revocation; and revoking *every* token does not stop the process, since the startup refusal exists to catch a forgotten mint rather than to police a deliberate one. `lib/mcp_http_client.py` is raw JSON-RPC over `urllib` and deliberately not the SDK's client, for the reason `lib/mcp_client.py` is not either -- the SDK on both ends would agree with itself about a framing and a header neither side had to get right, and the header is half of what this file is about. It earned that choice immediately: it is what caught the 307 on the exact path that the SDK-shaped test client had been following silently. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KchcvnbfhhZhUHy83YL3Ya
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.
{
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:
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:
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.
disablethenenablerotates it. - Capture runs only while somebody is connected. An enabled stream nobody
is watching costs no
grimand no CPU. - Watching counts as activity. This is the one exception to "
touchis 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.
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 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://statusis whether the desktop is up,hhstream://sessionsis what is running,hhstream://sessions/<id>/logsis an application's own output,hhstream://pointeris who holds the input lease,hhstream://screenis a frame of the screen,hhstream://streamsis what is being published and who is watching. - Tools are the acts — twenty-three, one per CLI verb that does something.
session_startputs an application on the screen,pointer_acquiretakes the input lease,keyboard_typetypes,session_stream_enablepublishes the screen for a person to watch,session_killends 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:
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:
{
"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:
{ "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:
services.hyprland-headless-stream.mcp.http.enable = true; # 127.0.0.1:9989/mcp
$ 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.
{
"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 that401s every request is almost always a forgotten mint, andsystemctl status hhstream-mcpsays 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.