Setup#

The recommended method for running Sunshine is to use the binaries bundled with the latest release.

Binaries#

Binaries of Sunshine are created for each release. They are available for Linux, macOS, and Windows. Binaries can be found in the latest release.

Tip

Some third party packages also exist. See Third Party Packages. No support will be provided for third party packages!

Install#

Warning

The Docker images are not recommended for most users. No support will be provided!

Docker images are available on Dockerhub.io and ghcr.io.

See Docker for additional information.

CUDA Compatibility

CUDA is used for NVFBC capture.

Tip

See CUDA GPUS to cross reference Compute Capability to your GPU.

Package

CUDA Version

Min Driver

CUDA Compute Capabilities

sunshine.AppImage

11.8.0

450.80.02

35;50;52;60;61;62;70;75;80;86;90

sunshine.pkg.tar.zst

11.8.0

450.80.02

35;50;52;60;61;62;70;75;80;86;90

sunshine_{arch}.flatpak

12.0.0

525.60.13

50;52;60;61;62;70;75;80;86;90

sunshine-debian-bookworm-{arch}.deb

12.0.0

525.60.13

50;52;60;61;62;70;75;80;86;90

sunshine-debian-bullseye-{arch}.deb

11.8.0

450.80.02

35;50;52;60;61;62;70;75;80;86;90

sunshine-fedora-38-{arch}.rpm

12.4.0

525.60.13

50;52;60;61;62;70;75;80;86;90

sunshine-fedora-39-{arch}.rpm

12.4.0

525.60.13

50;52;60;61;62;70;75;80;86;90

sunshine-ubuntu-22.04-{arch}.deb

11.8.0

450.80.02

35;50;52;60;61;62;70;75;80;86;90

sunshine-ubuntu-24.04-{arch}.deb

11.8.0

450.80.02

35;50;52;60;61;62;70;75;80;86;90

Caution

Use distro-specific packages instead of the AppImage if they are available.

According to AppImageLint the supported distro matrix of the AppImage is below.

  • ✔ Debian bullseye

  • ✔ Debian bookworm

  • ✔ Debian trixie

  • ✖ Debian sid

  • ✔ Ubuntu mantic

  • ✔ Ubuntu lunar

  • ✔ Ubuntu jammy

  • ✔ Ubuntu focal

  • ✖ Ubuntu bionic

  • ✖ Ubuntu xenial

  • ✖ Ubuntu trusty

  • ✖ CentOS 7

  1. Download sunshine.AppImage to your home directory.

    cd ~
wget https://github.com/LizardByte/Sunshine/releases/latest/download/sunshine.AppImage

  2. Open terminal and run the following code.

    ./sunshine.AppImage --install
Start:
./sunshine.AppImage --install && ./sunshine.AppImage
Uninstall:
./sunshine.AppImage --remove

  1. Open terminal and run the following code.

    wget https://github.com/LizardByte/Sunshine/releases/latest/download/sunshine.pkg.tar.zst
pacman -U --noconfirm sunshine.pkg.tar.zst
Uninstall:
pacman -R sunshine

  1. Download sunshine-{distro}-{distro-version}-{arch}.deb and run the following code.

    sudo apt install -f ./sunshine-{distro}-{distro-version}-{arch}.deb

    Note

    The {distro-version} is the version of the distro we built the package on. The {arch} is the architecture of your operating system.

    Tip

    You can double click the deb file to see details about the package and begin installation.

Uninstall:
sudo apt remove sunshine

Caution

Use distro-specific packages instead of the Flatpak if they are available.

Important

The instructions provided here are for the version supplied in the latest release, which does not necessarily match the version in the Flathub repository!

  1. Install Flatpak as required.

  2. Download sunshine_{arch}.flatpak and run the following code.

    Note

    Be sure to replace {arch} with the architecture for your operating system.

    System level (recommended)
    flatpak install --system ./sunshine_{arch}.flatpak
    User level
    flatpak install --user ./sunshine_{arch}.flatpak
    Additional installation (required)
    flatpak run --command=additional-install.sh dev.lizardbyte.sunshine
Start:
X11 and NVFBC capture (X11 Only)
flatpak run dev.lizardbyte.sunshine
KMS capture (Wayland & X11)
sudo -i PULSE_SERVER=unix:$(pactl info | awk '/Server String/{print$3}') \
  flatpak run dev.lizardbyte.sunshine
Uninstall:
flatpak run --command=remove-additional-install.sh dev.lizardbyte.sunshine
flatpak uninstall --delete-data dev.lizardbyte.sunshine

  1. Add rpmfusion repositories by running the following code.

    sudo dnf install \
  https://mirrors.rpmfusion.org/free/fedora/rpmfusion-free-release-$(rpm -E %fedora).noarch.rpm \
  https://mirrors.rpmfusion.org/nonfree/fedora/rpmfusion-nonfree-release-$(rpm -E %fedora).noarch.rpm

  2. Download sunshine-{distro}-{distro-version}-{arch}.rpm and run the following code.

    sudo dnf install ./sunshine-{distro}-{distro-version}-{arch}.rpm

    Note

    The {distro-version} is the version of the distro we built the package on. The {arch} is the architecture of your operating system.

    Tip

    You can double click the rpm file to see details about the package and begin installation.

Uninstall:
sudo dnf remove sunshine

The deb, rpm, zst, Flatpak and AppImage packages should handle these steps automatically. Third party packages may not.

Sunshine needs access to uinput to create mouse and gamepad events.

  1. Create and reload udev rules for uinput.
    echo 'KERNEL=="uinput", SUBSYSTEM=="misc", OPTIONS+="static_node=uinput", TAG+="uaccess"' | \
sudo tee /etc/udev/rules.d/60-sunshine.rules
sudo udevadm control --reload-rules
sudo udevadm trigger
sudo modprobe uinput
  2. Enable permissions for KMS capture.

    Warning

    Capture of most Wayland-based desktop environments will fail unless this step is performed.

    Note

    cap_sys_admin may as well be root, except you don’t need to be root to run it. It is necessary to allow Sunshine to use KMS capture.

    Enable
    sudo setcap cap_sys_admin+p $(readlink -f $(which sunshine))
    Disable (for Xorg/X11 only)
    sudo setcap -r $(readlink -f $(which sunshine))

  3. Optionally, configure autostart service

    • filename: ~/.config/systemd/user/sunshine.service

    • contents:
      [Unit]
Description=Sunshine self-hosted game stream host for Moonlight.
StartLimitIntervalSec=500
StartLimitBurst=5

[Service]
ExecStart=<see table>
Restart=on-failure
RestartSec=5s
#Flatpak Only
#ExecStop=flatpak kill dev.lizardbyte.sunshine

[Install]
WantedBy=graphical-session.target

      package

      ExecStart

      Auto Configured

      aur

      /usr/bin/sunshine

      ✔

      deb

      /usr/bin/sunshine

      ✔

      rpm

      /usr/bin/sunshine

      ✔

      AppImage

      ~/sunshine.AppImage

      ✔

      Flatpak

      flatpak run dev.lizardbyte.sunshine

      ✔
    Start once
    systemctl --user start sunshine
    Start on boot
    systemctl --user enable sunshine
  4. Reboot
    sudo reboot now

Important

Sunshine on macOS is experimental. Gamepads do not work.

  1. Install Homebrew

  2. Update the Homebrew sources and install Sunshine.

    brew tap LizardByte/homebrew
brew install sunshine

  1. Install MacPorts

  2. Update the Macports sources.

    sudo nano /opt/local/etc/macports/sources.conf
    Add this line, replacing your username, below the line that starts with rsync.

    file:///Users/<username>/ports

    Ctrl+x, then Y to exit and save changes.

  3. Download and install by running the following code.

    mkdir -p ~/ports/multimedia/sunshine
cd ~/ports/multimedia/sunshine
curl -OL https://github.com/LizardByte/Sunshine/releases/latest/download/Portfile
cd ~/ports
portindex
sudo port install sunshine

  4. The first time you start Sunshine, you will be asked to grant access to screen recording and your microphone.

  5. Optionally, install service

    sudo port load Sunshine
Uninstall:
sudo port uninstall sunshine

Sunshine can only access microphones on macOS due to system limitations. To stream system audio use Soundflower or BlackHole.

Note

Command Keys are not forwarded by Moonlight. Right Option-Key is mapped to CMD-Key.

Caution

Gamepads are not currently supported.

  1. Download and install sunshine-windows-installer.exe

Attention

You should carefully select or unselect the options you want to install. Do not blindly install or enable features.

To uninstall, find Sunshine in the list here and select “Uninstall” from the overflow menu. Different versions of Windows may provide slightly different steps for uninstall.

Warning

By using this package instead of the installer, performance will be reduced. This package is not recommended for most users. No support will be provided!

  1. Download and extract sunshine-windows-portable.zip

  2. Open command prompt as administrator

  3. Firewall rules

    Install:
    cd /d {path to extracted directory}
scripts/add-firewall-rule.bat
    Uninstall:
    cd /d {path to extracted directory}
scripts/delete-firewall-rule.bat

  4. Virtual Gamepad Support

    Install:
    cd /d {path to extracted directory}
scripts/install-gamepad.bat
    Uninstall:
    cd /d {path to extracted directory}
scripts/uninstall-gamepad.bat

  5. Windows service

    Install:
    cd /d {path to extracted directory}
scripts/install-service.bat
scripts/autostart-service.bat
    Uninstall:
    cd /d {path to extracted directory}
scripts/uninstall-service.bat

To uninstall, delete the extracted directory which contains the sunshine.exe file.

Usage#

  1. If Sunshine is not installed/running as a service, then start sunshine with the following command, unless a start command is listed in the specified package install instructions above.

    Note

    A service is a process that runs in the background. This is the default when installing Sunshine from the Windows installer. Running multiple instances of Sunshine is not advised.

    Basic usage
    sunshine
    Specify config file
    sunshine <directory of conf file>/sunshine.conf

    Note

    You do not need to specify a config file. If no config file is entered the default location will be used.

    Attention

    The configuration file specified will be created if it doesn’t exist.

    Start Sunshine over SSH (Linux/X11)

    Assuming you are already logged into the host, you can use this command

    ssh <user>@<ip_address> 'export DISPLAY=:0; sunshine'

    If you are logged into the host with only a tty (teletypewriter), you can use startx to start the X server prior to executing sunshine. You nay need to add sleep between startx and sunshine to allow more time for the display to be ready.

    ssh <user>@<ip_address> 'startx &; export DISPLAY=:0; sunshine'

    Tip

    You could also utilize the ~/.bash_profile or ~/.bashrc files to setup the DISPLAY variable.

    See also

    See Remote SSH Headless Setup on how to setup a headless streaming server without autologin and dummy plugs (X11 + NVidia GPUs)

  2. Configure Sunshine in the web ui

    The web ui is available on https://localhost:47990 by default. You may replace localhost with your internal ip address.

    Attention

    Ignore any warning given by your browser about “insecure website”. This is due to the SSL certificate being self signed.

    Caution

    If running for the first time, make sure to note the username and password that you created.

    1. Add games and applications.

    2. Adjust any configuration settings as needed.

  3. In Moonlight, you may need to add the PC manually.

  4. When Moonlight requests for you insert the pin:

    • Login to the web ui

    • Go to “PIN” in the Navbar

    • Type in your PIN and press Enter, you should get a Success Message

    • In Moonlight, select one of the Applications listed

Network#

The Sunshine user interface will be available on port 47990 by default.

Warning

Exposing ports to the internet can be dangerous. Do this at your own risk.

Arguments#

To get a list of available arguments run the following:

sunshine --help

./sunshine.AppImage --help

flatpak run --command=sunshine dev.lizardbyte.Sunshine --help

Shortcuts#

All shortcuts start with CTRL + ALT + SHIFT, just like Moonlight

  • CTRL + ALT + SHIFT + N - Hide/Unhide the cursor (This may be useful for Remote Desktop Mode for Moonlight)

  • CTRL + ALT + SHIFT + F1/F12 - Switch to different monitor for Streaming

Application List#

  • Applications should be configured via the web UI.

  • A basic understanding of working directories and commands is required.

  • You can use Environment variables in place of values

  • $(HOME) will be replaced by the value of $HOME

  • $$ will be replaced by $, e.g. $$(HOME) will be become $(HOME)

  • env - Adds or overwrites Environment variables for the commands/applications run by Sunshine

  • "Variable name":"Variable value"

  • apps - The list of applications

  • Advanced users may want to edit the application list manually. The format is json.

  • Example json application:
    {
    "cmd": "command to open app",
    "detached": [
        "some-command",
        "another-command"
    ],
    "image-path": "/full-path/to/png-image",
    "name": "An App",
    "output": "/full-path/to/command-log-file",
    "prep-cmd": [
        {
            "do": "some-command",
            "undo": "undo-that-command"
        }
    ],
    "working-dir": "/full-path/to/working-directory"
}

    • cmd - The main application

    • detached - A list of commands to be run and forgotten about

      • If not specified, a process is started that sleeps indefinitely

    • image-path - The full path to the cover art image to use.

    • name - The name of the application/game

    • output - The file where the output of the command is stored

    • auto-detach - Specifies whether the app should be treated as detached if it exits quickly

    • wait-all - Specifies whether to wait for all processes to terminate rather than just the initial process

    • exit-timeout - Specifies how long to wait in seconds for the process to gracefully exit (default: 5 seconds)

    • prep-cmd - A list of commands to be run before/after the application

      • If any of the prep-commands fail, starting the application is aborted

      • do - Run before the application

        • If it fails, all undo commands of the previously succeeded do commands are run

      • undo - Run after the application has terminated

        • Failures of undo commands are ignored

    • working-dir - The working directory to use. If not specified, Sunshine will use the application directory.

  • For more examples see app examples.

Considerations#

  • On Windows, Sunshine uses the Desktop Duplication API which only supports capturing from the GPU used for display. If you want to capture and encode on the eGPU, connect a display or HDMI dummy display dongle to it and run the games on that display.

  • When an application is started, if there is an application already running, it will be terminated.

  • When the application has been shutdown, the stream shuts down as well.

    • For example, if you attempt to run steam as a cmd instead of detached the stream will immediately fail. This is due to the method in which the steam process is executed. Other applications may behave similarly.

    • This does not apply to detached applications.

  • The “Desktop” app works the same as any other application except it has no commands. It does not start an application, instead it simply starts a stream. If you removed it and would like to get it back, just add a new application with the name “Desktop” and “desktop.png” as the image path.

  • For the Linux flatpak you must prepend commands with flatpak-spawn --host.

HDR Support#

Streaming HDR content is officially supported on Windows hosts and experimentally supported for Linux hosts.

  • General HDR support information and requirements:

    • HDR must be activated in the host OS, which may require an HDR-capable display or EDID emulator dongle connected to your host PC.

    • You must also enable the HDR option in your Moonlight client settings, otherwise the stream will be SDR (and probably overexposed if your host is HDR).

    • A good HDR experience relies on proper HDR display calibration both in the OS and in game. HDR calibration can differ significantly between client and host displays.

    • You may also need to tune the brightness slider or HDR calibration options in game to the different HDR brightness capabilities of your client’s display.

    • Some GPUs video encoders can produce lower image quality or encoding performance when streaming in HDR compared to SDR.

  • Additional information:

  • HDR streaming is supported for Intel, AMD, and NVIDIA GPUs that support encoding HEVC Main 10 or AV1 10-bit profiles.

  • We recommend calibrating the display by streaming the Windows HDR Calibration app to your client device and saving an HDR calibration profile to use while streaming.

  • Older games that use NVIDIA-specific NVAPI HDR rather than native Windows HDR support may not display properly in HDR.

  • HDR streaming is supported for Intel and AMD GPUs that support encoding HEVC Main 10 or AV1 10-bit profiles using VAAPI.

  • The KMS capture backend is required for HDR capture. Other capture methods, like NvFBC or X11, do not support HDR.

  • You will need a desktop environment with a compositor that supports HDR rendering, such as Gamescope or KDE Plasma 6.

See also

Arch wiki on HDR Support for Linux and Reddit Guide for HDR Support for AMD GPUs

Tutorials and Guides#

Tutorial videos are available here.

Guides are available here.

Community!

Tutorials and Guides are community generated. Want to contribute? Reach out to us on our discord server.