Hermenix 30f456c07e integrate the session broker: one CLI, a module unit, and a VM check
M0 of the sessions design, wired into the flake and gated by a real check.

What is here now:

- `src/hhstreamd/` — the broker: session registry, lifecycle verbs, process-group
  teardown, app allowlist, audit log, idle reaper on CLOCK_BOOTTIME.
- `src/hhstream_session/` — the CLI handlers, registered into the one front door.
- `src/hhstream/cli.py` — `hhstream status|shot|run|record|session …`, so the
  frame verbs and the session namespace are one binary.
- `nix/module.nix` — `sessions.*` options and the `hhstream-sessions.service`
  unit: the operator's own account (never a service account, because launched
  applications should see that account's home), the compositor's group as a
  supplementary group (without it a launched GUI client cannot open the Wayland
  socket), the generated app allowlist, and `--compositor-runtime-dir` so
  applications are handed the compositor's session rather than the broker's.
- `checks/vm-sessions.nix` — 18 subtests on a real compositor in a VM.

Two bugs found by driving it, both fixed:

- BUG-01: launched applications could not reach the compositor at all — the
  broker spawned them with its own inherited environment, which names the login
  session. `hhstreamd/compositor.py` discovers the socket and builds the child
  environment; a directory with no usable socket is a startup refusal, not a
  warning.
- BUG-02: `kill` refused to signal a live application and said nothing was
  wrong. The identity gate hashed `/proc/<pid>/cmdline`, which every `execve`
  replaces — and on NixOS applications are reached through wrapper scripts that
  do exactly that. The gate now rests on `starttime` (+ boot id, + session id
  where it is immutable) and records command-line drift as evidence of nothing.

KillMode=process is set on the unit on purpose: the default control-group kill
would take the applications down with the broker, which would make adoption and
a broker restart pointless.
2026-10-01 12:23:16 +00: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/hyprland-headless-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.

Document What it is
docs/CONTRACT.md the wire protocol and the module surface — the interface other people build against
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%