HermenixandClaude Opus 5 9347e31705 feat(nix): mcp.http, its unit, and a state directory of its own
`mcp.http.enable` is the fourth unit and the first that listens on a
port.  The comment on the `mcp` block said anything that started a daemon
here "would be inventing a second thing to supervise", so it is rewritten
rather than deleted: what changed is not the cost of supervising it but
what it buys -- a port is reachable by a caller who never touched this
filesystem, which is the first time a token on this surface means
anything.  The two options stay independent and neither implies the
other.

`mcp.stateDir` defaults to /var/lib/hhstream-mcp and is deliberately NOT
`sessions.stateDir`.  That directory is 0700 owned by the broker's user
and holds `events.jsonl`; parking a token file in it would grant this
shim write access to the audit trail's directory for no reason, and the
two have different lifetimes besides.  A tmpfiles entry rather than
`StateDirectory=`, for the reason the broker's state dir is one --
`StateDirectory=` can only name a path under /var/lib and would stop
applying the moment the option is pointed elsewhere.

The unit runs as sessions.user with sessions.group, because its tools are
the CLI's handlers called in process and that CLI opens a 0660 control
socket owned by that user and a compositor runtime directory owned by
that group.  `Wants`/`After` the broker and not `BindsTo`: the frame
verbs answer with the broker down and the rest answer exit 5, which is a
true answer, whereas a listener that vanished with the broker would turn
that into a connection refused and tell a client nothing.  The systemd
default KillMode is right here and `KillMode=process` -- which the broker
and the driver both need -- would be wrong, because every process this
unit starts is part of answering one request.

Two assertions and two warnings, each for a failure that is otherwise
discovered from the far side of an HTTP client:

* http.enable without sessions.enable is an assertion, not the warning
  `mcp.enable` gets against the same condition, because there the frame
  tools still work and here `User=` names an account that does not exist.
* a wildcard bind with no allowedHosts is an assertion, because the
  SDK's rebinding allowlist has no implicit localhost and the unit would
  come up refusing everything with a 421.
* a non-loopback address warns that the token crosses the wire in clear
  text, since the option reads like a bind address and not like a
  decision about what is on it.
* openFirewall warns and is not implied by http.enable, the same way
  sessions.stream.openFirewall is not implied by the stream.

`mcp.http.enable` also puts the binary on PATH, because `token mint` is
how the credential that unit demands gets issued.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KchcvnbfhhZhUHy83YL3Ya
2026-10-11 20:40:37 +00:00
2026-10-09 11:32:42 -04:00
2026-09-28 05:01:41 +00:00
2026-09-28 05:01:41 +00: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.

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 — 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:

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-one 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%