`packages.hhstream-mcp` (`nix/mcp.nix`), separate from `packages.hhstream` and the separation is the point: the frame socket, the CLI and the broker are stdlib-only by policy, the MCP SDK is a third-party dependency, and `packages.hhstream` runs as the compositor's own units. Verified: the hhstream closure gains no `mcp`, no `pydantic` and no `httpx`, and `hhstream_mcp` is not in its site-packages. The join to `hhstream` is a *library* one -- `toPythonModule`, because the tools call `hhstream.cli`'s handlers in process. `grim` and `ffmpeg` are prefixed onto the wrapper's PATH, because the CLI spawns them and the server is launched by an MCP client whose PATH is not ours to predict. The entry point is smoke-tested with `--list-tools` in a `postPhases` phase, not `postInstall`: the script is wrapped in `fixupPhase`, so any earlier and the check runs against a script with no PYTHONPATH and tests the wrong thing. (`installCheckPhase` is no use either -- `buildPythonPackage` does not include that phase at all.) `services.hyprland-headless-stream.mcp.enable` (default false) puts the binary on the system PATH, which is the whole of the option: the server is stdio and spawned per client, so there is no unit, no socket and no state directory. `mcp.package` defaults to this flake's build against `cfg.package`, so the server and the CLI it runs are one build. A warning, not an assertion, when it is enabled with `sessions.enable` off: 22 of the 26 tools then answer exit 5, but the four frame tools are genuinely useful alone. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011ZeH65zd6pFTgBSu52W9PE
1240 lines
53 KiB
Nix
1240 lines
53 KiB
Nix
{
|
|
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:
|
|
#
|
|
# <runtimeDir>/hypr/<HYPRLAND_INSTANCE_SIGNATURE>/.socket.sock requests
|
|
# <runtimeDir>/hypr/<HYPRLAND_INSTANCE_SIGNATURE>/.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 = <name>, <width>x<height>@<refresh>, auto, <scale>` 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-<session-id>` 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-<id>` 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 keyboard has no `enable` of its own: it is the same unit, the same
|
|
# process and the same lease as the pointer (`hhstream session keyboard
|
|
# …` refuses with exit 9 until `pointer acquire`). What it needs from an
|
|
# operator is a layout, because the keymap the driver uploads is the only
|
|
# thing that decides which keycode a keysym is -- Hyprland's own
|
|
# `input:kb_layout` is not read and does not affect injected keys.
|
|
keyboard = {
|
|
layout = lib.mkOption {
|
|
# `strMatching` and not `str`, and the pattern is the point: it is
|
|
# what refuses `us,ru`. A comma-separated layout compiles perfectly
|
|
# well into a two-group keymap, and v1 sends `group = 0` in every
|
|
# `modifiers` request -- so the second group would be unreachable and
|
|
# an agent asking for a Cyrillic character would silently get a Latin
|
|
# one. The driver refuses a comma too, for a binary run by hand.
|
|
type = lib.types.strMatching "[A-Za-z0-9_-]+";
|
|
default = "us";
|
|
example = "de";
|
|
description = ''
|
|
XKB layout the `hhstream-pointer` unit compiles once at start-up and
|
|
uploads as its virtual keyboard's keymap (rules `evdev`, model from
|
|
{option}`sessions.keyboard.model`).
|
|
|
|
**This is the only thing that decides what an injected key means.**
|
|
Every `hhstream session keyboard` verb names an XKB *keysym*
|
|
(`a`, `A`, `Return`, `Control_L`), and the driver resolves that name
|
|
against this keymap to get the evdev code and the modifier mask the
|
|
compositor is sent. A character this layout cannot produce is
|
|
refused with exit 2 and nothing is typed -- there is no partial
|
|
type, so `é` on `us` fails the whole string rather than the letter.
|
|
|
|
Hyprland's `input:kb_layout` is **not** read. It describes the
|
|
layout for physical keyboards, of which a headless session has none,
|
|
and reading it would mean a `hyprctl` reload could silently change
|
|
what every agent types. One group only: see the type.
|
|
'';
|
|
};
|
|
|
|
model = lib.mkOption {
|
|
type = lib.types.strMatching "[A-Za-z0-9_-]*";
|
|
default = "pc105";
|
|
description = ''
|
|
XKB model for the same keymap. `pc105` unless an operator knows
|
|
otherwise; it decides little beyond which keys exist at all.
|
|
'';
|
|
};
|
|
|
|
variant = lib.mkOption {
|
|
type = lib.types.str;
|
|
default = "";
|
|
example = "intl";
|
|
description = ''
|
|
XKB variant, empty by default.
|
|
|
|
Worth knowing before setting one: a variant whose characters are
|
|
**dead keys** -- `us(intl)`'s accents, for instance -- cannot be
|
|
typed by this version. A dead key is half of a compose sequence and
|
|
v1 emits one event per character, so the driver refuses the name
|
|
rather than arming the next keystroke in the focused application.
|
|
'';
|
|
};
|
|
|
|
options = lib.mkOption {
|
|
type = lib.types.str;
|
|
default = "";
|
|
example = "ctrl:nocaps";
|
|
description = ''
|
|
XKB options, empty by default. Passed through to
|
|
`xkb_keymap_new_from_names`; a value it rejects stops the driver
|
|
with exit 2 before it connects to the compositor, so a typo here is
|
|
a failed unit rather than a session that types the wrong thing.
|
|
'';
|
|
};
|
|
};
|
|
|
|
# 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.
|
|
'';
|
|
};
|
|
};
|
|
|
|
# The Model Context Protocol server -- `hhstream-mcp`, the `hhstream` CLI
|
|
# as typed tools, so an agent drives this desktop without shelling out.
|
|
#
|
|
# Its own top-level block rather than one under `sessions`, because it is
|
|
# not the broker's: four of its tools (`status`, `shot`, `record`, `run`)
|
|
# are frame-socket verbs that work with the broker switched off. It is also
|
|
# not a unit. The transport is stdio, one process per client, spawned by
|
|
# whichever client wants it -- so "installing" it means exactly putting the
|
|
# binary on PATH, and anything that started a daemon here would be
|
|
# inventing a second thing to supervise.
|
|
mcp = {
|
|
enable = lib.mkOption {
|
|
type = lib.types.bool;
|
|
default = false;
|
|
description = ''
|
|
Put `hhstream-mcp` on the system PATH, so an MCP client on this
|
|
machine can spawn it.
|
|
|
|
Off by default, and deliberately not implied by
|
|
{option}`sessions.enable`: this is the surface through which a
|
|
language model starts applications, clicks and types on this desktop,
|
|
and whether that is wanted is a decision, not a consequence of the
|
|
broker being up. Installing it starts nothing — the server is stdio
|
|
and short-lived, spawned per client — and it grants no access the
|
|
`hhstream` CLI does not already grant to whoever runs it.
|
|
|
|
The client configures the sockets through the CLI's own environment,
|
|
`HHSTREAM_SOCKET` and `HHSTREAM_FRAME_SOCKET`; see the README section
|
|
on registering it.
|
|
'';
|
|
};
|
|
|
|
package = lib.mkOption {
|
|
type = lib.types.package;
|
|
description = ''
|
|
The MCP server package. Defaults to this flake's `hhstream-mcp`,
|
|
built against {option}`package` so the server and the CLI it drives
|
|
are the same build.
|
|
'';
|
|
};
|
|
};
|
|
};
|
|
|
|
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 <runtime dir>/hypr/<instance signature>/.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 {});
|
|
|
|
# Built against `cfg.package`, so the server and the CLI it runs are one
|
|
# build: the tools are argv lists against that CLI's parser, and a server
|
|
# paired with a different one would refuse flags for reasons no agent could
|
|
# read. `mkDefault` for the same reason as above.
|
|
services.hyprland-headless-stream.mcp.package =
|
|
lib.mkDefault (pkgs.callPackage ./mcp.nix { hhstream = cfg.package; });
|
|
|
|
# Installing it IS the whole of `mcp.enable`: the server is spawned by a
|
|
# client over stdio, so there is no unit, no socket and no state directory
|
|
# to declare.
|
|
environment.systemPackages = lib.mkIf cfg.mcp.enable [ cfg.mcp.package ];
|
|
|
|
# A warning and not an assertion: twenty-two of the twenty-six tools need
|
|
# the broker, and an agent handed them against a machine where it is off
|
|
# gets exit 5 from every one of them -- which is a true answer, badly
|
|
# timed. The four frame tools are genuinely useful on their own, so this is
|
|
# a thing worth saying rather than a thing worth refusing.
|
|
warnings = lib.optional (cfg.mcp.enable && !cfg.sessions.enable) ''
|
|
services.hyprland-headless-stream.mcp.enable is on while sessions.enable
|
|
is off: the MCP server's session, pointer and keyboard tools will all
|
|
fail with exit 5 (the broker is unreachable). Only status, shot, record
|
|
and run will work.
|
|
'';
|
|
|
|
# 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";
|
|
|
|
# The first two flags are frozen in docs/CONTRACT-sessions.md §3.4,
|
|
# word for word. The driver defaults to both of those 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.
|
|
#
|
|
# The four XKB flags are the **only** path a layout has to the uploaded
|
|
# keymap, and that is worth being blunt about: the broker's TOML has a
|
|
# `[pointer]` table that `hhstreamd` reads for its lease numbers, and
|
|
# this is a different unit that never opens that file. A `[keyboard]`
|
|
# table there would be a setting an operator could change while every
|
|
# injected key stayed on `us`.
|
|
ExecStart = lib.escapeShellArgs [
|
|
(lib.getExe' cfg.package "hhstream-pointer")
|
|
"--socket"
|
|
pointerSocket
|
|
"--compositor-runtime-dir"
|
|
runtimeDir
|
|
"--xkb-layout"
|
|
cfg.sessions.keyboard.layout
|
|
"--xkb-model"
|
|
cfg.sessions.keyboard.model
|
|
"--xkb-variant"
|
|
cfg.sessions.keyboard.variant
|
|
"--xkb-options"
|
|
cfg.sessions.keyboard.options
|
|
];
|
|
};
|
|
};
|
|
};
|
|
}
|