If you forgot your credentials to the web UI, try this.
General
AppImage
Flatpak
If you experience unusual mouse behavior, try attaching a physical mouse to the Sunshine host.
Can't access the web UI?
One trick might be to change Steam settings and check or uncheck the configuration to support Xbox/PlayStation controllers and leave only support for Generic controllers.
Also, if you have many controllers already directly connected to the host, it might help to disable them so that the Sunshine-provided controller (connected to the guest) is the "first" one. In Linux this can be achieved on USB devices by finding the device in /sys/bus/usb/devices/ and writing 0 to the authorized file.
For real-time game streaming the most important characteristic of the network path between server and client is not pure bandwidth but rather stability and consistency (low latency with low variance, minimal or no packet loss).
The network can be tested using the multi-platform tool iPerf3.
On the Sunshine host iperf3 is started in server mode:
On the client device iperf3 is asked to perform a 60-second UDP test in a reverse direction (from server to client) at a given bitrate (e.g. 50 Mbps):
Watch the output on the client for packet loss and jitter values. Both should be (very) low. Ideally, packet loss remains less than 5% and jitter below 1 ms.
For Android clients use PingMaster.
For iOS clients use HE.NET Network Tools.
If you are testing a remote connection (over the internet), you will need to forward the port 5201 (TCP and UDP) from your host.
If the host PC (running Sunshine) has a much faster connection to the network than the slowest segment of the network path to the client device (running Moonlight), massive packet loss can occur: Sunshine emits its stream in bursts every 16 ms (for 60 fps), but those bursts can't be passed on fast enough to the client and must be buffered by one of the network devices inbetween. If the bitrate is high enough, these buffers will overflow and data will be discarded.
This can easily happen if e.g., the host has a 2.5 Gbit/s connection and the client only 1 Gbit/s or Wi-Fi. Similarly, a 1 Gbps host may be too fast for a client having only a 100 Mbps interface.
As a workaround the transmission speed of the host NIC can be reduced: 1 Gbps instead of 2.5 or 100 Mbps instead of 1 Gbps. A technically more advanced solution would be to configure traffic shaping rules at the OS level, so that only Sunshine's traffic is slowed down.
Such a solution on Linux could look like that:
In that way only the Sunshine traffic is limited by 1 Gbit. This is not persistent on reboots. If you use a different port for the game stream, you need to adjust the last command.
Sunshine versions > 0.23.1 include improved networking code that should alleviate or even solve this issue (without reducing the NIC speed).
Although unlikely, some guests might work better with a lower MTU from the host. For example, an LG TV was found to have 30–60% packet loss when the host had MTU set to 1500 and 1472, but 0% packet loss with a MTU of 1428 set in the network card serving the stream (a Linux PC). It's unclear how that helped precisely, so it's a last resort suggestion.
Capture methods (wlgrab) or encoders (nvenc, vaapi) that utilize EGL contexts may exhibit FPS drops in conjunction with a Sunshine installation that runs in a sandboxed or reduced permissions state (Flatpak, AppImage packages) due to the lack of active CAP_SYS_NICE process permissions needed to set up high priority EGL contexts.
To check if you are affected by this issue, look out for this message in your Sunshine log:
| Desktop Environment | Vulkan Supported? | Recommended Sunshine Install Type | Recommended Capture & Encoder Configuration |
|---|---|---|---|
| KDE Plasma | Yes | Any | portal or kwin capture with vulkan encoding |
| KDE Plasma | No | Non-Sandboxed | portal or kwin capture with vaapi/nvenc encoding |
| GNOME / other | Yes | Any | portal capture with vulkan encoding |
| GNOME / other | No | Non-Sandboxed | portal capture with vaapi/nvenc encoding |
Due to legal concerns, Mesa has disabled hardware decoding and encoding by default.
If you see the above error in the Sunshine logs, compiling Mesa manually may be required. See the official Mesa3D Compiling and Installing documentation for instructions.
Portal capture requires you to approve Remote Desktop permissions using an on-screen prompt on the host. Sunshine saves the resulting restore token so the XDG Desktop Portal can reauthorize capture automatically on subsequent starts.
If a restore token doesn't yet exist or becomes stale (for example, after a Sunshine crash, switching desktop environments, changing portal implementations, or changing the monitor associated with the Portal session), Sunshine will attempt to run in fallback capture mode. While in this mode, Sunshine will temporarily select another working capture method so that you can interact with the Portal Remote Desktop dialog. Once a new restore token is negotiated and saved, Sunshine will automatically restart and switch back to Portal capture.
If the saved Portal token is valid but you want to change the monitor associated with Portal capture, open the Web UI, open Troubleshooting, and select Reset XDG Portal Capture. Sunshine deletes the saved token and restarts. Approve the Remote Desktop prompt again and select the display to capture when it appears.
Users of the KDE Plasma desktop can bypass manual permission setup either by switching to kwin capture or setting the following configuration to enable permanent capture authorization for Sunshine via Portal capture:
After installation, the udev rules need to be reloaded. Our post-install script tries to do this for you automatically, but if it fails, you may need to restart your system.
Sunshine recreates virtual gamepad device nodes for each streaming session. Manual chmod or setfacl changes therefore disappear when the client reconnects. Confirm that the installed Sunshine rule contains the parent-property import and libvirtualhid/uhid/* match, then reload it and reapply it to existing gamepad nodes:
If the input is still not working, you may need to add your user to the input group.
If you run multiple concurrent Wayland sessions on separate logind seats (e.g. seat0, seat1), your compositor may ignore injected input unless Sunshine's virtual devices are assigned to the correct seat.
Sunshine determines its target seat from XDG_SEAT, which is typically set automatically by your display manager. If needed, you can override it manually in your systemd service file or shell environment before starting Sunshine.
When the seat is not seat0, Sunshine appends the seat name to its virtual device names, for example:
Sunshine creates two mouse devices: a relative one and an absolute one.
To assign Sunshine's virtual devices to the correct seat, create this udev rules file (/etc/udev/rules.d/72-sunshine-virtual-seat.rules):
Then reload udev:
KMS screencasting requires elevated privileges which are not allowed for Flatpak or AppImage packages. This means that you must install Sunshine using the native package format of your distribution, if available. KMS capture will soon be phased out in favour of XDG Portal Capture (which works with all package types).
KWin's overlay support interferes with KMS capture. As of KWin 6.5 this is not yet set by default, but for future versions that enables this by default, you may be able to disable again via a special environment variable:
If KMS screen capture results in a black screen being streamed, you may need to set the parameter modeset=1 for Nvidia's kernel module. This can be done by adding the following directive to the kernel command line:
Consult your distribution's documentation for details on how to do this. (Most often grub is used to load the kernel and set its command line.)
If you notice unexpectedly high encoding latencies (e.g., in Moonlight's performance overlay) or strong fluctuations thereof, your system's Mesa libraries are outdated (<24.2). This is particularly problematic at higher resolutions (4K).
Starting with Mesa-24.2, applications can request a low-latency mode by running them with a special environment variable:
Sunshine sets this variable automatically, no manual configuration is needed.
To check whether low-latency mode is being used, one can watch the VCLK and DCLK frequencies in amdgpu_top. Without this encoder tuning both clock frequencies will fluctuate strongly, whereas with active low-latency encoding they will stay high as long as the encoder is used.
Some users have reported stuttering issues when streaming games running within Gamescope.
If you get this error:
Dynamic session lookup supported but failed: launchd did not provide a socket path, verify that org.freedesktop.dbus-session.plist is loaded!
Try this.
Sunshine supports two virtual gamepad backends on Windows. You can install the Virtual HID Driver separately as an optional paid upgrade for a driver-backed Raw Input keyboard and mouse plus full virtual gamepad support. ViGEmBus is a limited alternative for Xbox 360 and DualShock 4 support that has reached end of life. If you use the ViGEmBus fallback, you must use version 1.17 or newer.
When Virtual HID Driver is used, Sunshine requires version 2026.914.1218.10 or newer.
Virtual HID Driver adds Xbox One, Xbox Series, DualSense, Nintendo Switch Pro, and Generic gamepads, plus advanced controller features such as motion, touchpads, LEDs, and adaptive triggers when supported. Unlike the discontinued ViGEmBus project, Virtual HID Driver is actively developed and supported by the LizardByte team.
An active paid Virtual HID Driver machine license is required before Sunshine can create driver-backed libvirtualhid devices, including gamepads and the Raw Input keyboard and mouse. Use the message on the Web UI home page, the startup tray notification, or Get/Manage License in the Virtual HID Driver tray submenu to open the license section on the Troubleshooting page. In Configuration > Input, select All Available Drivers, only Virtual HID Driver, or only ViGEmBus. Sunshine keeps prompting until this setting is saved, but automatically selects All Available Drivers when it detects an existing active Virtual HID Driver license. Whenever the Virtual HID Driver license is not valid, All Available Drivers falls back to a compatible ViGEmBus installation for Xbox 360 and DualShock 4 gamepads and to SendInput for keyboard and mouse. Selecting only ViGEmBus suppresses Virtual HID Driver startup notifications and hides its status and license details from the Troubleshooting page.
After installation, it is recommended to restart your computer.
With a compatible Virtual HID Driver and active license, Sunshine sends normal key transitions through a real HID keyboard so games using Raw Input can receive them. Unicode text input and keys outside the supported HID keyboard page continue to use Windows input injection. When the driver-backed keyboard cannot be created because the driver, broker, or license is unavailable, libvirtualhid falls back to SendInput.
Check the Virtual HID Driver version and license sections on the Web UI Troubleshooting page. Sunshine recreates the shared keyboard and mouse after a successful license activation, validation, or deactivation, so you do not need to restart Sunshine merely to switch between the HID and SendInput paths.
With a compatible Virtual HID Driver and active license, Sunshine sends relative mouse movement, buttons, and scrolling through a real HID device so games using Raw Input can receive them. Absolute positioning still uses Windows input injection. When the driver-backed mouse cannot be created, libvirtualhid falls back to SendInput; the Windows cursor may still move even though a game that listens only for Raw Input receives nothing.
Check the Virtual HID Driver version and license sections on the Web UI Troubleshooting page even when controller input is disabled. The same live refresh used by the keyboard path also switches the mouse between HID and SendInput without requiring a Sunshine restart.
Since Sunshine runs as a service on Windows, it may not have the same level of access that your regular user account has. You may get permission denied errors when attempting to launch a game or application from a non-system drive.
You will need to modify the security permissions on your disk. Ensure that user/principal SYSTEM has full permissions on the disk.
If you experience stuttering using NVIDIA, try disabling vsync:fast in the NVIDIA Control Panel.