Peripherals & Display (k8s-native design)

​

Why this document exists

​

The GPU reality (read this before anything else)

• i3 (kind=storage, 192.168.1.100) has the working /dev/dri — Intel HD 4400, card0 + renderD128, used by jellyfin for QuickSync. It has no attached screen that matters.
• i5 (kind=compute, 192.168.1.25) has the physical screen — the Dell Inspiron 5490 All-in-One (model W24C). It has its own iGPU (10th-gen-class, QuickSync-capable per the turn-13 spec recon), but no one has verified its /dev/dri / /dev/video* / /dev/input device layout in the k3s era. The jellyfin passthrough is on i3 and tells us nothing about i5’s device nodes.

​

Architecture at a glance

agent  --deploy-web-app-->  apps.augustin.ai/<x>   (Caddy, existing webapps box)
agent  --call-service (MQTT-bridge / HA) -->  mosquitto  topic: kiosk/show  {url:".../<x>"}
kiosk  <--subscribe--  mosquitto        ->  Chromium navigates to the URL on i5's panel
senses --MJPEG/PCM-->  (HA / agent)     ->  camera + mic as a passive feed and a callable input

​

1. Display / kiosk as a pod

​

The three hard problems and the proposed solutions

1. Rely on the headless OS. i5 ships with no display manager (OS + k3s only), so on boot nothing owns /dev/dri/card*. The kiosk pod’s cage becomes master unopposed. This is the clean path and it’s a consequence of the k3s-only rule — verify at bring-up that i5 has no getty on the console VT grabbing DRM and no plymouth/fbcon splash holding it.
2. VT/seat handoff. Run the compositor on a dedicated VT and mount /dev/tty0 + /dev/tty2 so cage can VT_SETMODE/KDSETMODE to take the console. seatd (a tiny seat manager) in the pod brokers device access without a full systemd-logind; mount /run/seatd.sock from a seatd sidecar or run seatd as the container’s init. cage supports libseat with the seatd backend, which is the lightest option that still does proper master arbitration.

​

Pod spec (described)

• nodeSelector: { kind: compute } — pin to i5 (the panel is there).
• strategy: { type: Recreate } — a rolling second pod would fight for DRM master; only one kiosk may exist. Same reasoning as the hostPort/Recreate rule for ingress.
• securityContext — the honest part. This pod is privileged or runs with a specific cap set (SYS_ADMIN for DRM ioctls/mode-setting, plus SYS_TTY_CONFIG for VT switching) and seLinuxOptions/seccompProfile: Unconfined if the compositor trips the default seccomp filter (mode-setting ioctls sometimes do — the same class of exception firefox needed seccomp:unconfined for). Start from the minimal set — SYS_ADMIN + SYS_TTY_CONFIG + the device mounts + seccomp: Unconfined — and only fall back to privileged: true if seatd-brokered access can’t get DRM master. Document whichever lands; do not leave it at blanket privileged if a cap set works.
• Device mounts (hostPath, all on i5, all VERIFY-FIRST):
  • /dev/dri → the GPU (KMS card* + render renderD*).
  • /dev/input → keyboard/mouse/touch (event*).
  • /dev/tty0 (+ a dedicated VT like /dev/tty2) → console/VT for master handoff.
  • /run/udev (readOnly) → libinput device discovery, if seatd alone isn’t enough.
• /dev/shm sizing — Chromium crashes on the default 64 MB shm (the exact trap firefox documents). Mount an emptyDir { medium: Memory, sizeLimit: 1Gi } at /dev/shm.
• No ingress, no Service. The kiosk is an output device, not a network service — nothing connects to it. It only makes outbound connections (subscribe to MQTT, fetch the app URL).
• Resources: request ~512Mi/250m, limit ~2Gi (a full Chromium + compositor; comparable to the browserless limit).
• Config: subscribe target (MQTT broker Service DNS), a default/idle URL to show when no event is pending (e.g. a clock/dashboard app on apps.augustin.ai), and screen resolution/rotation for the W24C panel.

​

The tradeoff vs. the shell-free / minimal-privilege ethos

​

2. Camera / mic sense layer as a pod

​

Pod spec (described)

• nodeSelector: { kind: compute } — the camera/mic are physically on the i5 AIO.
• securityContext: far lighter than the kiosk. V4L2 + ALSA generally need only the device mounts and a matching group (video, audio), not privileged and not SYS_ADMIN. Use supplementalGroups for the host video/audio GIDs (the pattern jellyfin uses with supplementalGroups: [992] for render). No net caps.
• Device mounts (hostPath, on i5, VERIFY-FIRST):
  • /dev/video0 (and any /dev/video1..N — UVC cameras expose two nodes, capture + metadata; mount the directory or enumerate) via type: CharDevice.
  • /dev/snd → the sound devices (directory).
• Service + no public ingress: expose the MJPEG stream on a ClusterIP Service (senses.peripherals.svc) so HA and the agent can read it in-cluster only. If a camera view ever needs to be shown, it’s shown through the kiosk (which fetches an apps.augustin.ai page embedding the stream) — the camera feed does not get its own public hostname.
• Device-plugin note: the “proper” k8s way to hand out /dev/video*//dev/dri is a device plugin (e.g. intel-gpu-plugin, or a generic k8s-device-plugin for hostPath devices) advertising intel.com/gpu / a video resource so pods request the device instead of hostPath-mounting it. That’s cleaner and schedules honestly, but it’s more moving parts for a single-node, single-device situation. Decision: start with hostPath (matches jellyfin, zero new infra) and only adopt a device plugin if a second consumer or a second GPU ever makes contention real. Don’t gold-plate a one-camera problem.

​

3. The push channel

​

mosquitto (broker)

• Deployment + PVC, nodeSelector: { kind: storage } (i3 — it’s stateful-ish: retained messages + a persistence file; pin it with the rest of the stateful data), Recreate.
• ClusterIP Service on 1883, in-cluster only (no ingress, no LoadBalancer — unlike the stalwart mail-port exception, nothing external needs MQTT).
• Auth: a username/password from a kubectl-created secret (secretKeyRef), never in git.
• runAsUser: 1000, minimal config ConfigMap (listener 1883, persistence on, one ACL: publishers can write kiosk/#, the kiosk subscribes kiosk/#).

​

The bridge — reuse call-service, don’t build a tool

1. HA as the bridge (preferred). Home Assistant (§4) speaks both MQTT and a REST API. The agent calls HA’s REST/webhook API via call-service (register HA in the service registry), and an HA automation republishes to the kiosk/show MQTT topic. One config entry, zero new agent tooling, and it makes “show X” a first-class HA action alongside every other device action.
2. A tiny MQTT-HTTP bridge pod (mqtt/http shim, e.g. a 20-line service exposing POST /publish {topic,payload} → MQTT) registered in call-service. Only build this if HA turns out to be the wrong hub. It’s the fallback, not the default.

​

4. Home Assistant headless / API-only

​

Pod spec (described)

• Deployment + PVC (/config — HA’s SQLite/state store), nodeSelector: { kind: storage } (i3, with the stateful data), Recreate, replicas: 1.
• Image: ghcr.io/home-assistant/home-assistant:stable.
• Network — the one wrinkle. HA’s device auto-discovery (mDNS/SSDP for smart-home gear) wants host networking or at least broadcast reach on the LAN. For an API/MQTT-only hub driving the screen, that discovery is not needed — so run it as a normal ClusterIP Deployment (no hostNetwork), talking to Mosquitto over the cluster network and to the agent over REST. If and when a real broadcast-discovered device is added, revisit hostNetwork: true (pinned to i3) as a scoped exception — but don’t take that networking hit speculatively. Document it as a known future edge.
• Config: the MQTT integration pointed at mosquitto.peripherals.svc, a long-lived access token (secret) for the agent’s call-service calls, and the kiosk/show automation from §3.
• No public ingress by default (agent reaches it in-cluster). If a debugging view of HA’s own UI is ever wanted, add an ingress behind the existing CF Access policy — but the product UI is the custom apps.augustin.ai app, per the framing.

​

5. How the agent drives it (no new tooling)

1. Content: the agent publishes a page with deploy-web-app → served by Caddy at apps.augustin.ai/<x> (turn 72, LOCKED). “Show me images of X” = generate a tiny gallery app, deploy-web-app it, done. No new content pipeline.
2. Command: the agent tells the screen what to show by call-service to HA (or the bridge), which publishes kiosk/show {url: "https://apps.augustin.ai/<x>"}. The kiosk pod, subscribed, navigates Chromium there.
3. Proactive: the agent can already reach out via ntfy (the mastra pod has NTFY_URL wired). “I put it on the screen” can also ping the phone with the same link — the surface is the screen and the notification, reusing the existing escalation path.
4. Camera as a tool: the senses pod’s in-cluster MJPEG/PCM endpoints are just more in-cluster services — reachable by call-service (HTTP) for a snapshot, or surfaced through HA as a camera entity. No bespoke “camera tool” needed; it collapses into the existing broad primitive, which is exactly the turn-91→95 direction (few broad primitives, not a per-device tool pile).

​

Phasing

• P0.1 — Re-establish i5 bring-up access. ssh i5 is unwired (verified: from pentium, ssh i5 → “Could not resolve hostname i5”). i5 is a live k3s node at 192.168.1.25 (verified: kubectl get nodes shows i5 Ready, kind=compute, Debian 13, kernel 6.12.94), but there is no working shell path to it from the bastion for device inspection or console work. Restore a reachable, authenticated path to i5 (fix the ~/.ssh/config host entry / mesh name resolution) before touching hardware. This document could not enumerate i5’s devices for exactly this reason — treat every device path below as unconfirmed.
• P0.2 — Verify i5’s /dev/dri. Confirm card* (KMS/scanout) and renderD* exist and which VA driver the 10th-gen iGPU uses (iHD vs i965). The jellyfin manifest is on i3 and tells us nothing about i5. Without this, the kiosk manifest is a guess.
• P0.3 — Verify i5’s /dev/video* and /dev/snd. Confirm the AIO webcam enumerates (UVC → /dev/video0+) and the mic/speakers appear under /dev/snd`.
• P0.4 — Verify i5 holds no DRM master at boot. Confirm the headless OS truly leaves /dev/dri/card* free — no gdm/Xorg/getty-on-console/plymouth grabbing it. This is the assumption the whole kiosk rests on; the “OS + k3s only” rule should guarantee it, but verify, don’t assume.
• P0.5 — W24C panel/touch/backlight verify (the standing turn-79 TODO). Confirm the Dell W24C’s touch SKU, panel native resolution/rotation, and that backlight control works headless (some AIO panels need a kernel video=/i915 quirk). Touch drives whether we mount /dev/input for a touchscreen and whether calibration is needed.

​

Risks — where k8s-native is genuinely harder

• DRM master in a container is the real risk. On a headless host it should work (nothing competes), but the failure modes are nasty and remote-debuggable only up to a point: if cage can’t take master you get a black screen with no network symptom, and diagnosing it means console access to i5 (which, per P0.1, isn’t even wired yet). A host process hitting the same problem is debuggable over plain SSH with journalctl; a pod adds a container/seat layer between you and the DRM error. This is strictly harder than host-native, and it’s the single most likely place the build stalls.
• Seat management without systemd-logind. Containers don’t have the host’s logind seat. seatd is the answer and it works, but it’s one more in-pod daemon to get right, and libseat backend selection (seatd vs logind vs builtin) is fiddly. Host-native cage under the host’s seatd/logind is a documented, common setup; in-pod is comparatively uncharted.
• Single-display arbitration. Only one DRM master, ever. The Recreate strategy enforces one pod, but a crash-looping kiosk that grabs-and-releases master can wedge the console; and if P0.4 is wrong (something does hold master at boot), the pod never starts cleanly. A host process has the same constraint but a simpler recovery (restart the unit).
• securityContext cost. This pod is the least-privilege ethos’s worst citizen (privileged or SYS_ADMIN+SYS_TTY_CONFIG+seccomp: Unconfined+broad device hostPaths). We contain it (own namespace, no API access, no inbound port), but it’s a real expansion of the fleet’s privileged surface — from “beszel reads /sys” to “a pod owns the console.”