HermenixandClaude Opus 5 f4485f7a63 feat(mcp)!: a second transport, and the token it exists for
`hhstream-mcp serve --http` serves the surface over Streamable HTTP behind
a bearer token, and `hhstream-mcp token mint|list|revoke|prune` issues
those tokens.  stdio stays the default and stays unauthenticated.

The two are one feature, because neither works alone.  A token checked by
a process the caller spawned is a lock whose key is in the same pocket:
over stdio the client starts the server and already holds the broker's
0660 control socket, which is why `mcp.enable`'s own option text says it
"grants no access the `hhstream` CLI does not already grant".  A port is
the first time the caller is someone who passed no filesystem check on
the way in, and that is the moment a credential starts meaning something.
So the transport arrives with the credential, and the contract's "stdio,
and only stdio" is rewritten rather than quietly broken.

The store (`authorizations.py`) keeps SHA-256 digests, not tokens:
nothing ever needs the secret back, so `authorizations.json` is not
itself a credential.  No salt and no KDF -- a token is 256 bits of
`secrets`, so there is no dictionary to attack and a work factor would
only slow the request path.  Expiry is wall clock, the one place in this
project where that is right: every broker deadline is CLOCK_BOOTTIME so
an idle window survives an NTP step, but "valid for thirty days" is a
calendar statement that has to outlive a reboot.  Every read-modify-write
takes a flock, because two processes write this file -- the server
stamping `last_used` and an operator running `token mint` -- and the
atomic replace alone prevents a torn read, not a lost update.

`--toolsets` on a token, not just at launch, because the flag is
per-process and one HTTP server has many callers: a per-process tool
budget stops being a per-caller one the moment the transport is shared.
The intersection applies, so a token cannot widen what the unit was
started with.  `server.build` takes a chooser instead of a fixed list to
make that possible; the stdio path passes none and closes over its
selection exactly as before.

Three things in the request path are deliberate.  `default_allowed_hosts`
exists because the SDK's DNS-rebinding check is allowlist-only with no
implicit localhost -- protection on with an empty list 421s *every*
request -- so the allowlist is derived from the bind address rather than
the protection being switched off to get a working default; a wildcard
bind derives nothing and is refused, which makes binding every interface
the case where the hostnames must be said out loud.  The grant travels in
the ASGI scope and not a contextvar, because in stateful mode the session
manager runs the handler in a task owned by its own lifespan and a
contextvar set in middleware would not be visible there.  And a refusal
is a 401 with an empty body that never echoes the token and never says
which of unknown, revoked or expired it was -- the discipline
`hhstream_live.server` already applies to a wrong phrase, with that app's
own RateLimiter reused rather than a second one grown.

This is NOT MCP's authorization specification, which is OAuth 2.1 plus
RFC 9728 metadata discovery.  A client that can only discover an
authorization server will not connect; one that lets you set a header
will.  Documented as a limit rather than hidden, beside the two the SDK
already imposes.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KchcvnbfhhZhUHy83YL3Ya
2026-10-12 17:53:31 +00:00
2026-10-09 11:32:42 -04:00

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. 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.
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://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:

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 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. Nothing else about the server is configurable — it holds no state and caches no lease, and the pointer lease is an explicit argument on every gesture tool for exactly that reason.

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.

S
Description
No description provided
Readme
2.8 MiB
0 Stars 1 Watchers 0 Forks
Languages
Python 81.7%
Nix 18.1%
Shell 0.2%