SmartestHome/hosts/steam-tv-box

Steam TV box

A living-room machine that boots straight into Steam Big Picture and runs games locally — real GPU, real CPU, games installed on this box. When you leave Big Picture it becomes the same media station as every other monitor client in the house: Spotify, a browser with uBlock Origin, and a general mp3/mp4 player.

This is not the thin client. hosts/thin-client/ runs Steam Link, which streams a game rendered on some other PC and needs no graphics performance at all. This image is the other end of that: it is the machine that renders. Different distro release, different driver stack, different session.

What ends up on the image:

Compositor	Sway, no bars, no lock screen, workspaces 1:steam / 2:games / 3:web / 4:media / 5:music
Autologin	greetd, default_session straight into /usr/local/bin/kiosk-session
Default app	Steam Big Picture (-gamepadui), under gamescope when available
Gaming	Native steam-installer + i386 multiarch + full Mesa/Vulkan stack, steam-devices udev rules, gamemode, MangoHud
Minecraft	Prism Launcher (Flathub), registered as a non-Steam game so it runs through Steam with Steam Input live
Browser	Firefox ESR, minimal chrome, uBlock Origin + SponsorBlock force-installed
Music	Spotify (Flathub, the real GUI client)
Player	mpv + mpv-mpris, opened idle on 4:media
Audio	PipeWire/WirePlumber, persistent output selection from HA
Remote control (human)	wayvnc on 0.0.0.0:5900, authentication required, fails closed
Remote control (HA/LLM)	steamtv-agent, a systemd service publishing HA MQTT-discovery entities
TV power	HDMI-CEC (cec-ctl) + Sway DPMS, driven by HA presence
Debian release	trixie, not the household default — see below

The one design decision worth reading

The media apps do not exist until you leave Big Picture.

The box boots to Steam and nothing else. No Firefox, no Spotify, no mpv. They are started the first time somebody actually leaves Big Picture, and they stay up from then on.

That is not tidiness. This is the only machine in the project where a background browser and a background Electron app cost something you can see: they hold GPU memory, they wake the CPU on timers, and Spotify keeps an audio stream open that turns up as stutter in a title that is already frame-limited. A gaming session should not pay for media features it is not using.

There are two triggers, because there are two different ways to leave and neither one can see the other:

Way out	What notices	File
"Exit Steam", or the client crashing	steam-big-picture runs in the foreground; when it returns, the wrapper carries on to the next line	configs/session/steam-session
"Exit Big Picture mode", alt-tab, the remote's channel keys, HA's Screen select	a sway IPC subscription to workspace-focus events	configs/session/session-watcher

Both call media-session start, which is idempotent — every launch is guarded by its own pgrep and the whole path holds an flock — so whichever fires first wins and the second is free. Leaving and re-entering Big Picture repeatedly costs three pgreps.

Deliberately rejected: matching on a window titled "Steam Big Picture Mode". Steam's window titles, classes, and whether Big Picture is even a separate window have all changed across client rewrites, and a media session that silently stops appearing after a Steam update looks like a broken image rather than a moved string. A sway workspace name is a contract this repo owns.

Going back into Steam does not stop anything. People play music over games on purpose, and killing a running Spotify because a game started would lose whatever was playing. media-session stop exists, is wired to an HA button ("Stop media apps"), and nothing calls it automatically.

Prism Launcher runs through Steam

Launched directly, Prism gets you a Flatpak window and a Minecraft that sees a raw evdev gamepad — which is to say, no controller support worth the name. So it does not launch directly. /usr/local/bin/steam-shortcut-prism registers Prism as a non-Steam game in shortcuts.vdf, and /usr/local/bin/prism-launch asks Steam to run it via steam://rungameid/….

What that buys: the game runs inside the Steam Runtime with Steam Input active, so the Steam Controller API is present for it. Pads arrive as configurable Steam controllers with per-game bindings, the overlay works, gyro and back-buttons on Deck-style pads work, and Prism shows up in the Big Picture library instead of being a hole you fall out of the UI into.

Two consequences you need to know about:

• It cannot be baked into the ISO. shortcuts.vdf lives under ~/.steam/steam/userdata/<steamID3>/config/, which does not exist until somebody has logged into Steam on the machine — and no Steam credentials go into an image. So registration happens per-session, is idempotent, and quietly no-ops until the first login. After you first log into Steam, restart the session (or reboot) once.
• It runs before Steam starts, from steam-session. Steam reads shortcuts.vdf at startup and rewrites it from memory at shutdown, so anything written underneath a running client is silently discarded.

If Steam is not installed, or nobody has logged in yet, prism-launch falls back to running Prism directly. That is a working Minecraft with worse controller support, which beats refusing to start.

VERIFY: the binary VDF encoding and the non-Steam AppID derivation (CRC32 of "Exe"+AppName, high bit set) are the long-standing community format — Valve documents neither, and neither was checked against a real client from this environment. The test is simply: does Prism Launcher appear in the Big Picture library, and does the pad work in Minecraft. steam-shortcut-prism refuses to rewrite a shortcuts.vdf that already has other entries in it (it backs it up and tells you to add the entry by hand) rather than risk eating shortcuts you added yourself.

Why trixie and not the household release

household.debian_release is bookworm, whose Mesa is 22.3. That is fine for every other host here — they are a browser and a Python agent, and none of them care what Mesa they have. It is not fine for the one machine that renders games.

So this kiosk sets a per-kiosk override:

"debian_release": "trixie"

tools/config-export.py emits CORE_KIOSK_DEBIAN_RELEASE for every kiosk, falling back to the household value, so the override is available to any builder but only this one uses it. validate-config.py warns if a steam-tv-box is pinned to bookworm. The graphics stack is the one thing on this box that cannot be fixed later by editing a config file and rebuilding a service.

Before you build

No hardware has been chosen and nothing here has been booted on real metal. That is the same standing caveat as the rest of the fleet, and it bites harder on this host than on the others: everything about a gaming box is a hardware claim.

Set these on the kiosk entry in CoreSystemConfig.json (see CoreSystemConfig.json.template for a complete example):

Key	What to put in it
type	steam-tv-box
gpu_vendor	amd, intel or nvidia. Not detected — the build host cannot see this machine, and installing the NVIDIA driver on an AMD box actively breaks it. amd/intel need nothing beyond Mesa; nvidia pulls the non-free driver and sets WLR_NO_HARDWARE_CURSORS=1.
debian_release	trixie
enable_installer	true, unlike every other kiosk here — see below
enable_cec	true unless the set ignores HDMI-CEC
room	the HA area, e.g. living_room

Then:

sudo -E tools/build-steam-tv-box-iso.sh              # the only steam-tv-box in the config
sudo -E tools/build-steam-tv-box-iso.sh <hostname>   # a specific one, if several

The build is noticeably longer than the other images: i386 multiarch plus Steam's dependency chain is a few hundred extra packages.

enable_installer should be true here

Every other kiosk in this project boots live, because every other kiosk is stateless by design. This one is not. A live system keeps its writable layer in RAM, so a Steam library and a few modpacks would vanish on reboot — and they are hundreds of gigabytes.

Install to the disk, and give /home its own large partition, or mount a games disk at /home/<kiosk_username>/Games (created by 0100-user-setup.hook.chroot, and the directory Prism's Flatpak is granted access to).

The validator warns if enable_installer is false on this type.

After the first boot

1. Confirm it is actually accelerated before blaming any game. From the maintenance shell (Super+Shift+Ctrl+M):

   vulkaninfo | head -n 20     # should name your GPU, not llvmpipe
   glxinfo -B                  # same
   

2. Set the wayvnc password. wayvnc will not be running until you do — it fails closed, same as the thin client:

   sudo sh -c 'openssl rand -base64 24 > /etc/wayvnc/wayvnc-password'
   sudo chmod 600 /etc/wayvnc/wayvnc-password
   sudo chown <kiosk_username>:<kiosk_username> /etc/wayvnc/wayvnc-password
   swaymsg reload
   

   It is for administering the box, not for playing over: wayvnc streams the compositor, so a game at 120fps arrives as a slideshow. That is what a screen-scraping protocol does, not a bug to work around.
3. Log into Steam, then restart the session once so the Prism shortcut registers.
4. Set the audio output. On a TV box the right sink is usually HDMI, and if the set was switched off at boot WirePlumber may have defaulted to a headphone jack with nothing in it — the classic "the game has no sound" report. Pick it in HA's Audio output select; the choice persists across reboots (it is stored as a WirePlumber node.name, which is stable, not as a numeric ID, which is not).
5. Leave Big Picture and confirm Firefox, mpv and Spotify appear. Then go back into a game and confirm they are not killed.
6. Pull the power on the container host and re-check: the box must still boot into Big Picture and play a game. steamtv-agent connects asynchronously and keeps retrying.

Home Assistant entities

Published by steamtv-agent via MQTT discovery, under a device named after the kiosk's friendly_name:

Entity	Type	Notes
Session	sensor	gaming / steam / media / idle, plus steam_running, media_running, workspace attributes
Mode	select	gaming / media. Both directions are additive — see below
Screen	select	the five workspaces
Launch Steam Big Picture / Prism Launcher / web browser / media player / Spotify	buttons
Stop media apps	button	the only thing in the whole surface that shuts anything down
Audio output	select	persisted across reboots
Display	switch	HDMI-CEC standby + Sway DPMS. The panel, never the machine
Volume	number
Playback state	sensor	mpv/Spotify via MPRIS
Play/pause, Next, Previous, Stop	buttons

Why Mode is additive in both directions: choosing gaming launches or focuses Steam and leaves the media apps alone (music over a game is a thing people want). Choosing media starts the media session and does not quit Steam, because quitting Steam from a phone while somebody is mid-match is not something this should be able to do by accident.

Playback state reads off for most of a gaming session. That is correct, not broken: the media players genuinely do not exist yet. Steam exposes no MPRIS bus and a game's audio is not something you "pause" — for a noisy game, the volume control is the right surface. Watch Session for what the box is doing.

Security posture

Same as every other kiosk here, and it matters more on this one, because this is the machine with a Steam login and a games library on it.

• MQTT discovery is the only inbound control surface. No HTTP listener, no websocket server, no exposed Sway IPC socket, no shell endpoint. Every handler is a fixed, enumerated action; a payload never becomes an argv element, a shell string or a URL host. See agent/steamtv_agent/mqtt_discovery.py.
• The local LLM has no network path here. The only chain is: LLM tool call → Home Assistant service call → MQTT → the dispatcher.
• Nothing listens on a port except sshd (key-only, root login off, passwords off) and wayvnc (password mandatory, refuses to start without one).
• Steam's remote-play ports are not opened by anything in this image. If you want them, that is a deliberate firewall decision, not a default this ships. Nothing here is port-forwarded; remote access is WireGuard, same as the rest of the house.
• The built ISO contains the Wi-Fi PSK and MQTT credentials from CoreSystemConfig.json. Treat it as a credential. .gitignore covers iso-out/.

Files

hosts/steam-tv-box/
├── configs/
│   ├── audio/audio-config.json        template; the runtime copy lives in /var/lib
│   ├── firefox/                       policies.json (uBlock Origin/SponsorBlock), chrome, launcher
│   ├── greetd/                        autologin config + the session wrapper
│   ├── installer/preseed.cfg          source; the builder generates live-build/config/preseed.cfg
│   ├── mpv/mpv.conf                   IPC socket + hwdec
│   ├── session/
│   │   ├── steam-session              boots Steam, starts the media session when it exits
│   │   ├── steam-big-picture          gamescope-or-Xwayland launcher, idempotent
│   │   ├── steam-shortcut-prism       registers Prism as a non-Steam game (Steam Input)
│   │   ├── session-watcher            sway IPC: the other "left Big Picture" trigger
│   │   ├── media-session              idempotent start/stop of the media half
│   │   ├── media-player               mpv wrapper
│   │   ├── prism-launch               routes through Steam; falls back to direct
│   │   └── spotify-launch             Flathub Spotify
│   ├── sway/                          the session config + display-toggle
│   └── wayvnc/                        config + the fails-closed launcher
├── agent/
│   ├── steamtv-agent.service
│   └── steamtv_agent/                 main, sway_control, mqtt_discovery, mpris_bridge,
│                                      audio_control, runtime_state, display_power, session_mode
└── live-build/config/
    ├── package-lists/steam-tv-box.list.chroot
    └── hooks/normal/                  0100-user-setup, 0250-wayvnc, 0200-greetd,
                                       0300-steam, 0400-flatpak-apps, 0700-steamtv-agent,
                                       0900-firefox

live-build/config/includes.chroot/ and live-build/config/preseed.cfg are generated — wiped and rewritten by the builder on every run. Edit configs/.

Status

Written, syntax-checked, and validated through tools/validate-config.py and tools/config-export.py. Never built, never flashed, never booted. No hardware has been chosen. Specific things that are reasoned rather than verified:

• gamescope's availability in the target Debian release (the hook installs it if present, steam-big-picture falls back to plain Xwayland if not).
• The Flathub application IDs (com.spotify.Client, org.prismlauncher.PrismLauncher) — believed correct, not checked against Flathub.
• The shortcuts.vdf binary format and non-Steam AppID derivation (see above).
• The NVIDIA driver package names for the target release.
• Whether the television honours CEC standby at all.