Operator Guides
Curated LAN baseline, low-latency, headless, multi-GPU, HDR, per-client, webhook, and logging how-tos.
LAN streaming baseline#
Goal: stable 1080p120 or 4K60 on a wired LAN with default fork settings. Install with ./scripts/linux-install.sh and enable the user service. Wire the host with Ethernet. Leave fork defaults enabled (cpu_pinning, enet_4mib_buffer, busy_poll_us, dscp_qos). In Moonlight set bitrate to ~80% of measured iPerf throughput. Run iperf3 per the Troubleshooting network test.
Tip
If the host NIC is 2.5 GbE but the client is 1 GbE, set rate_cap_pct = 80 or lower to avoid buffer overruns.
Competitive low-latency profile#
Add to ~/.config/sunshine/sunshine.conf, plus per-game NVENC override in apps.json. Disable V-Sync in-game; cap Moonlight bitrate only if packet loss appears.
Warning
latency_mode = aggressive trades some visual quality on software scaling paths. Test before using in single-player titles.
latency_mode = aggressive
busy_poll_us = 75
pipewire_latency_ms = 4
cpu_pinning = true
nvenc_tuning_preset = 0Headless and SSH access#
Path 1 — virtual display (fork): headless_virtual_display = true with headless_width/headless_height/headless_refresh. Path 2 — dummy plug for NVIDIA stable modes with a normal graphical session. Path 3 — SSH into an existing X11 session: ssh user@host 'export DISPLAY=:0; sunshine'.
Caution
Do not run two sunshine instances. Stop the systemd user service before foreground debugging.
Multi-GPU workstations#
| Step | Action |
|---|---|
| 1 | Identify GPUs: lspci | grep -E 'VGA|3D' and nvidia-smi |
| 2 | Plug the monitor (or dummy) into the GPU you want to capture |
| 3 | Launch games on that GPU (DRI_PRIME=1, prime-run, or BIOS mux) |
| 4 | In Web UI, set display adapter / output if multiple heads are visible |
| 5 | Enable gpu_governor = true for AMD; install redesign nvidia-clock-lock for NVIDIA |
HDR on Linux (experimental)#
Requires KMS capture, an HDR compositor (KDE Plasma 6, Gamescope), HEVC Main 10 or AV1 10-bit encoder (VAAPI on AMD/Intel), HDR enabled in host OS and Moonlight client, and an EDID emulator or HDR-capable display on host.
Per-client household profiles#
Use client_profile_<identifier> in sunshine.conf. The identifier matches the paired client name from the Web UI PIN / clients list.
client_profile_living-room-tv = {"max_bitrate": 150000, "hevc_mode": 1}
client_profile_phone = {"max_bitrate": 20000, "width": 1280, "height": 720}Webhooks and structured logging#
Notify Home Assistant or Discord on stream start/stop with webhook_secret + webhook_url_0, verifying X-Solarflare-Signature. For observability: SUNSHINE_LOG_JSON=1 systemctl --user restart app-dev.lizardbyte.app.Sunshine.service, then journalctl --user -u app-dev.lizardbyte.app.Sunshine.service -f.
webhook_secret = your-hmac-secret
webhook_url_0 = https://example.com/hooks/solarflarePlatform support#
Linux x86-64 is primary via ./scripts/linux-install.sh. Other-arch Linux may build but is not release-tested. Windows / macOS / FreeBSD paths install upstream Sunshine unless you build this repository yourself on that platform.
| Platform | SolarFlare support |
|---|---|
| Linux x86-64 | Primary; ./scripts/linux-install.sh |
| Linux (other arch) | Source may build; not release-tested |
| Windows / macOS | Inherited code; use upstream Sunshine releases |
| FreeBSD | Inherited upstream packages only |
Builder vs runtime images#
scripts/linux_build.sh is a compile-only Docker builder, not a streaming runtime. It validates packaging metadata (appstreamcli, desktop-file-validate) and can emit AppImage artifacts. Runtime containers use the upstream lizardbyte/sunshine images with --ipc=host, /dev/dri (and /dev/uinput for input), the full TCP/UDP port set, and a persisted /config volume. Set PUID/PGID to the config owner and chown -R the volume if IDs change later. Multi-arch manifests cover amd64 and arm64, but SolarFlare release binaries are x86-64 only — arm64 hosts must build from source. Point orchestrator health checks at GET /api/health.
Moonlight client picks#
| Client | Platforms | Notes |
|---|---|---|
| Moonlight Desktop (Qt) | Windows, macOS, Linux | Recommended; full codec and HDR set |
| Moonlight Android | Android, Android TV | Manual host add when mDNS is blocked |
| Moonlight iOS / tvOS | iPhone, iPad, Apple TV | HDR needs host + client capable |
| Moonlight Embedded | Raspberry Pi, embedded Linux | Host must be a separate machine |
| Moonlight Web | Chrome, Edge | Browser client; smaller feature surface |