Files
hyprland-headless-stream-pl…/docs/TODO/capture-binary-and-the-unit-path.md
T
Hermenix 4fefb448ac docs(todo): the capture binary needs an absolute path under a unit
Found on the deployment machine on 2026-10-11, the first time `hhstream-live`
was run **as a unit** rather than from a login shell: a systemd unit's PATH has
no system profile, so the capture command `grim` is not found, ten times, and
the stream gives up. It answers on its port, serves the landing page and
reports `"stopped": true, "failures": 10` while showing nothing -- the quiet
half of the failure is what makes it worth a file.

The module already solves this for `sessions.apps` by requiring an absolute
store path; the stream's unit has to do the same (or set PATH, which is what
made the deployment run work). Recorded in `docs/TODO/` with the two fixes, and
named as a risk on stage 3 of the plan, which is the stage that turns this from
an experiment into the only path.
2026-10-11 02:31:52 +00:00

2.9 KiB

The capture command needs an absolute path under a unit

The issue

hhstream-live runs its capture command (grim -c -t jpeg -q 80 -o <output> -) by name, from the PATH it inherits. Under systemd that path is /usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin — the system profile is deliberately not on it — so the capture fails, ten times, and the stream gives up:

WARNING hhstream.live: stream on hh-chromium-yhvpms: giving up after 10
consecutive capture failures: capture command ['grim', '-c', '-t', 'jpeg',
'-q', '80', '-o', 'hh-chromium-yhvpms', '-'] could not be run:
[Errno 2] No such file or directory: 'grim'

Measured on 2026-10-11 on the deployment machine, the first time the app was run as a unit rather than from a login shell. A login shell has /run/current-system/sw/bin on its PATH, which is why every run before this one — the stage-1 work, the standalone serve --stream runs, the whole test suite — never saw it.

What makes it worth a file rather than a line: the failure is quiet in the worst way. The unit starts, the port opens, the landing page answers, and status.json reports a stream that is simply "stopped": true with "failures": 10. A viewer sees an empty frame area and nothing else says why. Only the unit's log names the reason, one line above the giving-up entry.

Ideas

  1. An absolute binary, as the module already does elsewhere (recommended). sessions.apps requires an absolute store path for exactly this reason — "a unit's default PATH does not include the system profile", which is why the allowlist spells foot as ${pkgs.foot}/bin/foot. The stream's unit should not inherit grim by name either: pass ${pkgs.grim}/bin/grim as the capture command from the module (or set PATH on the unit, which is what made it work on the deployment machine). The absolute path is also the stronger control: it names one exact binary instead of whatever PATH resolves to at the moment the unit starts.
  2. Resolve early and fail loudly. Have the app resolve the binary itself at start-up and refuse to serve with a named error (capture_binary_missing) if it is not there. A unit that dies at start is a five-second diagnosis; a unit that serves an empty frame is an afternoon.
  3. Both. The module passes the absolute path and the app checks it once at start-up: the first is the fix, the second is what catches the next deployment shape nobody has thought of yet.

Why it matters

Stage 3's unit is the point at which running under systemd stops being an experiment and becomes the only path every deployment takes — and a stream that answers, reports a healthy port, and shows nothing is a worse failure than one that does not start. Whichever idea is taken, the check for it belongs in the same stage as the unit: a vm-* check that starts the unit and reads one frame would have caught this on the day it was written.