wiki/Catalogue-Self-Hosted/apps/app-steam-headless.md

---
title: Steam Headless
created: 2026-06-07
updated: 2026-06-07
type: app
tags: [catalogue, gaming, steam, headless, docker, bash, game-streaming, library]
confidence: medium
contested: true
sources:
  - https://selfh.st/apps/?tag=Gaming
  - https://github.com/Steam-Headless/docker-steam-headless
  - https://headless.doctormckay.com/
---

# 🚂 Steam Headless

> Lance un client Steam en mode headless dans un conteneur Linux avec un X server virtuel — permet d'utiliser Steam depuis un serveur distant, d'automatiser des téléchargements, ou de coupler avec [[app-sunshine]] pour streamer des jeux Steam via un GPU partagé.

| Métadonnée | Valeur |
| :--- | :--- |
| **Site web** | https://headless.doctormckay.com/ |
| **GitHub** | https://github.com/Steam-Headless/docker-steam-headless |
| **License** | MIT |
| **Langage** | Bash / Dockerfile |
| **Étoiles** | 225 ⭐ |
| **Dernière MAJ** | 2026-04-18 |
| **Catégorie** | [[cat-gaming\|Gaming]] |

## Description

**Steam Headless** est un projet communautaire qui répond à un besoin simple mais tricky : faire tourner un **client Steam complet** dans un environnement **sans écran physique** (serveur headless, container Docker, VM cloud). Valve ne fournit pas officiellement de client Steam headless — Steam attend un display X11/Wayland, un D-Bus, un audio sink, et refuse de se lancer en mode purement CLI. Ce projet fournit un **Dockerfile + scripts Bash** qui assemblent un environnement complet : Xvfb (X virtual framebuffer), PulseAudio, D-Bus, SteamCMD, le client Steam, et divers hacks pour bypass les dialogues GUI.

Trois cas d'usage principaux : (1) **Téléchargement de bibliothèque Steam** : on veut backup tous ses jeux Steam sur un NAS sans devoir laisser un PC allumé. (2) **Steam + Sunshine** : on stream via [[app-sunshine]] depuis un serveur headless, et Steam tourne à l'intérieur d'un container. Le GPU est partagé entre Sunshine et le jeu via le GPU passthrough ou la virtualisation. (3) **CI/CD pour jeux Steam** : pour des projets qui ont un build/deploy automatisé de leur jeu sur Steam (indé), ou des runners pour le modding.

Le projet **n'est pas officiel Valve** et dépend des hacks internes de Steam (utilisation de `xvfb-run`, `xdotool` pour simuler des clicks, `xdg-open`, etc.). Valve casse régulièrement la compatibilité (sessions Steam Guard, mises à jour de la binaire, intégration Proton). Le tag `contested: true` reflète ce risque : le projet est utile mais fragile.

Limites connues : pas de support multi-GPU propre (1 GPU = 1 instance), performances légèrement dégradées vs client natif (overhead Xvfb), mises à jour Steam imposent souvent un rebuild de l'image, certains jeux anti-cheat refusent le mode headless. Pour un usage stable : viser les jeux sans anti-cheat (solo, indie, simulation) ; pour les jeux compétitifs, préférer un client natif sur un PC physique.

## Installation

### Docker Compose (méthode recommandée)

```yaml
# docker-compose.yml
version: '3.8'

services:
  steam-headless:
    build:
      context: https://github.com/Steam-Headless/docker-steam-headless.git
      dockerfile: Dockerfile
    container_name: steam-headless
    restart: unless-stopped
    network_mode: host  # nécessaire pour le streaming
    environment:
      - DISPLAY=:0
      - PUID=1000
      - PGID=1000
      - TZ=Europe/Paris
      - STEAM_USER=mon_compte_steam
      - STEAM_PASS=***  # voir note
    volumes:
      - ./config:/config
      - ./library:/home/steam/Steam
      - /etc/localtime:/etc/localtime:ro
    devices:
      - /dev/dri:/dev/dri  # Intel/AMD GPU
    # runtime: nvidia  # décommenter pour GPU NVIDIA
```

> ⚠️ **Sécurité Steam Guard** : éviter de mettre le mot de passe en variable d'environnement. Préférer `steamcmd +login mon_user` puis suivre la procédure Steam Guard interactivement au premier lancement (cache le token ensuite).

### Avec GPU NVIDIA

```yaml
services:
  steam-headless:
    runtime: nvidia
    environment:
      - NVIDIA_VISIBLE_DEVICES=all
      - NVIDIA_DRIVER_CAPABILITIES=all
    # ... reste identique
```

### Installation manuelle (sans Docker)

```bash
# Installer Xvfb, SteamCMD, dépendances
sudo apt install -y xvfb xdotool x11-utils pulseaudio dbus-x11
mkdir -p ~/steam-headless
cd ~/steam-headless

# Télécharger SteamCMD
wget https://steamcdn-a.akamaihd.net/client/installer/steamcmd_linux.tar.gz
tar -xvzf steamcmd_linux.tar.gz

# Lancer Steam dans Xvfb
xvfb-run -a -s "-screen 0 1280x720x24" ./steamcmd.sh +login mon_user +quit
```

## Configuration

- **Authentification** : premier lancement interactif requis pour le Steam Guard (code email). Ensuite, le token est mis en cache.
- **Téléchargements automatiques** : Steam Headless peut être couplé à un script qui installe les jeux par ID Steam (`steamcmd +app_update <app_id> validate`).
- **Bibliothèque partagée** : mapper `/home/steam/Steam/steamapps` sur un volume NFS ou SMB pour servir la même bibliothèque à plusieurs containers.
- **Audio** : PulseAudio configuré pour rediriger vers null sink (pas de son en headless) ou vers un client réseau (PulseAudio over TCP).
- **Lancement de jeux** : `steam -applaunch <app_id>` via `xvfb-run`. Pour les jeux Windows : Proton activé par défaut.
- **Sunshine integration** : ajouter Sunshine dans le même compose file, partager `/home/steam/.steam`, configurer Sunshine pour streamer la session X.

## Alternatives

### Open Source
- [[app-sunshine]] — Pour le game streaming, pas le téléchargement Steam.
- [[app-games-on-whales]] — Approche conteneurisée plus complète (Sunshine + audio + Steam intégrés).
- **SteamCMD** (Valve officiel) — CLI pur pour serveurs de jeux dédiés, pas pour client Steam.
- **heroic-games-launcher** (self-hosted) — Launchers alternatifs GOG/Epic/Amazon, parfois couplés à Steam.
- **steam-library-manager** (legacy) — Gérer la bibliothèque Steam hors-ligne.
- **Nilesoft Steam Manager** — Fork Proton pour installation propre.

### Propriétaires
- **Steam client officiel** (Valve) — Mode GUI standard, ne tourne pas headless.
- **GeForce NOW**, **Xbox Cloud Gaming** — Cloud gaming SaaS, pas self-hosted.
- **Boosteroid**, **Shadow PC** — Offres cloud PC, pas open source.

## Sécurité

- **Compte Steam** : un compte « dédié » au headless est recommandé. Ne pas utiliser son compte principal si on stocke ses identifiants dans un compose file.
- **Steam Guard 2FA** : obligatoire depuis 2015 pour la plupart des opérations. Activer Steam Mobile Authenticator pour ne pas dépendre de l'email.
- **Anti-cheat** : EAC/BattlEye/VAC détectent les environments conteneurisés/headless. **Jouer à des jeux anti-cheat en headless peut entraîner un ban** — vérifier les CGU de chaque jeu.
- **Docker socket** : ne JAMAIS monter `/var/run/docker.sock` dans le container Steam Headless (escalade de privilèges triviale).
- **Mises à jour** : les breaking changes Valve sont fréquents (1-3x/an). Prévoir une procédure de rebuild + test.
- **GPU passthrough** : si VM, le passthrough PCI d'un GPU est très efficace mais nécessite IOMMU + isolation ACPI. Bien documenter.
- **HTTPS Sunshine** : si couplé à [[app-sunshine]], la surface d'attaque augmente (2 services exposés). Penser à un VPN ([[app-vpn]]).

## Ressources

- [Site officiel](https://headless.doctormckay.com/)
- [Repository GitHub](https://github.com/Steam-Headless/docker-steam-headless)
- [Discussion Reddit (état du projet)](https://reddit.com/r/selfhosted)
- [Wiki Proton (compatibilité jeux)](https://www.protondb.com/)

## Pages Liées
- [[cat-gaming]] — Catégorie parente
- [[app-sunshine]] — Game streaming couplé
- [[app-games-on-whales]] — Stack conteneurisée complète
- [[app-pterodactyl]] — Panel pour serveurs SteamCMD
- [[app-linuxgsm]] — CLI pour serveurs de jeux
- [[recettes-docker-compose]] — Templates
- [[securisation-home-lab]] — Anti-cheat et bans