Steam-Headless: your Steam library streamed from a container you never see

Headless means the screen is elsewhere

The project is a headless Steam Docker image, a remote game streaming server where the container runs a full Steam client and desktop that nobody sits in front of. Play your games either in the browser with audio or via Steam Link or Moonlight, and play from another Steam client with Steam Remote Play, the four consumption paths covering a browser tab, dedicated hardware receivers, the Moonlight open ecosystem and Valve's own remote play protocol. The web access path is a full video and audio noVNC session to an Xfce4 desktop, so the container is not merely a protocol relay but a complete Linux desktop with Steam configured for running on Linux with Proton, the translation layer that makes Windows games run.

GPU support across three vendors

The feature list names NVIDIA, AMD and Intel GPU support, full controller support, and root access inside the container, the trio that defines what kind of host the image expects. The GPU passthrough setup is what makes gaming viable, since the container's Proton and game rendering need real hardware acceleration, and controller passthrough matters because the clients expect the host to present gamepads to the Steam session. Root access signals the philosophy, this is a personal appliance rather than a multi-tenant service, the user is expected to install what they need. Two Dockerfiles at the repository root, Dockerfile.debian and Dockerfile.arch, show the base distribution choices, with Debian Trixie named as the current base in the feature list.

Flatpak launchers beside Steam

Beyond Steam itself, the image supports easy installation of EmuDeck, Heroic and Lutris via Flatpak, the three companion launchers covering emulation and the non-Store game libraries, installed through the WebUI under Applications, System, Software. Support for Flatpak and Appimage installation generally is listed as a feature, so the container behaves like a desktop for software purposes, and additional startup behavior is handled two ways, a script ending in .sh dropped into the init.d directory in the home directory runs on container startup, and Session and Startup settings in the WebUI configure autostarts. Steam itself is configured to automatically start in the container, so the appliance boots into a usable state without interaction.

The persistence rule

The storage note is the one paragraph a user must internalize before touching anything, everything you wish to save in this container should be stored in the home directory or a docker container mount that you have specified, and all files stored outside the home directory are not persistent and will be wiped if there is an update of the container or you change something in the template. The corollary follows, it is recommended that you mount your games library to /mnt/games and configure Steam to add that path, the mount that survives container replacement while the container itself is disposable. This is the container-native mental model applied to gaming, state lives in volumes, the image is cattle, and the note exists because gaming users arrive with desktop instincts.

Networking for Remote Play

The network note addresses the subtlest failure mode, if you want to use the container as a Steam Remote Play host, you should create a custom network and assign the container its own IP, because if you do not, the traffic will be routed through the internet since Steam thinks you are on a different network. The explanation is Valve's discovery mechanism, and the remedy is standard Docker networking, a macvlan or similar custom network giving the container a LAN address. The note's existence, buried in the README rather than left to issue threads, shows where first-time deployments actually fail, and the fix is configuration at docker run time rather than inside the container.

Sharing the host's X server

For hosts already running X, the container can use the existing display instead of starting its own, and the configuration is spelled out as four items. DISPLAY set to :0 configures the screen to use the primary display, set to whatever the host is using, MODE set to secondary configures the container to not start an X server of its own, and two optional settings enable host dbus sharing, the HOST_DBUS variable set to true and the /run/dbus mount read-only into the container. This mode matters on home servers that already run a desktop, since a second X server on one GPU invites driver contention, and the secondary mode makes the container a guest on the existing session infrastructure rather than a competitor for it.

Three install guides and an honest TODO

Installation routes to three platform guides in the docs directory, Docker Compose for the general case, Unraid for the NAS audience this project's user base overlaps heavily with, and Ubuntu Server for bare metal hosts, with a development environment script in the devops directory for contributors. The TODO section is refreshingly blunt, remove SSH, require the user to enter a password for sudo, and document how to run the container on other server operating systems including TrueNAS Scale, the last being a common NAS platform for this kind of deployment. The listed releases, 0.1.0 and 0.2.0, both dated the same day in September 2023, predate the ongoing master branch work, pushed 2026-09-25, so the image tracks Steam's own updates through builds rather than tags.

Editorial conclusion

Deploy Steam-Headless when a spare machine with a GPU should serve games to browsers, TVs and other clients without a desktop install, and when the container model, wipeable root, mounted games library, startup scripts, fits how you manage servers. Skip it if you want a native gaming desktop, the headless design assumes the screen is elsewhere. Before deploying, mount your games library at /mnt/games as recommended, give the container its own IP on a custom network if Remote Play will be used, since otherwise traffic routes through the internet, and read the installation guide matching your platform, Docker Compose, Unraid or Ubuntu Server, before the first run.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-2.0
3. README
4. Releases
5. Steam-Headless/docker-steam-headless on GitHub