Setup ===== .. _latest release: https://github.com/LizardByte/Sunshine/releases/latest 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 :ref:`Third Party Packages `. No support will be provided for third party packages! Install ------- .. tab:: Docker .. 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 :ref:`Docker ` for additional information. .. tab:: Linux **CUDA Compatibility** CUDA is used for NVFBC capture. .. tip:: See `CUDA GPUS `__ to cross reference Compute Capability to your GPU. .. table:: :widths: auto =========================================== ============== ============== ================================ Package CUDA Version Min Driver CUDA Compute Capabilities =========================================== ============== ============== ================================ PKGBUILD User dependent User dependent User dependent 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 unavailable unavailable none sunshine-fedora-39-{arch}.rpm unavailable unavailable none sunshine-ubuntu-20.04-{arch}.deb 11.8.0 450.80.02 35;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 =========================================== ============== ============== ================================ .. tab:: AppImage 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 #. Download ``sunshine.AppImage`` to your home directory. .. code-block:: bash cd ~ wget https://github.com/LizardByte/Sunshine/releases/latest/download/sunshine.AppImage #. Open terminal and run the following code. .. code-block:: bash ./sunshine.AppImage --install Start: .. code-block:: bash ./sunshine.AppImage --install && ./sunshine.AppImage Uninstall: .. code-block:: bash ./sunshine.AppImage --remove .. tab:: Archlinux PKGBUILD #. Open terminal and run the following code. .. code-block:: bash wget https://github.com/LizardByte/Sunshine/releases/latest/download/PKGBUILD makepkg -fi Uninstall: .. code-block:: bash pacman -R sunshine .. tab:: Archlinux pkg #. Open terminal and run the following code. .. code-block:: bash wget https://github.com/LizardByte/Sunshine/releases/latest/download/sunshine.pkg.tar.zst pacman -U --noconfirm sunshine.pkg.tar.zst Uninstall: .. code-block:: bash pacman -R sunshine .. tab:: Debian Package #. Download ``sunshine-{distro}-{distro-version}-{arch}.deb`` and run the following code. .. code-block:: bash 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: .. code-block:: bash sudo apt remove sunshine .. tab:: Flatpak Package .. 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! #. Install `Flatpak `__ as required. #. 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) .. code-block:: bash flatpak install --system ./sunshine_{arch}.flatpak User level .. code-block:: bash flatpak install --user ./sunshine_{arch}.flatpak Additional installation (required) .. code-block:: bash flatpak run --command=additional-install.sh dev.lizardbyte.sunshine Start: X11 and NVFBC capture (X11 Only) .. code-block:: bash flatpak run dev.lizardbyte.sunshine KMS capture (Wayland & X11) .. code-block:: bash sudo -i PULSE_SERVER=unix:$(pactl info | awk '/Server String/{print$3}') \ flatpak run dev.lizardbyte.sunshine Uninstall: .. code-block:: bash flatpak run --command=remove-additional-install.sh dev.lizardbyte.sunshine flatpak uninstall --delete-data dev.lizardbyte.sunshine .. tab:: RPM Package #. Add `rpmfusion` repositories by running the following code. .. code-block:: bash 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 #. Download ``sunshine-{distro}-{distro-version}-{arch}.rpm`` and run the following code. .. code-block:: bash 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: .. code-block:: bash sudo dnf remove sunshine The `deb`, `rpm`, `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. #. Create `udev` rules. .. code-block:: bash echo 'KERNEL=="uinput", SUBSYSTEM=="misc", OPTIONS+="static_node=uinput", TAG+="uaccess"' | \ sudo tee /etc/udev/rules.d/85-sunshine.rules #. Optionally, configure autostart service - filename: ``~/.config/systemd/user/sunshine.service`` - contents: .. code-block:: cfg [Unit] Description=Sunshine self-hosted game stream host for Moonlight. StartLimitIntervalSec=500 StartLimitBurst=5 [Service] ExecStart= Restart=on-failure RestartSec=5s #Flatpak Only #ExecStop=flatpak kill dev.lizardbyte.sunshine [Install] WantedBy=graphical-session.target .. table:: :widths: auto ======== ============================================== =============== 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** .. code-block:: bash systemctl --user start sunshine **Start on boot** .. code-block:: bash systemctl --user enable sunshine #. Additional Setup for KMS .. 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. **Enable** .. code-block:: bash sudo setcap cap_sys_admin+p $(readlink -f $(which sunshine)) **Disable (for Xorg/X11)** .. code-block:: bash sudo setcap -r $(readlink -f $(which sunshine)) #. Reboot .. code-block:: bash sudo reboot now .. tab:: macOS .. important:: Sunshine on macOS is experimental. Gamepads do not work. Other features may not work as expected. .. tab:: dmg .. warning:: The `dmg` does not include runtime dependencies. This package is not recommended for most users. No support will be provided! #. Download the ``sunshine.dmg`` file and install it. Uninstall: .. code-block:: bash cd /etc/sunshine/assets uninstall_pkg.sh .. tab:: Portfile #. Install `MacPorts `__ #. Update the Macports sources. .. code-block:: bash sudo nano /opt/local/etc/macports/sources.conf Add this line, replacing your username, below the line that starts with ``rsync``. ``file:///Users//ports`` ``Ctrl+x``, then ``Y`` to exit and save changes. #. Download and install by running the following code. .. code-block:: bash mkdir -p ~/ports/multimedia/sunshine cd ~/ports/multimedia/sunshine curl -O https://github.com/LizardByte/Sunshine/releases/latest/download/Portfile cd ~/ports portindex sudo port install sunshine #. The first time you start Sunshine, you will be asked to grant access to screen recording and your microphone. #. Optionally, install service .. code-block:: bash sudo port load Sunshine Uninstall: .. code-block:: bash 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. .. tab:: Windows .. tab:: Installer #. 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. .. tab:: Standalone .. 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! #. Download and extract ``sunshine-windows-portable.zip`` #. Open command prompt as administrator #. Firewall rules Install: .. code-block:: bash cd /d {path to extracted directory} scripts/add-firewall-rule.bat Uninstall: .. code-block:: bash cd /d {path to extracted directory} scripts/delete-firewall-rule.bat #. Virtual Gamepad Support Install: .. code-block:: bash cd /d {path to extracted directory} scripts/install-gamepad.bat Uninstall: .. code-block:: bash cd /d {path to extracted directory} scripts/uninstall-gamepad.bat #. Windows service Install: .. code-block:: bash cd /d {path to extracted directory} scripts/install-service.bat scripts/autostart-service.bat Uninstall: .. code-block:: bash cd /d {path to extracted directory} scripts/uninstall-service.bat To uninstall, delete the extracted directory which contains the ``sunshine.exe`` file. Usage ----- #. 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** .. code-block:: bash sunshine **Specify config file** .. code-block:: bash sunshine /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 .. code-block:: bash ssh @ '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. .. code-block:: bash ssh @ 'startx &; export DISPLAY=:0; sunshine' .. tip:: You could also utilize the ``~/.bash_profile`` or ``~/.bashrc`` files to setup the ``DISPLAY`` variable. .. seealso:: See :ref:`Remote SSH Headless Setup ` on how to setup a headless streaming server without autologin and dummy plugs (X11 + NVidia GPUs) #. 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. #. Add games and applications. #. Adjust any configuration settings as needed. #. In Moonlight, you may need to add the PC manually. #. 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: .. tab:: General .. code-block:: bash sunshine --help .. tab:: AppImage .. code-block:: bash ./sunshine.AppImage --help .. tab:: Flatpak .. code-block:: bash 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: .. code-block:: json { "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 :ref:`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: .. tab:: Windows - 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. .. tab:: Linux - 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. .. seealso:: `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 :doc:`here <./guides/guides>`. .. admonition:: Community! Tutorials and Guides are community generated. Want to contribute? Reach out to us on our discord server.