linux: put the service user in the render group, so the engine can open an AMD or Intel GPU (#1535)

[gen16k]

Why

The inference engine is started by the daemon as its child (internal/runtime/spawner_unix.go, with no credential change), so on Linux it runs as waired.

On Debian and Ubuntu, /dev/dri/renderD* and /dev/kfd are 0660 root:render. Both distributions build systemd with -Dgroup-render-mode=0660; upstream's default is 0666. The engine needs these nodes for AMD GPUs (ROCm or Vulkan) and Intel GPUs (Vulkan). Without the render group it cannot see such a GPU, and it runs on the CPU without saying why.

#1466 (for #459) had decided not to grant the group, so as not to add a standing privilege for a fact that never changes. That decision considered only the profiler's reading; the engine needs the node for every computation.

What changes

• Install paths
  • packaging/debian/waired/postinst runs usermod -a -G render waired on every configure, when the group exists. An upgrade therefore fixes an existing install; the existing restart picks the group up.
  • waired-agent install does the same through ensureGPUGroups (internal/platform/service/service_linux.go). Which groups to join, and how, are both passed in, so the table test drives the real function.
  • usermod is declared in scripts/ci/lookpathguard/exemptions.go.
• render only, never video (owner decision, 2026-09-22). video also opens cameras (/dev/video*) and the display (/dev/dri/card*), and computing does not need it on the supported distributions.
• No SupplementaryGroups= in the unit.
  • Naming a group the host lacks stops the unit from starting (exit 216/GROUP).
  • systemd applies a User='s groups from the group database (systemd.exec(5)).
  • Comments in both unit sources say so, and a test keeps both units free of the directive.
• The sudo waired init reading (gpu-topology.json) stays as the floor for a host whose service user is not in the group. With the group, the daemon reads the FUSION bit and an Intel card's memory itself, and a live reading already wins. The product string unreadIntelMemoryReason is unchanged: it now shows only when the live read fails.
• Records
  • New decision docs/decisions/20260922/1430-linux-service-user-joins-render.md. It partly supersedes 20260920/2000 (only the "do not grant render" sentence), with links both ways.
  • Corrections in place in knowledge notes 2100, 1600 and 1700.
  • Comments corrected in internal/hardware, internal/runtime/state/gpu_topology.go, and both gpu_topology.go files under cmd/.
• Docs (en/ja)
  • troubleshooting/slow-or-wrong.md: the Linux paragraph now names the group, with id waired to check it and usermod to fix it. It replaces "memory can only be read with administrator rights".
  • getting-started/install/linux.mdx: a "Service user" row.
• installtest
  • assert_tier1 checks render membership where the guest has the group, and that video is absent.
  • assert_postinst_selfheal removes the group before dpkg-reconfigure and checks that it comes back.

Verification

• Local checks
  • go test ./...: exit 0.
  • golangci-lint: 0 issues on the touched packages (Linux).
  • GOOS=windows and GOOS=darwin go vet: OK. The GOOS=windows lint findings are all in files this PR does not touch.
  • install-script-lint (shellcheck and copy guard), decision-log-guard, hostname-guard, lookpathguard and npm run i18n:check: all OK.
• Mutations: 7 of 7 caught. Each of these makes a test fail:
  • joining an absent group;
  • adding video;
  • swallowing a failed join;
  • joining nothing;
  • a groupExists that is always true;
  • SupplementaryGroups= in the rendered unit;
  • SupplementaryGroups= in the packaged unit.
• Hardware. Linux, RTX PRO 4000 plus an AMD iGPU, Ubuntu 26.04, systemd 259, APT install. Details in Linux: the service user is not in the render group, so the engine cannot reach an AMD or Intel GPU #1535.
  • Before: the daemon ran with Groups: 117 (waired only). renderD128, renderD129 and /dev/kfd were denied to waired; /dev/nvidia* are 0666.
  • The product's ollama 0.34.0 run as waired on a spare port:
    • without the group, the AMD iGPU is not listed at all and nothing is logged;
    • with render and OLLAMA_IGPU_ENABLE=1, it appears as library=Vulkan … type=iGPU;
    • with render and the defaults, it is dropped (dropping integrated GPU) and CUDA serves. That is today's result, and waired's prediction still matches.
  • The branch's postinst, run twice as configure <installed version> (an upgrade): exit 0 both times; the restarted daemon ran with Groups: 117 991. The host was then restored (gpasswd -d waired render, restart, binaries unchanged by sha256).
• Not verified on hardware. Computing on an AMD discrete GPU, a Linux Strix Halo or an Intel Arc card: the fleet has none. Those stay with measure: AMD discrete GPUs on Linux and Windows — detection, gfx target, host key, and which backend the engine picks #1495, measure: Linux Strix Halo — sysfs detection, the KFD-pool budget, and the engine's own ROCm path #1496 and measure: Intel Arc discrete GPUs — the render-node memory query on Linux, the registry on Windows, and the host key #1497, which now say to check id waired first.

Other operating systems (cross-OS parity)

• macOS: the LaunchDaemon and the engine run as root; Metal under it was checked on hardware in macOS: the first start after the bundled ollama moves to a new version times out its GPU discovery, and that engine runs as a CPU host until it restarts #1521 and macOS: run the LaunchDaemon as a Standard job, not Background, so the engine's first Metal compile finishes inside ollama's GPU-discovery window (#1521) #1525.
• Windows: the service and the engine run as LocalSystem. NVIDIA supports CUDA from a service.
• Nothing to change on either. install.sh and install.ps1 are not touched: Linux installs go through the .deb.

Found alongside, not fixed here

Both are recorded in #1535 and #1534.

• ollama's Vulkan backend reads free VRAM only with CAP_PERFMON or as root, and NoNewPrivileges=yes also disables file capabilities. This affects Intel Arc, and granting a capability is a separate security decision.
• /dev/nvidia-uvm created on demand by the setuid nvidia-modprobe cannot be created under NoNewPrivileges=yes (inference: check whether Windows and Linux can fail first-start GPU discovery the way macOS did in #1521 (six unverified candidates) #1534 item 5).

Fixes #1535

🤖 Generated with Claude Code

https://claude.ai/code/session_01BviBGHJqCeM88hxCRYrtAg

[github-actions]

📘 Docs preview — the preview channel for this PR has been deleted now that it is closed.