`docs/CONTRACT-mcp.md` goes to mcp-v3 with a change table: two tools, two resources, three `session_start` arguments, and the one rule that is not a name at all -- a connected viewer is the single exception to the idle-clock rule, and it cannot be invoked, so it is documented in §6 rather than offered in §3. v3 is additive; every v2 name still means what it meant. README.md leads the stream with the shape of it rather than the options: one port for the machine, a phrase per session, a browser `<img>` as the entire client, and the four things worth knowing before switching one on -- that it is per session and off by default, that the phrase survives a restart, that capture runs only while somebody is connected, and that watching counts as activity. The phrase is called what it is: the only protection, with no TLS and no second factor. ARCHITECTURE.md gains the fourth unit as a seventh box -- `hhstream-live`, hanging off the broker by `live.sock` with one port and a browser at the end of it -- and the counts move to 23 and 10. Two TODOs, both written by `checks/vm-stream.nix`: * `a-stream-that-gave-up-still-reports-attached.md`. The publisher stops a stream after ten consecutive capture failures and the stop is sticky on purpose, but `Control._describe` does not pass `stopped` on, so `_stream_public` reports `attached: true` for a capture that has permanently given up. That is the second place `attached` answers "is a capture running right now" wrongly, and a field that is right only when nothing is wrong is not worth reading. * `capture-binary-and-the-unit-path.md` is now half fixed, and says so. The module passes grim's store path and this check reads real frames -- which immediately found the sibling fault, the unit's missing `XDG_RUNTIME_DIR`. What is still open is the other half: the app resolves its capture command by name and never checks it, so any deployment that is not this module still discovers a broken capture ten failures later. The plan's status section records Stage 2 and Stage 3 as built, the two decisions §5 left open (that `start` takes `--stream`, and that the default rate is the daemon's), and what Stage 2 deliberately did not do -- §6's restart re-attachment, which has its own TODO. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011ZeH65zd6pFTgBSu52W9PE
177 lines
7.5 KiB
Markdown
177 lines
7.5 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 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. 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. |