characterecho-sean/cachyos-headless-sunshine

cachyos-headless-sunshine is a setup script for turning a Linux gaming PC into a headless game-streaming box, meaning it runs with no monitor, keyboard, or mouse ever attached. It combines Sunshine, a game-streaming host, with gamescope, a display compositor, so that a phone, tablet, or TV running the Moonlight streaming app receives a stream at its own native resolution, with HDR support. It was built and tested on CachyOS, an Arch-based Linux distribution, with an NVIDIA RTX 4090 and a Samsung Galaxy Tab S9 Ultra as the streaming client, but the author expects it to work on other Arch-based distributions, GPUs, and resolutions as well. The core problem it solves is that a generic HDMI dummy plug only reports a handful of standard resolutions, not your actual device's native resolution, which normally forces either a blurry fallback resolution or manual reconfiguration after every reboot. The script builds a synthetic display identity file that declares your device's real resolution and HDR capability, loaded at boot so the system always treats the display as connected, with no physical plug required. If that approach does not work on a given setup, it can fall back to patching a real HDMI dummy plug's own display data instead. On top of that, it installs and configures gamescope as a headless compositor pinned to your resolution and refresh rate, with inverse tone mapping enabled so standard-range game content is properly converted for an HDR display instead of looking dark and wrong. It wires up Sunshine's screen capture to read directly from the graphics driver rather than depending on a specific compositor protocol, and sets everything to start automatically on boot through an autologin console, launching gamescope, Sunshine, and Steam Big Picture together. Extra touches include a performance overlay you can toggle mid-stream, an interactive HDR calibration tool that installs as its own entry in your Steam library so you can tune brightness against your real display, faster shader pre-caching so newly installed games stutter less on first launch, and a workaround that clones the virtual controller Sunshine creates so certain games that fail to detect it can still be played. Because a stray button press could otherwise suspend a headless machine with no way to wake it, the installer also disables the system's suspend option.