{ lib, config, pkgs, ... }: # The option surface below is the interface described in docs/CONTRACT.md # ("NixOS module surface"); the `config` block wires it to the two services # named there. let cfg = config.services.hyprland-headless-stream; # One private runtime directory, shared by both units: it holds the Wayland # socket of the session and, by default, the published frame socket too. # `RuntimeDirectoryPreserve` keeps it (and the Wayland socket) alive across a # restart of either unit. # # The name is short on purpose, and the assertion below is what keeps it that # way. A Unix socket address carries its path inside `sun_path`, which is 108 # bytes including the terminating NUL (linux/un.h), and the compositor puts # its IPC sockets under this directory: # # /hypr//.socket.sock requests # /hypr//.socket2.sock events # # Of that budget, 20 characters are fixed and the instance signature (~30) is # Hyprland's to choose; this directory's name is the only part we control. At # the previous name -- `/run/hyprland-headless-stream`, 29 characters -- the # event socket did not fit and the compositor refused to bind it: # # ERR ]: Socket2 path is too long. (2) IPC will not work. # # The *request* socket kept answering `hyprctl` anyway (both ends agreed on a # residual truncated path), which is why the broken event socket went # unnoticed. docs/CONTRACT-sessions.md §5 freezes the ceiling at 25. runtimeDirName = "hypr-stream"; runtimeDir = "/run/${runtimeDirName}"; runtimeDirMaxLength = 25; # The broker's own runtime directory: its control socket and, when the # pointer driver is enabled, the private socket the two speak over. Both # paths are frozen in docs/CONTRACT-sessions.md §5, and the driver's command # line is frozen with them, so this is a name for a constant rather than # something a consumer may move. brokerRuntimeDirName = "hhstream"; brokerRuntimeDir = "/run/${brokerRuntimeDirName}"; controlSocket = "${brokerRuntimeDir}/control.sock"; pointerSocket = "${brokerRuntimeDir}/pointer.sock"; # Addresses that mean "this listener answers on loopback only". The spelling # `localhost` is included because it is what a person writes; it is not a # resolution the module performs. loopbackBinds = [ "127.0.0.1" "::1" "localhost" ]; socketDir = builtins.dirOf cfg.socketPath; # Hyprland refuses `--socket` unless it is paired with `--wayland-fd` (that # pair is the socket-handover path), so the socket name is not ours to choose: # the compositor calls wl_display_add_socket_auto, which takes the first free # `wayland-N` starting at 0. # # N is therefore not fixed. The runtime directory is preserved across restarts # (`RuntimeDirectoryPreserve=yes`), so a crashed compositor leaves its # `wayland-0` behind and the next start binds `wayland-1` — measured in the VM # test, where the frame server then waited forever for a socket that would # never exist. Neither unit may hardcode the name: # # * the compositor clears leftover sockets first (the directory is private to # this session, so nothing else can own them) — that alone makes it # `wayland-0` again, but the units below do not depend on that; # * the server discovers whichever socket is actually there. clearStaleSockets = pkgs.writeShellScript "hhstream-clear-stale-sockets" '' for stale in "$XDG_RUNTIME_DIR"/wayland-* "$XDG_RUNTIME_DIR"/wayland-*.lock; do if [ -e "$stale" ]; then ${lib.getExe' pkgs.coreutils "rm"} -f "$stale" fi done ''; # Exit 0 once *any* Wayland socket is bound, and print its name so callers that # want it do not have to glob again. findSession = pkgs.writeShellScript "hhstream-find-session" '' for _ in $(${lib.getExe' pkgs.coreutils "seq"} 1 300); do for candidate in "$XDG_RUNTIME_DIR"/wayland-*; do if [ -S "$candidate" ]; then echo "''${candidate##*/}" exit 0 fi done ${lib.getExe' pkgs.coreutils "sleep"} 0.1 done echo "no Wayland socket in $XDG_RUNTIME_DIR after 30s; is the compositor up?" >&2 exit 1 ''; # Open the compositor's IPC directory to its own group. # # MEASURED, in checks/vm-ipc.nix, which is the check that exists to find # exactly this: # # drwxr-x--- hhstream hhstream /run/hypr-stream # drwx------ hhstream hhstream /run/hypr-stream/hypr <-- 0700 # srw-rw---- hhstream hhstream /run/hypr-stream/stream.sock # srwxrwx--- hhstream hhstream /run/hypr-stream/wayland-1 # # The unit's `UMask=0007` reaches everything the compositor creates with a # permissive mode -- the Wayland socket is group-accessible, which is how a # launched application connects at all -- but Hyprland creates its *instance* # directory with `S_IRWXU`, i.e. 0700 with no umask left to subtract. So the # request and event sockets underneath it are reachable by `hhstream` and by # nobody else. # # The broker runs as the operator's account with `hhstream` as a supplementary # group, deliberately (it starts processes that must be the operator's). It # therefore could not open the IPC directory at all, and the symptom was not # an error: `HyprlandIPC.discover` raised `CompositorUnavailable`, the broker # degraded exactly as it is designed to, and every session got # `container: degraded` while `container.list` said `compositor: absent`. A # whole capability silently absent, on a machine where nothing looked wrong. # # Group access, not world: the directory stays 0750 and the sockets 0660, so # this grants the compositor's own group what it already has on the Wayland # socket beside it, and nothing more. # # Run only when the broker is enabled (nothing else needs the IPC sockets), # and allowed to fail the unit: a compositor whose IPC the broker cannot # reach is a session with no containers and no pointer, and discovering that # from a half-working desktop is how this went unnoticed in the first place. openIpcDirectory = pkgs.writeShellScript "hhstream-open-ipc-directory" '' set -eu hypr="$XDG_RUNTIME_DIR/hypr" for _ in $(${lib.getExe' pkgs.coreutils "seq"} 1 300); do if [ -n "$(${lib.getExe' pkgs.coreutils "ls"} -1 "$hypr" 2>/dev/null)" ]; then break fi ${lib.getExe' pkgs.coreutils "sleep"} 0.1 done if [ ! -d "$hypr" ]; then echo "no $hypr after 30s: the compositor bound no IPC socket" >&2 exit 1 fi ${lib.getExe' pkgs.coreutils "chmod"} 0750 "$hypr" for instance in "$hypr"/*; do [ -d "$instance" ] || continue ${lib.getExe' pkgs.coreutils "chmod"} 0750 "$instance" for sock in "$instance"/.socket.sock "$instance"/.socket2.sock; do [ -S "$sock" ] || continue ${lib.getExe' pkgs.coreutils "chmod"} 0660 "$sock" done ${lib.getExe' pkgs.coreutils "ls"} -la "$instance" done ''; # The server needs WAYLAND_DISPLAY pointing at the socket the compositor # actually bound. This cannot be an `Environment=` line, because the name is # only known once the compositor is up — systemd's ExecStartPre cannot export # into the main process. execServer = pkgs.writeShellScript "hhstream-exec-server" '' for candidate in "$XDG_RUNTIME_DIR"/wayland-*; do if [ -S "$candidate" ]; then export WAYLAND_DISPLAY="''${candidate##*/}" break fi done exec ${lib.getExe' cfg.package "hhstream-server"} "$@" ''; hyprlandConf = pkgs.writeText "hyprland.conf" (import ./hyprland-conf.nix { inherit lib; inherit (cfg) outputs extraConfig; }); # `BindsTo=` already stops the frame server when the compositor goes away, but # the compositor is only *ready* once its Wayland socket is bound. The # compositor unit is `Type=notify`, so `findSession` above is a second line of # defence for compositor builds that do not sd_notify, and it is why this is # not a plain `After=` ordering. # The session broker's config, in the daemon's own format (PLAN §10). It # carries the app allowlist, which is what makes `sessions.enable = true` # useful rather than decorative: the daemon treats a missing file as an empty # allowlist and refuses every `start` with the path it looked for. # # ─── A GAP, STATED HERE RATHER THAN HIDDEN ─────────────────────────────── # `hhstreamd/policy.py:policy_from_dict` reads `[defaults]` and `[apps]` and # nothing else, and `hhstreamd/__main__.py:serve` builds its `ManagerConfig` # from command-line flags that have no counterpart for any of these numbers. # So the `[compositor]` and `[pointer]` tables below, and `max_containers`, # are written and *not read*: the broker falls back to its own defaults # (container band 1000, 4 slots, 1280x720; lease 30 s / 300 s), which happen # to agree with the defaults here, so a deployment that leaves these options # alone behaves exactly as this file says. One that changes them is ignored. # # They are rendered anyway, and with §10's own key names, because that is the # interface the broker is specified to read and writing it is what makes the # omission a one-file fix rather than a redesign. `sessions.pointer.enable` # is the one option here with teeth today: it decides whether the driver unit # exists, which is what the broker's `pointer_socket` finds or does not find. # # Two key names differ from §10 on purpose. §10 puts `max_sessions` and # `max_containers` under `[broker]`, but the broker reads `max_sessions` from # `[defaults]` — so `max_containers` is written beside it, where the code # that will read it already looks. And §10 has no key for # `containers.enable`, so `containers_enabled` is named here. # ────────────────────────────────────────────────────────────────────────── sessionsConfig = pkgs.writeText "hhstream-sessions.toml" '' [defaults] max_sessions = ${toString cfg.sessions.maxSessions} idle_timeout_s = ${toString cfg.sessions.idleTimeout} max_containers = ${toString cfg.sessions.containers.max} [compositor] runtime_dir = ${builtins.toJSON runtimeDir} containers_enabled = ${lib.boolToString cfg.sessions.containers.enable} workspace_base = ${toString cfg.sessions.containers.workspaceBase} container_mode = ${builtins.toJSON cfg.sessions.containers.mode} [pointer] enabled = ${lib.boolToString cfg.sessions.pointer.enable} lease_ttl_s = ${toString cfg.sessions.pointer.leaseTtl} lease_max_s = ${toString cfg.sessions.pointer.leaseMax} ${lib.concatStringsSep "\n" ( lib.mapAttrsToList (name: app: '' [apps.${name}] exec = ${builtins.toJSON (toString app.exec)} args_allow = [${ lib.concatStringsSep ", " (map (arg: builtins.toJSON arg) app.argsAllow) }] '') cfg.sessions.apps )} ''; serverArgs = [ "--socket" cfg.socketPath "--fps" (toString cfg.frameRate) "--format" cfg.format ] # One occurrence per argv word. The capture command is a list whose words # start with `-` (`grim -t png -`), and repeating the flag is the only # shape that survives that without inventing a quoting convention. # `hhstream.server.build_parser()` is still a stub, so this is the one # place the module guesses at the server's CLI rather than reading it. ++ lib.concatMap (word: ["--capture-command" word]) cfg.captureCommand; # Shared by both units: a private session, no parent display to nest in. sessionEnvironment = { XDG_RUNTIME_DIR = runtimeDir; HOME = runtimeDir; XDG_SESSION_TYPE = "wayland"; }; commonServiceConfig = { User = cfg.user; Group = cfg.group; RuntimeDirectory = runtimeDirName; RuntimeDirectoryMode = "0750"; RuntimeDirectoryPreserve = "yes"; WorkingDirectory = runtimeDir; # docs/CONTRACT.md: the socket is owned by the service user, mode 0660. UMask = "0007"; Restart = "always"; RestartSec = 2; # A GPU render node is the one piece of hardware a headless session still # needs; everything else is virtual. SupplementaryGroups = ["video" "render"]; NoNewPrivileges = true; PrivateTmp = true; ProtectHome = true; ProtectSystem = "strict"; ProtectControlGroups = true; ProtectKernelTunables = true; ProtectKernelModules = true; RestrictSUIDSGID = true; ReadWritePaths = lib.optional (socketDir != runtimeDir) socketDir; }; in { options.services.hyprland-headless-stream = { enable = lib.mkEnableOption "a headless Hyprland session streamed to a Unix socket"; socketPath = lib.mkOption { type = lib.types.str; default = "/run/hypr-stream/stream.sock"; description = "Where the frame server publishes frames."; }; user = lib.mkOption { type = lib.types.str; default = "hhstream"; description = "User the compositor and frame server run as."; }; group = lib.mkOption { type = lib.types.str; default = "hhstream"; description = "Group owning the socket."; }; frameRate = lib.mkOption { type = lib.types.ints.positive; default = 30; description = "Target capture rate; becomes `fps` in the protocol Hello."; }; format = lib.mkOption { type = lib.types.enum ["png" "jpeg"]; default = "png"; description = "Frame encoding."; }; outputs = lib.mkOption { type = lib.types.listOf (lib.types.submodule { options = { name = lib.mkOption { type = lib.types.str; default = ""; description = '' Regex matched against the names of the outputs this machine has (`eDP-1`, `Virtual-1`, ...). Empty is Hyprland's wildcard form and matches every output; a name no connector has is a rule that is silently ignored. ''; }; width = lib.mkOption { type = lib.types.ints.positive; default = 1280; }; height = lib.mkOption { type = lib.types.ints.positive; default = 720; }; refresh = lib.mkOption { type = lib.types.ints.positive; default = 30; }; # Was `lib.types.positive`, which does not exist in nixpkgs and made # `outputs` unreadable; `numbers.positive` is the int-or-float type # that name meant. scale = lib.mkOption { type = lib.types.numbers.positive; default = 1.0; }; }; }); default = [ { name = ""; width = 1280; height = 720; refresh = 30; scale = 1.0; } ]; description = '' Monitor rules applied to the outputs the machine has. Each entry becomes one `monitor = , x@, auto, ` line. These are *not* outputs the compositor creates: aquamarine's headless backend has no allocator of its own and rides on the DRM backend, so a session started by this module always has the GPU's own connectors and whatever names the host gives them. The default therefore uses the empty name -- Hyprland's wildcard, as in its own shipped `monitor=,preferred,auto,1` -- so that `enable = true` alone gives a session at a known size on any machine. Naming a connector that does not exist is not an error; the rule is simply never applied. ''; }; extraConfig = lib.mkOption { type = lib.types.lines; default = ""; description = "Extra lines appended to hyprland.conf."; }; hyprlandPackage = lib.mkOption { type = lib.types.package; default = pkgs.hyprland; defaultText = lib.literalExpression "pkgs.hyprland"; description = "Compositor to run."; }; package = lib.mkOption { type = lib.types.package; description = "The frame server / client package."; }; captureCommand = lib.mkOption { type = lib.types.listOf lib.types.str; default = ["grim" "-t" "png" "-"]; description = "Command that writes one frame to stdout; overridable for tests."; }; sessions = { enable = lib.mkOption { type = lib.types.bool; default = false; description = '' Run the session broker (`hhstreamd`) that launches GUI applications into this compositor as *tracked sessions*: started by name, kept alive by an explicit `touch`, killed by name, and reaped when they go quiet for {option}`sessions.idleTimeout`. It is off by default because it is a different capability from streaming frames: a frame server can be read by anyone in the group, while this one starts processes on the machine. Its CLI is `hhstream session …` on the same binary as the frame commands; the daemon itself is the unit `hhstream-sessions.service`. ''; }; user = lib.mkOption { type = lib.types.str; default = config.services.hyprland-headless-stream.user; defaultText = lib.literalExpression "services.hyprland-headless-stream.user"; description = '' The account the broker runs as, and the account every launched application runs as. It must already exist: the module does not create it, because its whole point is usually to be a real person's account whose home directory and files the applications should see. Set it to the account that will actually drive the CLI. The broker is granted {option}`sessions.group` as a supplementary group so the applications it launches can reach the compositor's socket. ''; }; group = lib.mkOption { type = lib.types.str; default = config.services.hyprland-headless-stream.group; defaultText = lib.literalExpression "services.hyprland-headless-stream.group"; description = '' The group that owns the compositor's runtime directory. The broker gets it as a supplementary group, and passes it to every application it launches — without it a launched GUI client cannot open the Wayland socket and dies at startup. ''; }; idleTimeout = lib.mkOption { type = lib.types.ints.positive; default = 10800; description = '' Seconds a session may go without a `touch` before the broker kills it and everything it spawned. The clock lives in the broker, not in the CLI, so it keeps running after the CLI exits. Only `touch` resets it: `list`, `status`, `logs` and `gc` deliberately do not, or a monitoring loop would keep abandoned sessions alive forever. ''; }; maxSessions = lib.mkOption { type = lib.types.ints.positive; default = 4; description = '' Hard cap on live sessions. Without cgroup limits this is the main containment control against a looping caller spawning applications until the machine gives up. ''; }; apps = lib.mkOption { type = lib.types.attrsOf (lib.types.submodule { options = { exec = lib.mkOption { type = lib.types.path; description = "Absolute path to the executable. Never a shell command."; }; argsAllow = lib.mkOption { type = lib.types.listOf lib.types.str; default = []; description = '' Arguments a caller may pass to this application. Anything else is refused, so `exec` must be able to do its job with these and nothing more. A trailing `*` matches a prefix (`--user-data-dir=*`). ''; }; }; }); default = {}; description = '' The allowlist: which applications may be started as a session, and with which arguments. This is the primary security control — without it, `session start /bin/sh` would make every other control decorative. An application that is not listed here cannot be started at all. ''; example = lib.literalExpression '' { chromium.exec = "''${pkgs.chromium}/bin/chromium"; chromium.argsAllow = [ "--new-window" "--user-data-dir=*" "https://*" ]; } ''; }; configFile = lib.mkOption { type = lib.types.nullOr lib.types.path; default = null; description = '' Use this TOML allowlist instead of the one generated from {option}`sessions.apps`, for configurations the option shape cannot express. ''; }; containers = { enable = lib.mkOption { type = lib.types.bool; default = true; description = '' Give each session its own headless output and workspace — a *container* (PLAN §5). The broker creates `hh-` on `start`, binds a window rule to it so the application's window lands there and nowhere else, and removes the output on teardown, which takes the container with it. Without it every application shares the main output, so two sessions see each other's windows and `grim -o` has nothing to aim at. It is on by default because every other part of this option tree assumes it; turn it off to run a single application on the main screen, as the pre-container module did. ''; }; max = lib.mkOption { type = lib.types.ints.positive; default = 2; description = '' How many containers may exist at once. Each one is a real render target: at `vfr = false` the compositor renders every output every frame, so this is a CPU budget and not a preference. The default of 2 is the plan's conservative starting point for a two-core machine and is explicitly waiting on a measurement (PLAN §5.5, experiment 2) — raise it from a number you measured, not from one you hoped for. Distinct from {option}`sessions.maxSessions`: a session may run without a container (degraded, if the compositor was unreachable), so the two caps bound different things. Exhausting this one refuses the `start` with exit 6 rather than quietly sharing a screen. ''; }; mode = lib.mkOption { type = lib.types.strMatching "[0-9]+x[0-9]+"; default = "1280x720"; description = '' The size each container's output is set to, `WIDTHxHEIGHT` (docs/CONTRACT-sessions.md §5 freezes the default at 1280x720). This is the resolution an application sees and the resolution `grim -o hh-` captures, so it is also the cost per container. ''; }; workspaceBase = lib.mkOption { type = lib.types.ints.positive; default = 1000; description = '' First workspace number of the reserved band containers are allocated from; a container gets `workspaceBase + slot`. The band exists so a container never collides with a workspace the operator uses by hand. Numbers this high are not reachable by the default keybindings, which is the point. ''; }; }; pointer = { enable = lib.mkOption { type = lib.types.bool; default = false; description = '' Run `hhstream-pointer`, the driver that moves this session's one cursor on the broker's instruction (`hhstream session pointer …`). Off by default, and the default is the honest one: input injection is a capability distinct from running applications, the cursor is singular so it has to be leased, and nothing in the compositor stops a *hostile* client from creating its own virtual pointer (PLAN §6.6) — the lease disciplines our sessions, it does not enforce against theirs. With it off, every pointer verb answers `driver_unavailable` (exit 10) rather than pretending: the broker looks for the driver's socket and does not find one. ''; }; leaseTtl = lib.mkOption { type = lib.types.ints.positive; default = 30; description = '' Seconds a pointer lease may go without a pointer verb before the broker force-releases it and lifts anything still pressed. This is what makes the lease a promise rather than a hope: an agent that acquired the cursor, pressed a button and died holds neither for longer than this. Every gesture verb refreshes it. ''; }; leaseMax = lib.mkOption { type = lib.types.ints.positive; default = 300; description = '' Hard ceiling on a single lease, in seconds, refreshed or not. {option}`sessions.pointer.leaseTtl` can be extended indefinitely by a caller that keeps sending verbs; this one cannot, so one session can never own the cursor forever. ''; }; }; # The session-stream web app — `hhstream-live`, the router that serves a # live view of one session per phrase, over one port # (`docs/plans/2026-10-04-session-stream-webapp.md`). # # Only the *reach* of it is declared here so far: the port every stream # shares, the address it will bind, and whether that port is opened in # the firewall. The unit that runs the app, the phrases the broker keeps # in its records and the `session stream enable` verbs are later stages # of that plan — and deliberately so: a stream is switched on per # session, never for all of them, so nothing here turns one on. stream = { port = lib.mkOption { type = lib.types.port; default = 9988; description = '' The single TCP port every stream shares. One listener rather than one per session is what makes the phrase speakable: there is one address to give a person, one thing to firewall and one thing to stop. It is also why this is a fixed number with no range to fall back on — a stream at a port nobody was told about is worse than a stream that is down, so a taken port fails loudly instead of moving. ''; }; bind = lib.mkOption { type = lib.types.str; default = "127.0.0.1"; description = '' The address the web app will bind. Loopback by default, where the reachable path is an ssh tunnel (`ssh -L 9988:127.0.0.1:9988`) and nothing else. Set it to an address a peer can reach (`"0.0.0.0"`) when {option}`sessions.stream.openFirewall` is set: opening the port for a listener that is not on it is a hole with no service behind it, which is why that pairing is refused rather than allowed. ''; }; openFirewall = lib.mkOption { type = lib.types.bool; default = false; description = '' Open {option}`sessions.stream.port` in the firewall. Off by default, and deliberately not implied by {option}`sessions.enable`: a live view of this desktop is readable by anyone who can reach the port, and the phrase in the URL is its only credential — no TLS, no second factor (`docs/plans/2026-10-04-…` §4). Opening it is an explicit act, and it opens exactly one port. ''; }; }; stateDir = lib.mkOption { type = lib.types.str; default = "/var/lib/hhstream"; description = '' Where the broker keeps what outlives a broker restart: the live-record mirrors it adopts on the way back up, tombstones of ended sessions, and `events.jsonl`, the audit trail of every accepted command. Point this at durable storage. The default is a system path, which on a machine whose root is rebuilt from scratch — the usual shape of a declaratively-managed server — means the audit trail dies with the next reinstall. On such a machine this belongs on the same disk as the rest of the state that cannot be rebuilt. ''; }; }; }; config = lib.mkIf cfg.enable { assertions = [ { assertion = cfg.outputs != []; message = "services.hyprland-headless-stream.outputs must not be empty."; } { assertion = lib.hasPrefix "/" cfg.socketPath; message = "services.hyprland-headless-stream.socketPath must be an absolute path."; } # Structural, not cosmetic: see the `runtimeDirName` comment above. The # ceiling exists so the compositor's *event* socket still fits in # `sun_path`, and the symptom of breaking it is silent -- the request # socket keeps answering, so `hyprctl` looks fine while every event-driven # feature is dead. { assertion = builtins.stringLength runtimeDir <= runtimeDirMaxLength; message = '' The compositor runtime directory "${runtimeDir}" is ${ toString (builtins.stringLength runtimeDir) } characters; it must be at most ${toString runtimeDirMaxLength}. Hyprland's event socket is /hypr//.socket2.sock. A longer directory pushes that path past the 108 bytes a Unix socket address has for `sun_path`, and the compositor then refuses to bind it: ERR ]: Socket2 path is too long. (2) IPC will not work. Nothing appears broken when that happens -- the shorter request socket still answers `hyprctl` -- but the event stream never arrives, so every feature that watches the compositor (window and workspace tracking, session containers) stops working. docs/CONTRACT-sessions.md §5 freezes this limit; shorten the directory rather than raising it. ''; } { assertion = cfg.sessions.pointer.leaseTtl <= cfg.sessions.pointer.leaseMax; message = '' services.hyprland-headless-stream.sessions.pointer.leaseTtl (${toString cfg.sessions.pointer.leaseTtl}s) is longer than leaseMax (${toString cfg.sessions.pointer.leaseMax}s), so the hard ceiling would fire before the idle timeout could and the idle timeout would never be reached. leaseMax is the cap a caller cannot refresh past; leaseTtl is the one it can. ''; } { # A driver with no broker is a process holding a Wayland connection and # a socket nobody will ever connect to: the broker owns the lease, and # the driver is deliberately stateless (CONTRACT-sessions.md §3.4). assertion = !cfg.sessions.pointer.enable || cfg.sessions.enable; message = '' services.hyprland-headless-stream.sessions.pointer.enable needs sessions.enable = true. The pointer driver takes its instructions from the session broker -- it holds no lease of its own and has no other client -- so without the broker it would bind a socket nothing connects to. ''; } { assertion = !cfg.sessions.stream.openFirewall || !(lib.elem cfg.sessions.stream.bind loopbackBinds); message = '' services.hyprland-headless-stream.sessions.stream.openFirewall is true while sessions.stream.bind is "${cfg.sessions.stream.bind}" — a loopback address. The port would be open in the firewall with nothing answering on it from anywhere but this machine, which is a hole rather than a feature. Set sessions.stream.bind to an address a peer can reach ("0.0.0.0"), or leave the firewall closed and reach the stream through a tunnel (`ssh -L 9988:127.0.0.1:9988`). ''; } { assertion = !cfg.sessions.enable || lib.hasAttr cfg.sessions.user config.users.users; message = '' services.hyprland-headless-stream.sessions.user = "${cfg.sessions.user}" is not a declared user. The module deliberately does not create it: launched applications run as that account, so it is normally a real person's account whose home directory and files they should see. Declare it (or point the option at an existing account). ''; } ]; # The flake's own build, as docs/CONTRACT.md says; `mkDefault` so a # consumer (or the test harness) can still point this at its own package. services.hyprland-headless-stream.package = lib.mkDefault (pkgs.callPackage ./package.nix {}); # The broker's state directory and the moved socket directory are two # different reasons to write a tmpfiles entry, and this option takes one # definition — so they are merged here rather than assigned twice (which # does not evaluate at all). systemd.tmpfiles.settings = lib.mkMerge [ # The broker keeps the records it adopts on the way back up, its # tombstones, and `events.jsonl`, the audit trail of every accepted # command. It is declared here rather than left to the daemon so its owner # and mode are declarative and survive a restart of the unit. (lib.mkIf cfg.sessions.enable { "10-hhstream-sessions".${cfg.sessions.stateDir}.d = { user = cfg.sessions.user; group = cfg.sessions.group; mode = "0700"; }; }) # The broker's runtime directory, which is also the pointer driver's: the # control socket and the private broker-driver socket both live in it # (CONTRACT-sessions.md §5), and it is declared here because *two* units # now need it to exist. # # `RuntimeDirectory=` on the broker alone is not enough. systemd removes # a unit's RuntimeDirectory when that unit stops, so a `systemctl restart # hhstream-sessions` would delete /run/hhstream and take the driver's # pointer.sock with it -- leaving the driver listening on an unlinked # inode and the broker unable to reach a driver that is running. Hence # this entry, and `RuntimeDirectoryPreserve` on the broker below. (lib.mkIf cfg.sessions.pointer.enable { "10-hhstream-pointer".${brokerRuntimeDir}.d = { user = cfg.sessions.user; group = cfg.sessions.group; mode = "0750"; }; }) # Only needed when the socket was moved out of the runtime directory that # `RuntimeDirectory=` already creates for us. (lib.mkIf (socketDir != runtimeDir) { "10-hyprland-headless-stream".${socketDir}.d = { user = cfg.user; group = cfg.group; mode = "0750"; }; }) ]; # The stream's one port, in the firewall. # # `lib.optional`, not a conditional block: the option is one line and its # effect is one port in the rule set, so there is nothing here that could # open a second one. Everything else about the app — the phrase per # session, the capture, the enable/disable verbs — is later stages of the # plan; this is the only part of the stream that a machine declares before # any of that exists. networking.firewall.allowedTCPPorts = lib.optional cfg.sessions.stream.openFirewall cfg.sessions.stream.port; users.users.${cfg.user} = { isSystemUser = true; group = cfg.group; description = "Headless Hyprland stream session"; }; users.groups.${cfg.group} = {}; systemd.services.hyprland-headless = { description = "Headless Hyprland session"; documentation = ["file://${hyprlandConf}"]; wantedBy = ["multi-user.target"]; # No WAYLAND_DISPLAY and no DISPLAY here on purpose: with either set the # compositor would pick its nested backend and try to connect to a parent # session. Without them it drives DRM directly, and the monitor rules in # hyprland.conf set the mode of whatever connectors it finds there. environment = sessionEnvironment // { # We are a system service: there is no user bus and no user manager to # import the session environment into. HYPRLAND_NO_SD_VARS = "1"; HYPRLAND_NO_CRASHREPORTER = "1"; # Ignored by aquamarine-era Hyprland, honoured by wlroots-era builds # someone may pin in `hyprlandPackage`. WLR_BACKENDS = "headless"; WLR_LIBINPUT_NO_DEVICES = "1"; WLR_RENDERER_ALLOW_SOFTWARE = "1"; # Ask libseat's embedded seatd for a seat with no VT. # # This unit is a system service, not a login, so libseat finds no # /run/seatd.sock and no logind session and falls back to the seatd it # links in -- whose seat is VT-bound by default. That seatd then opens # /dev/tty0, which `cfg.user` cannot, so its client never goes active # and every device open is refused: # # [libseat] Could not open target tty: Permission denied # [libseat] Could not open VT for client # libseat: Couldn't open device at /dev/dri/card0 # drm: Found no gpus to use, cannot continue # # and with the DRM backend gone there is no allocator, so # `CBackend::create()` aborts -- the headless backend takes its # allocator from the DRM one. SEATD_VTBOUND=0 (seatd/server.c) is the # truth about this session on any host: there is no terminal to switch # away from. SEATD_VTBOUND = "0"; }; serviceConfig = commonServiceConfig // { # Hyprland sends READY=1 once the session is up, so the frame server's # `After=` is an ordering on readiness, not just on fork. Type = "notify"; NotifyAccess = "all"; TimeoutStartSec = 60; # A preserved runtime directory can still hold the previous run's # sockets, and that would push the new session to `wayland-1` (and # leave the server waiting on a dead one). ExecStartPre = "${clearStaleSockets}"; ExecStart = lib.escapeShellArgs [ (lib.getExe cfg.hyprlandPackage) "--config" "${hyprlandConf}" ]; # See `openIpcDirectory` above for what this fixes and why it is # allowed to fail the unit. ExecStartPost = lib.mkIf cfg.sessions.enable "${openIpcDirectory}"; }; }; systemd.services.hyprland-headless-stream = { description = "Frame server for the headless Hyprland session"; wantedBy = ["multi-user.target"]; after = ["hyprland-headless.service"]; bindsTo = ["hyprland-headless.service"]; # `captureCommand` defaults to an unqualified `grim`. path = [pkgs.grim]; environment = sessionEnvironment // { # WAYLAND_DISPLAY is set by `execServer` at start, because the socket # name is only known once the compositor has bound it. PYTHONUNBUFFERED = "1"; }; serviceConfig = commonServiceConfig // { Type = "simple"; ExecStartPre = "${findSession} >/dev/null"; ExecStart = lib.escapeShellArgs ([execServer] ++ serverArgs); }; }; # ── the session broker ───────────────────────────────────────────── # # A different capability from the frame server, and a different account: this # one starts processes, so it runs as the operator's own user and everything # it launches runs as that user too. systemd.services.hhstream-sessions = lib.mkIf cfg.sessions.enable { description = "Session broker for the headless Hyprland desktop"; wantedBy = ["multi-user.target"]; after = ["hyprland-headless.service"]; bindsTo = ["hyprland-headless.service"]; environment = { PYTHONUNBUFFERED = "1"; }; serviceConfig = { Type = "simple"; User = cfg.sessions.user; # The broker does not need the group itself -- but the applications it # launches do, and they inherit its supplementary groups. Without it a # GUI client cannot open the compositor's socket (0770, this group) and # dies with "Failed to connect to Wayland display". SupplementaryGroups = [cfg.sessions.group]; RuntimeDirectory = brokerRuntimeDirName; RuntimeDirectoryMode = "0750"; # Kept across a restart of this unit, because it is no longer only this # unit's: the pointer driver's socket lives in it too, and systemd's # default is to delete the directory when the unit stops. See the # tmpfiles entry above for the failure that causes. RuntimeDirectoryPreserve = "yes"; WorkingDirectory = brokerRuntimeDir; UMask = "0007"; Restart = "on-failure"; RestartSec = 1; NoNewPrivileges = true; # Sessions must outlive the broker, because a broker restart is an # ordinary event (an upgrade, a crash, `systemctl restart`) and the whole # point of the registry is to adopt what it finds afterwards. # # systemd's default is KillMode=control-group, which SIGTERMs every # process in the unit's cgroup when the unit stops -- i.e. it kills the # applications from outside, undoing the broker's own care (it spawns # them with a plain Popen precisely so its own death does not reach them). # KillMode=process signals only the broker; the applications are left # running and are adopted on the way back up. KillMode = "process"; ExecStart = lib.escapeShellArgs [ (lib.getExe' cfg.package "hhstreamd") "--socket" controlSocket "--runtime-dir" brokerRuntimeDir "--state-dir" cfg.sessions.stateDir "--config" (toString ( if cfg.sessions.configFile != null then cfg.sessions.configFile else sessionsConfig )) # Where the compositor's own session lives. The broker discovers the # `wayland-N` socket in there and hands XDG_RUNTIME_DIR / WAYLAND_DISPLAY # to every application it launches; the daemon was built to fail loudly # if this directory holds no usable socket. "--compositor-runtime-dir" runtimeDir ]; }; }; # ── the pointer driver ───────────────────────────────────────────── # # A third unit, and a third capability: this one injects input. It is a # separate process from the broker because a Wayland client needs its own # connection and a driver blocked on the compositor must not stall session # lifecycle (PLAN §6.5). It holds no lease -- the broker owns that -- so it # is an executor that can be restarted at any moment. systemd.services.hhstream-pointer = lib.mkIf (cfg.sessions.enable && cfg.sessions.pointer.enable) { description = "Pointer input driver for the headless Hyprland desktop"; wantedBy = ["multi-user.target"]; after = ["hyprland-headless.service"]; # `BindsTo` and not merely `After`: the driver's whole state is a Wayland # connection to that compositor, so when the compositor goes the driver # has nothing left to drive. The broker force-releases the lease when the # driver's socket stops answering, which is how the cursor comes back. bindsTo = ["hyprland-headless.service"]; environment = { PYTHONUNBUFFERED = "1"; }; serviceConfig = { Type = "simple"; User = cfg.sessions.user; # The compositor's runtime directory is 0750 and owned by this group, # and the driver is a Wayland client of it: without the group it cannot # open wayland-N at all. Same reason the broker has it, one step # further -- the broker only needs to *find* the socket for the # applications it launches, the driver has to connect to it itself. SupplementaryGroups = [cfg.sessions.group]; # No `RuntimeDirectory`: /run/hhstream belongs to the broker's unit and # to the tmpfiles entry above, and a second RuntimeDirectory= on the # same path would delete the broker's control socket when this unit # stopped. WorkingDirectory = brokerRuntimeDir; UMask = "0007"; Restart = "on-failure"; RestartSec = 1; NoNewPrivileges = true; # The same reasoning as the broker's, for the same reason: a driver # restart must not take sessions down. The applications the broker # launched are in the broker's cgroup, not this one, so `control-group` # would not reach them today -- but this unit is `After=` the # compositor and shares the broker's account, and KillMode=process says # plainly that stopping the driver stops the driver and nothing else. KillMode = "process"; # Frozen in docs/CONTRACT-sessions.md §3.4, word for word. The driver # defaults to both of these paths anyway; they are passed explicitly # because the contract specifies the command line, and a unit that # relied on the defaults would stop matching it the moment either # default moved. ExecStart = lib.escapeShellArgs [ (lib.getExe' cfg.package "hhstream-pointer") "--socket" pointerSocket "--compositor-runtime-dir" runtimeDir ]; }; }; }; }