---
name: headless-game-streaming
description: "Turn a headless Linux server with NVIDIA GPU into a game streaming host (Sunshine + Moonlight) — including virtual display setup, Steam Proton, and network tuning."
version: 1.0.0
author: Hermes Agent
license: MIT
platforms: [linux]
metadata:
  hermes:
    tags: [gaming, streaming, nvidia, sunshine, moonlight, headless]
---

# Headless Game Streaming (Sunshine + Moonlight)

Turn a headless Linux server into a game streaming host. The GPU renders games, NVENC hardware-encodes the stream, and Moonlight clients (Shield TV, phone, laptop) decode it — all with 3-8ms latency on a local network.

## Prerequisites

- NVIDIA GPU (Turing or newer for NVENC)
- NVIDIA proprietary drivers installed
- Wired Ethernet (gigabit recommended)
- HDMI dummy plug ($5-10 on Amazon) — **critical**: without a connected display, NVIDIA GPUs throttle clocks or refuse to render properly

## Setup

### 1. HDMI Dummy Plug

Plug into any HDMI port on the GPU. It emulates a display (4K capable, usually) and tricks the GPU into full performance mode. No monitor needed.

### 2. Sunshine (streaming server)

```bash
sudo add-apt-repository ppa:sunshine-streaming/release
sudo apt install sunshine
```

Sunshine auto-detects NVIDIA GPU and NVENC. Web UI at `https://localhost:47990`.

### 3. Moonlight (client)

Install Moonlight on the client device (Android Shield, phone, laptop, etc.). It auto-discovers Sunshine on the LAN. Pair with a 4-digit PIN from the Sunshine web UI, one time.

### 4. Games

**Steam + Proton** (Windows games on Linux):
```bash
sudo apt install steam
# Enable Proton in Steam → Settings → Compatibility → "Enable Steam Play for all other titles"
```

**Lutris** (non-Steam: GOG, Epic, Battle.net, emulators):
```bash
sudo apt install lutris
```

Add individual games in Sunshine web UI → Applications → Add. Point to the `.exe` or Steam shortcut. Or just stream the full desktop.

## Network Requirements

| Resolution | Bitrate needed | Your LAN |
|---|---|---|
| 1080p 60fps | 20-30 Mbps | Gigabit (1000 Mbps) |
| 1440p 60fps | 40-60 Mbps | 1000 Mbps |
| 4K 60fps | 80-100 Mbps | 1000 Mbps |

All traffic stays on LAN — never touches your internet connection. The router's switch chip handles it in hardware.

## Pitfalls

- **No dummy plug = broken rendering**: Without a display, NVIDIA GPUs run at minimum clocks and games may refuse to launch or render at single-digit FPS.
- **Desktop environment needed**: Xorg (Wayland works but has edge cases). Sunshine captures a display output. A minimal Xorg session on the dummy display is enough.
- **Some anti-cheat games don't work on Linux**: Valorant, Call of Duty, Fortnite — kernel-level anti-cheat has no Linux support. Check ProtonDB before buying.
- **VRAM conflict with local LLM**: If running llama-server simultaneously, the model and game compete for VRAM. Socket-activate the LLM or stop it while gaming.

## Performance (NVIDIA Turing / 2080 Ti reference)

NVENC encoding uses dedicated silicon — negligible FPS impact (0-5% in most titles). Latency: 3-8ms on wired LAN, 5-15ms on WiFi 6.
