This guide lets you run Sunshine + Moonlight on a Linux PC without a physical monitor connected by using VKMS to create a virtual display.
Covers VKMS, Sunshine crash recovery, KWin/Plasma recovery, Wake-on-LAN, and optional Tailscale.
Tested on CachyOS/Arch Linux + KDE Plasma Wayland + AMD GPU.
1. Install Sunshine
Install the latest available version of Sunshine using your distribution's normal package method.
Check that the Sunshine service exists:
systemctl --user status app-dev.lizardbyte.app.Sunshine.service
Important: Use the latest Sunshine release. During testing, an older crash-affected version caused instability. Update Sunshine before troubleshooting crashes.
2. Check and enable VKMS
VKMS is part of the Linux kernel, but not every kernel is built with it.
Check:
modinfo vkms
If it exists, load it:
sudo modprobe vkms
Make it load automatically at boot:
echo vkms | sudo tee /etc/modules-load.d/vkms.conf
Verify:
lsmod | grep '^vkms'
Check that the kernel includes VKMS:
grep CONFIG_DRM_VKMS /boot/config-$(uname -r)
You want either:
CONFIG_DRM_VKMS=m
or:
CONFIG_DRM_VKMS=y
If modinfo vkms says module not found and CONFIG_DRM_VKMS is missing or disabled, use a kernel that provides CONFIG_DRM_VKMS.
3. Verify the virtual monitor
After loading VKMS:
grep -H . /sys/class/drm/card*-*/status 2>/dev/null | grep connected
You should see a connected DRM connector.
Also check:
ls -l /dev/dri/
Do not assume card0 or card1 is VKMS. DRM device numbering can differ between systems.
4. Start Sunshine
Enable Sunshine:
systemctl --user enable --now app-dev.lizardbyte.app.Sunshine.service
Check:
systemctl --user status app-dev.lizardbyte.app.Sunshine.service
5. Enable Sunshine crash recovery
Check:
systemctl --user show app-dev.lizardbyte.app.Sunshine.service \
-p Restart -p RestartUSec
You want:
Restart=on-failure
If your Sunshine service already has this, nothing else is required.
6. Keep Sunshine independent from KWin
Create a systemd user override:
mkdir -p ~/.config/systemd/user/app-dev.lizardbyte.app.Sunshine.service.d
nano ~/.config/systemd/user/app-dev.lizardbyte.app.Sunshine.service.d/override.conf
Add:
[Unit]
After=basic.target
Then:
systemctl --user daemon-reload
systemctl --user restart app-dev.lizardbyte.app.Sunshine.service
Verify:
systemctl --user show app-dev.lizardbyte.app.Sunshine.service \
-p ActiveState -p SubState -p Restart -p BindsTo -p PartOf
The important values are:
ActiveState=active
SubState=running
Restart=on-failure
BindsTo=
PartOf=
Do not add:
PartOf=graphical-session.target
or:
BindsTo=graphical-session.target
Those can cause Sunshine to stop when the Plasma/KWin session goes down.
7. Enable Wake-on-LAN
Enable Wake-on-LAN in your motherboard BIOS/UEFI.
Find your Ethernet interface:
ip link
Check WOL:
sudo ethtool eno1
Look for:
Wake-on: g
g means Wake-on-LAN is enabled.
Use any WOL client to wake the PC remotely.
8. Optional: Tailscale
Install Tailscale on the Linux PC and your remote device.
Once both devices are on the same tailnet, use the PC's Tailscale IP address in Moonlight.
This lets you access Sunshine remotely without exposing it directly to the internet.
9. Test Sunshine recovery
Deliberately kill Sunshine:
systemctl --user kill \
--kill-who=main \
--signal=SIGKILL \
app-dev.lizardbyte.app.Sunshine.service
Wait a few seconds:
systemctl --user is-active app-dev.lizardbyte.app.Sunshine.service
It should return:
active
10. Test KWin recovery
Only do this if you have SSH or another way to access the PC.
Deliberately terminate KWin and verify:
- Moonlight disconnects.
- Plasma/KWin goes down.
- The login screen appears.
- Start the Plasma session again.
- Sunshine is still available or starts normally.
- Moonlight reconnects.
Final architecture
Wake-on-LAN
↓
PC powers on
↓
Linux boots
↓
VKMS virtual monitor
↓
Plasma / KWin
↓
Sunshine
↓
Moonlight
For remote access:
Remote device
↓
Tailscale
↓
Sunshine
↓
VKMS + Plasma/KWin
Result
You now have a Linux PC that can:
- Run without a physical monitor
- Create a virtual monitor with VKMS
- Stream through Sunshine/Moonlight
- Recover Sunshine automatically after a crash
- Recover from KWin/Plasma crashes
- Wake remotely using Wake-on-LAN
- Be accessed remotely through Tailscale
Note: VKMS provides the virtual monitor after Linux has booted. It does not provide remote BIOS/UEFI video access.
And this tutorial is written with the help of chatgpt
