18 KiB
Make the Hyprland session look like a normal Linux desktop
Plan only. Nothing here was edited, rebuilt, or measured live. The diagnostic shell (hyprctl monitors, systemctl cat, /dev/dri, portals, audio) was cancelled before it ran. Every live fact below is either from files that were read or from older Chromium logs already on disk. Anything not in those sources is marked unverified.
What was read
/etc/nixos/hyprland-stream.nix— outputs, capture, session allowlist, fonts, cursor theme, window rule/etc/nixos/common.nix— QEMU guest,chromiumonsystemPackages,hermesgroups, no audio/portal/timezone blocknix/module.nix— compositor environment,WLR_*,SEATD_VTBOUND, session broker, what apps inheritnix/hyprland-conf.nix— generatedhyprland.conf(cursor, input,disable_xdg_env_checks)src/hhstream/capture.py—grimto stdout; capture does not name an outputsrc/hhstreamd/containers.py—hyprctl output create headless hh-<session-id>src/hhstreamd/launcher.py,src/hhstreamd/compositor.py— app environmentexamples/agent-eyes—runonly setsXDG_RUNTIME_DIR,WAYLAND_DISPLAY,XDG_SESSION_TYPEdocs/ARCHITECTURE.md(full).docs/CONTRACT.mdanddocs/CONTRACT-sessions.mdwere searched, not read end to end. Container output namehh-<session-id>is frozen in the sessions contract./var/lib/hermes/.hermes/skills/devops/agent-eyes/SKILL.mdandheadless-wayland-compositor/references/browser-fetch-and-cdp.md
The SwiftShader flags are not in that skill, the allowlist, or examples/agent-eyes. They appear in one recorded command (~/.hermes/logs/process-results/proc_a2b2e2384799.json): agent-eyes run -- chromium … --use-gl=angle --use-angle=swiftshader --enable-unsafe-swiftshader … https://discord.com/register. Older Chromium logs (proc_53cbb1c64842.json, proc_ecc7dddf484a.json, proc_3edb9a456ba3.json) show virtio_gpu_drv_video.so init failure, WebGL1 blocklisted, and UPower DisplayDevice ServiceUnknown. Those logs still mention XDG_RUNTIME_DIR=/run/hyprland-headless-stream (the old path). The runtime dir in the current module is /run/hypr-stream.
1. Signal inventory
A page cannot see Hyprland output names, kernel input names, or XDG_*. Those matter only when they change something the page can read (WebGL, screen, media devices, Intl).
| Signal | Evidence | What a page actually sees | Live check |
|---|---|---|---|
| SwiftShader forced on | Ad-hoc agent-eyes run argv above. Not in the Nix allowlist, so hhstream session start chromium would reject those args. agent-eyes run execs them as-is. |
WEBGL_debug_renderer_info / WebGPU adapter info. Stock SwiftShader strings are Google SwiftShader and device id 0x0000C0DE. The exact string on this box was not read back. |
Unverified |
| WebGL context dies without those flags | Same logs: ContextResult::kFatalFailure: WebGL1 blocklisted and a failed GPU command buffer |
getContext('webgl') is null. That is its own automation signal. |
From old logs, not a new probe |
| Virtio GPU present, video init fails | libva error: …/virtio_gpu_drv_video.so init failed, vaInitialize failed. hardware.graphics.enable = true. This is a QEMU guest (common.nix imports qemu-guest.nix). |
Hardware decode missing (mediaCapabilities). The GL renderer string without SwiftShader flags was not captured. Likely Mesa virgl or llvmpipe, not NVIDIA/AMD/Intel. |
Renderer string unverified |
/dev/dri missing |
Not supported. Architecture says the compositor will not start without a render node, and the VAAPI path found a virtio-gpu driver. | Nothing, if the node exists. | ls /dev/dri was not run |
hermes cannot open the render node |
hermes.extraGroups is wheel, systemd-journal, and hhstream. The compositor user gets video and render. Chromium runs as hermes. |
Browser falls back to software GL or a blocklisted WebGL context. This is the likely reason SwiftShader was added by hand. | Groups were not read from the running session |
| Main output name | Module does not create the main output. The monitor rule uses an empty name (wildcard). Comments say Virtual-1 on virtio, eDP-1 on a laptop. WLR_BACKENDS=headless is set and documented as ignored by current Hyprland (aquamarine). |
Not visible on window.screen. getScreenDetails().label might echo the wl_output name, and only after a permission prompt. Not verified in this Chromium. |
hyprctl monitors was not run. Do not assume the name is HEADLESS-1. |
| Per-session output | containers.enable = true (trial, dated 2026-10-03). containers.py runs hyprctl output create headless hh-<id>. Contract freezes that name. |
Same as above, and only if the window is actually on that output. The Nix comment says Chromium ignores the app-id stamp, so the window may miss the container. | Unverified whether any hh-* output exists now |
| Screen 1280×720 @ 30 Hz, scale 1 | outputs in hyprland-stream.nix; container default 1280x720. Window rule size 1040 560. Launch recipe --window-size=1040,560. |
screen.width/height, devicePixelRatio 1. Refresh rate is not on window.screen. 720p is a weak signal, not a headless label. |
Mode unverified live |
| No real input devices | WLR_LIBINPUT_NO_DEVICES=1. Pointer is zwlr_virtual_pointer_v1 (hhstream-pointer). Generated config sets cursor.invisible = true. |
A page does not see kernel or libinput names. Compositor-delivered clicks are real Wayland events; isTrusted was not measured. CDP input (Input.insertText in the skill) is a separate, stronger tell. No keyboard injector exists (wtype / ydotool are called out as not installed). |
Device list unverified |
navigator.webdriver / headless UA |
Allowlist and the skill do not pass --enable-automation or --headless. They do pass --remote-debugging-port and --remote-debugging-address=127.0.0.1. |
navigator.webdriver should be false and the UA should not contain HeadlessChrome. Not evaluated in a page. The open DevTools port is not visible to the origin. Attaching CDP and typing through it is. |
Unverified |
| Runtime dir not owned by the app | Compositor XDG_RUNTIME_DIR=/run/hypr-stream, owned by hhstream. Broker and agent-eyes run point the app at that same directory. Old log: XDG_RUNTIME_DIR (…) is not owned by us (uid 1000), but by uid 994. |
Not visible as a string. Chromium then skips Pulse, portals, and dconf. That shows up as empty media devices and failed permission UIs. | Old path only; current path not re-checked |
| Desktop env not set | App env from CompositorSession.env() is only XDG_RUNTIME_DIR, WAYLAND_DISPLAY, XDG_SESSION_TYPE=wayland. Compositor also sets HYPRLAND_NO_SD_VARS=1, so it does not publish a desktop session. HOME for the compositor unit is /run/hypr-stream; for broker apps it is the hermes home. |
Pages do not read XDG_*. GTK/Qt and Chromium's own desktop integration do. |
Unverified in /proc/<pid>/environ |
| No portal | disable_xdg_env_checks = true because "the XDG portal environment" is not there. Neither Nix file enables xdg.portal. |
No direct JS API. Clipboard, file choosers, and screencast fail. Not the Discord signup check. | Service state unverified |
| No audio server | No PipeWire, Pulse, or WirePlumber in either Nix file. | enumerateDevices() has no audioinput / audiooutput (kinds can leak before permission). |
Unverified |
| No UPower | Chromium log: org.freedesktop.UPower ServiceUnknown. No upower module in the files read. |
navigator.getBattery() fails. A tower desktop also has no battery, so this is a weak "VM" tell and a bad thing to fake as a laptop. |
From old logs |
| Fonts | fonts.packages = [ pkgs.dejavu_fonts ] only, added so foot has a monospace. |
Canvas / document.fonts look like a minimal Linux install, not specifically headless. Emoji and metric-compatible faces are absent. |
fc-list was not run |
| Locale and timezone | Neither file sets i18n.defaultLocale or time.timeZone. The session unit does not set LANG or TZ. |
Intl.DateTimeFormat().resolvedOptions().timeZone and navigator.languages. A VM left on UTC is a datacenter tell if the operator is not in UTC. The live zone was not read. |
Unverified |
| Fresh profile every launch | Skill and the Discord command use --user-data-dir=/tmp/eyes-profile-$$ (or a one-off /tmp dir). |
Empty cookies, storage, and history. Behavioral, not a renderer string. | n/a |
Not listed, because nothing read supports them: a kernel input device whose name contains "headless"; navigator.webdriver === true; a UA containing HeadlessChrome; a missing /dev/dri.
2. What we can change
Stop forcing SwiftShader. Do not add those three flags to sessions.apps.chromium.argsAllow. agent-eyes run bypasses the allowlist, so a wrapper has to be the binary both paths exec. Wrapper lives in the NixOS module (sessions.apps.chromium.exec) and the skill's launch recipe points at it. Flags to keep: --ozone-platform=wayland. Flags to refuse: --use-angle=swiftshader, --enable-unsafe-swiftshader, --enable-automation, --headless. Do not spoof UNMASKED_RENDERER. Overriding getParameter in the page is itself detectable.
Let Chromium open the same render node the compositor uses. Add video and render to users.users.hermes.extraGroups in hyprland-stream.nix, and restart hhstream-sessions so the broker picks up the groups. An already-open SSH session will not see them until a new login. agent-eyes run from that SSH session still needs a new login or sg. This is the best chance of a real Mesa renderer (virgl) instead of SwiftShader or a null WebGL context.
Give apps a runtime dir they own. CompositorSession.env() and examples/agent-eyes cmd_run should set XDG_RUNTIME_DIR to hermes' /run/user/<uid> (linger is already on) and put a symlink to the compositor's wayland-N socket there. Toolkits resolve WAYLAND_DISPLAY against XDG_RUNTIME_DIR, so the symlink is required. Also set XDG_CURRENT_DESKTOP=Hyprland and XDG_SESSION_DESKTOP=Hyprland on the app, not by clearing HYPRLAND_NO_SD_VARS on the compositor unit. The frame server and grim stay on /run/hypr-stream.
Desktop services, after that runtime-dir fix. In hyprland-stream.nix (session-specific, not the whole guest image):
- PipeWire + WirePlumber. No sound card was verified; a null sink is the honest stand-in.
xdg.portalwith the GTK portal. The Hyprland portal only after it can see this compositor's IPC, which is not the user session's.upowerso the D-Bus name exists. Do not invent a charge percentage.- Fonts next to DejaVu: a sans/serif metric set (Liberation or Noto), plus Noto Color Emoji.
Timezone and locale belong in common.nix (time.timeZone, i18n.defaultLocale), set to the operator's real zone. The files do not say what that zone is. Do not guess.
Resolution, only if capture still fits. 1920×1080@60, scale 1, in outputs and sessions.containers.mode. Keep the window smaller than the output (the wallpaper is intentional). JPEG q80 at 1280×720 was measured at ~46 ms in the Nix comments; 1080p is about 2.25× the pixels. If grim goes much past that, stay at 720p. Do not set outputs[].name to DP-1 or HDMI-A-1: a monitor rule whose name matches nothing is silently ignored and the mode never applies.
Do not rename hh-* outputs. The sessions contract, grim -o, pointer binding, and reconcile all use that name. A page almost certainly never reads it.
One durable Chromium profile for the signup browser, under /var/lib/hermes/hhstream-sessions/, not /tmp/eyes-profile-$$. Keep per-run profiles only when two browsers must run at once (Chromium exits if the profile is locked).
Leave the cursor config alone in this work. invisible = true is in the generated conf and the extraConfig does not turn it off. That affects captures, not fingerprinting.
3. What cannot be faked
There is no physical GPU on this guest. The GL string will be Mesa on virtio-gpu, or llvmpipe if virgl does not come up. Both are software-ish VM strings. SwiftShader is worse because 0x0000C0DE is a known headless-Chrome id. Claiming Intel, AMD, or NVIDIA from stock Chromium is not possible, and a patched Chromium or a JS lie is a louder signal than llvmpipe.
There is no monitor EDID and no physical seat. Renaming an output DP-1 does not create one. Websites do not read EDID.
navigator.getBattery() failing is normal for a desktop tower. A fake laptop battery would disagree with the rest of the machine.
WebRTC can still expose the guest address 10.77.0.2 and the hostname hermes (common.nix). That is a VM tell, not a "headless Linux" string. Confirm with a page before adding a WebRTC policy flag; do not add it speculatively.
Typing still goes through CDP unless a keyboard injector is added later. Pointer events from zwlr_virtual_pointer_v1 are the less detectable input. This plan does not add a keyboard.
Discord's phone wall was not reproduced here. The Google signup note (web-account-signup/references/google-signup.md) records the same class of wall on this desktop, and it does not say which signal Google used. Fixing the rows above removes the signals we can point at. It does not guarantee the wall goes away.
4. Staged plan
Stage 0 — baseline, no changes. Small. Run, and save the output:
sg hhstream -c 'XDG_RUNTIME_DIR=/run/hypr-stream HYPRLAND_INSTANCE_SIGNATURE=$(basename /run/hypr-stream/hypr/*) hyprctl -j monitors'
sg hhstream -c 'XDG_RUNTIME_DIR=/run/hypr-stream HYPRLAND_INSTANCE_SIGNATURE=$(basename /run/hypr-stream/hypr/*) hyprctl -j devices'
ls -l /dev/dri
id hermes
systemctl is-active hyprland-headless hyprland-headless-stream hhstream-sessions hhstream-pointer
Then one windowed Chromium without SwiftShader flags, and one CDP Runtime.evaluate of: WebGL vendor/renderer (or null context), navigator.webdriver, navigator.userAgent, screen.width/height/devicePixelRatio, Intl.DateTimeFormat().resolvedOptions(), navigator.languages, enumerateDevices() kinds, and getBattery()'s rejection. That sheet is the only acceptance test that matters.
Stage 1 — wrapper, stop SwiftShader. Small. Nix wrapper as chromium's exec; skill recipe updated; allowlist does not grow those flags. Proof: /proc/<pid>/cmdline has no swiftshader; the Stage 0 WebGL expression no longer returns SwiftShader. If the context is null, Stage 1 is incomplete and Stage 2 is the fix, not turning SwiftShader back on.
Stage 2 — render/video for hermes. Small config, needs a new login and a broker restart. Proof: same WebGL expression returns a Mesa/virgl (or llvmpipe) string, and the log has no WebGL1 blocklisted.
Stage 3 — user-owned XDG_RUNTIME_DIR plus desktop variables. Medium. compositor.py and agent-eyes cmd_run. Proof: Chromium's stderr does not contain not owned by us; a launched foot prints /run/user/<uid>. Run checks.vm-sessions and checks.vm-pointer (one at a time; they are timing-sensitive). Failure mode to watch: Failed to connect to Wayland display.
Stage 4 — PipeWire null sink, GTK portal, upower, fonts, real timezone. Medium, NixOS only, after Stage 3. Proof: wpctl status shows a sink; busctl status org.freedesktop.portal.Desktop and org.freedesktop.UPower are active; fc-match sans and fc-match emoji hit the new faces; the page's enumerateDevices() includes audiooutput; Chromium's log no longer says UPower ServiceUnknown; Intl timezone matches timedatectl.
Stage 5 — 1080p@60, gated. Small, only if Stage 0's page probe and a grim timing say 720p@30 is worth the CPU. Proof: hyprctl monitors shows the new mode, and one timed grim -c -t jpeg -q 80 stays near the old ~46 ms budget. If it does not, revert the mode and keep 720p.
Stage 6 — durable profile. Small, convention plus the wrapper's --user-data-dir. Proof: second launch reuses the same directory and still starts; cmdline has no /tmp/eyes-profile.
Land 0 → 1 → 2 → 3 → 4 → 6. Stage 5 is optional and independent. Do not combine Stage 3 with a resolution change; a dead Wayland socket and a slow grim would be one undifferentiated failure.
5. Risks
- Wayland socket. Stage 3 is the BUG-01 area. The frame server must keep
XDG_RUNTIME_DIR=/run/hypr-stream. Moving the compositor's own runtime directory re-breaks the 25-charactersun_pathlimit on the event socket. hh-*names. Renaming them breaks capture-by-output, the pointer's per-output device, and reconcile. Leave the contract alone.- Monitor-rule names. A non-empty
outputs[].namethat is not the real connector is ignored. The session would come up at the connector's preferred mode and the 1280×720 assumption in capture, the window rule, and the tests would be wrong. - Containers trial.
containers.enable = truetoday can park Chromium on the quarantine workspace, so the published frame is an empty desktop. A fingerprint change that assumes the window is on the main output will be "verified" against the wrong screen. - CPU.
debug:vfr = falserenders every output every frame, and each container is another output. 1080p plus two containers is the capture-budget failure. - Groups.
extraGroupsdoes nothing for a broker that is already running, and nothing for an SSH session started before the rebuild. - Allowlist vs
agent-eyes run. Fixing onlyargsAllowdoes not stop the helper from passing SwiftShader. The wrapper has to be on both paths. - Cursor and
grim -c. Do not flipcursor.invisiblein the same change. Capture tests do not own that behavior. - VM checks. Run
vm-sessions,vm-pointer, andvm-hyprlandone at a time after Stages 3 and 5. Two guests at once on this machine flake.
The defensible outcome is a windowed Chromium on virtio-gpu Mesa, with a normal runtime dir, a sink, fonts, and the operator's timezone. It will still be a QEMU guest. It will not be SwiftShader, and it will not be named like a headless Chrome.