Files
hyprland-headless-stream-pl…/examples/hhstream-sessions.config.example.toml
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

52 lines
2.1 KiB
TOML

# hhstreamd configuration — the app allowlist.
#
# This is the main security control (DESIGN.md §8 item 1). Without it,
# `hhstream session start /bin/sh` would make every other control decorative.
#
# The daemon reads this at startup from --config / $HHSTREAM_CONFIG, defaulting
# to /etc/hhstream/config.toml. A missing file is not an error: the allowlist is
# then empty and every `start` is refused with exit 6, naming the file it looked
# for. A misconfigured deployment must not look like a crash.
[defaults]
# The maximum number of live sessions. With no cgroup caps available (see
# DESIGN.md §3.3), this is the primary containment control against a looping
# agent spawning browsers, so it is a real setting and not a tuning knob.
max_sessions = 4
# Default idle timeout, in seconds. A session with no `touch` for this long is
# reaped. `touch` is the only thing that resets the clock.
idle_timeout_s = 10800 # 3h
# The largest idle timeout a caller may ask for.
max_idle_timeout_s = 86400 # 24h
# How long `kill` waits between SIGTERM and SIGKILL, by default.
grace_s = 10
# How long `start` will wait for readiness before returning exit 7. The session
# is left alive either way.
wait_ready_s = 15
# ---------------------------------------------------------------------------
# Apps. The key is the name a caller passes to `start`; it is never a path.
# ---------------------------------------------------------------------------
[apps.chromium]
# Absolute path, always. Resolution against PATH is refused.
exec = "/run/current-system/sw/bin/chromium"
# Caller-supplied arguments must each match one of these fnmatch patterns.
# An app with no `args_allow` accepts no caller arguments at all.
args_allow = ["--new-window", "--app=*", "--user-data-dir=*"]
[apps.foot]
exec = "/run/current-system/sw/bin/foot"
[apps.blender]
exec = "/run/current-system/sw/bin/blender"
# Fixed arguments, always prepended, never supplied by the caller.
args = ["--factory-startup"]
args_allow = ["*.blend"]
# A per-app default idle timeout, overridden by --idle-timeout.
idle_timeout_s = 7200