Skip to content

getting_started.md

Latest commit

 

History

History
676 lines (513 loc) · 22.6 KB

getting_started.md

File metadata and controls

676 lines (513 loc) · 22.6 KB

Getting Started

The recommended method for running Sunshine is to use the binaries included in the latest release, unless otherwise specified.

Pre-releases are also available. These should be considered beta, and release artifacts may be missing when merging changes on a faster cadence.

Binaries

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

Note

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

Install

Docker

Warning

The Docker images are not recommended for most users.

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

See Docker for more information.

FreeBSD

Install

  1. Download the appropriate package for your architecture

    Architecture Package
    amd64/x86_64 Sunshine-FreeBSD-14.3-amd64.pkg
    arm64/aarch64 Sunshine-FreeBSD-14.3-aarch64.pkg

  2. Open terminal and run the following command.

    sudo pkg install ./Sunshine-FreeBSD-14.3-{arch}.pkg

Uninstall

sudo pkg delete Sunshine

Linux

CUDA Compatibility

CUDA is used for NVFBC capture.

Note

See CUDA GPUS to cross-reference Compute Capability to your GPU. The table below applies to packages provided by LizardByte. If you use an official LizardByte package, then you do not need to install CUDA.

CUDA Compatibility
CUDA Version Min Driver CUDA Compute Capabilities Package
12.9.1 575.57.08 50;52;60;61;62;70;72;75;80;86;87;89;90;100;101;103;120;121 sunshine.AppImage
sunshine-ubuntu-22.04-{arch}.deb
sunshine-ubuntu-24.04-{arch}.deb
sunshine-debian-trixie-{arch}.deb
sunshine_{arch}.flatpak
Sunshine (copr - Fedora)
Sunshine (copr - OpenSUSE)
sunshine.pkg.tar.zst

AppImage

Caution

Use distro-specific packages instead of the AppImage if they are available. AppImage does not support KMS capture.

Note

The AppImage is built on Ubuntu 22.04, which requires glibc 2.35 or newer and libstdc++ 3.4.11 or newer.

Install
  1. Download sunshine.AppImage into your home directory. 
    cd ~
wget https://github.com/LizardByte/Sunshine/releases/latest/download/sunshine.AppImage
  2. Open terminal and run the following command. 
    ./sunshine.AppImage --install
Run
./sunshine.AppImage --install && ./sunshine.AppImage
Uninstall
./sunshine.AppImage --remove

ArchLinux

Caution

Use AUR packages at your own risk.

Install Prebuilt Packages

Follow the instructions at LizardByte's pacman-repo to add the repository. Then run the following command.

pacman -S sunshine
Install PKGBUILD Archive

Open terminal and run the following command.

wget https://github.com/LizardByte/Sunshine/releases/latest/download/sunshine.pkg.tar.gz
tar -xvf sunshine.pkg.tar.gz
cd sunshine

# install optional dependencies
pacman -S cuda  # Nvidia GPU encoding support
pacman -S libva-mesa-driver  # AMD GPU encoding support

makepkg -si
Uninstall
pacman -R sunshine

Debian/Ubuntu

Install

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

sudo dpkg -i ./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

Fedora/OpenSUSE

Tip

The package name is case-sensitive.

Install (GitHub releases)

Download Sunshine-{version}.{distro+version}.{arch}.rpm and run the following command.

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

Note

The {distro+version} is the distro and distro 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
Install (Copr)

Important

Stable builds are only available if the Sunshine release was made after the Fedora version release. Because of this, it is often recommended to use the beta copr; however, you do not need to regularly update. This could lead to annoyances in rare cases where there may be a breaking change.

  1. Enable copr repository.

    sudo dnf copr enable lizardbyte/stable

    or

    sudo dnf copr enable lizardbyte/beta

  2. Install the package.

    sudo dnf install Sunshine
Uninstall
sudo dnf remove Sunshine

Flatpak

Caution

Use distro-specific packages instead of the Flatpak if they are available. Flatpak does not support KMS capture.

Using this package requires that you have Flatpak installed.

Download (local option)

  1. Download sunshine_{arch}.flatpak and run the following command.

    [!NOTE] Replace {arch} with your system architecture.

Install (system level)

Flathub

flatpak install --system flathub dev.lizardbyte.app.Sunshine

Local

flatpak install --system ./sunshine_{arch}.flatpak
Install (user level)

Flathub

flatpak install --user flathub dev.lizardbyte.app.Sunshine

Local

flatpak install --user ./sunshine_{arch}.flatpak
Additional installation (required)
flatpak run --command=additional-install.sh dev.lizardbyte.app.Sunshine
Run with NVFBC capture (X11 Only) or XDG Portal (Wayland Only)
flatpak run dev.lizardbyte.app.Sunshine
Uninstall
flatpak run --command=remove-additional-install.sh dev.lizardbyte.app.Sunshine
flatpak uninstall --delete-data dev.lizardbyte.app.Sunshine

Homebrew

Important

The Homebrew package is experimental on Linux.

This package requires that you have Homebrew installed.

Install
brew update
brew upgrade
brew tap LizardByte/homebrew
brew install sunshine
Uninstall
brew uninstall sunshine

Tip

For beta you can replace sunshine with sunshine-beta in the above commands.

macOS

Important

Sunshine on macOS is experimental. Gamepads do not work.

DMG

Install

  1. Download and install based on your architecture:

    Architecture Package
    arm64 (Apple Silicon) Sunshine-macOS-arm64.dmg
    x86_64 (Intel) Sunshine-macOS-x86_64.dmg

  2. Open the downloaded .dmg file.

  3. Drag Sunshine.app into the Applications folder.

  4. Eject the disk image.

Uninstall
  1. Quit Sunshine if it is running.
  2. Open Finder, navigate to Applications, and drag Sunshine.app to the Trash.

Homebrew

This package requires that you have Homebrew installed.

Install
brew update
brew upgrade
brew tap LizardByte/homebrew
brew install sunshine
Uninstall
brew uninstall sunshine

Tip

For beta you can replace sunshine with sunshine-beta in the above commands.

Windows

Note

Sunshine supports ARM64 on Windows; however, this should be considered experimental. This version does not properly support GPU scheduling and any hardware acceleration.

Installer (recommended)

Caution

The msi installer is preferred moving forward. Before using a different type of installer, you should manually uninstall the previous installation.

  1. Download and install based on your architecture:

    Architecture Installer
    AMD64/x64 (Intel/AMD) Sunshine-Windows-AMD64-installer.msi
    AMD64/x64 (Intel/AMD) Sunshine-Windows-AMD64-installer.exe
    ARM64 Sunshine-Windows-ARM64-installer.msi
    ARM64 Sunshine-Windows-ARM64-installer.exe

Tip

Installer logs can be found in the following locations.

File log paths
.exe %%PROGRAMFILES%/Sunshine/install.log (AMD64 only)
%%TEMP%/Sunshine/logs/install/
.msi %%TEMP%/Sunshine/logs/install/

Caution

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.

Standalone (lite version)

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 based on your architecture:

    Architecture Installer
    AMD64/x64 (Intel/AMD) Sunshine-Windows-AMD64-portable.zip
    ARM64 Sunshine-Windows-ARM64-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. 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

Initial Setup

After installation, some initial setup is required.

FreeBSD

Virtual Input Devices

Important

To use virtual input devices (keyboard, mouse, gamepads), you must add your user to the input group.

The installation process creates the input group and configures permissions for /dev/uinput. To allow your user to create virtual input devices, run:

pw groupmod input -m $USER

After adding yourself to the group, log out and log back in for the changes to take effect.

Linux

Services

Note

Two service unit files are available. Pick "app-dev.lizardbyte.app.Sunshine" for unprivileged XDG Portal or X11 capture, otherwise pick "sunshine" for privileged KMS capture.

Start once

systemctl --user start sunshine

Start on boot (privileged; swap names for unprivileged XDG capture)

systemctl --user --now disable app-dev.lizardbyte.app.Sunshine
systemctl --user --now enable sunshine

macOS

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

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.

Windows

In order for virtual gamepads to work, you must install ViGEmBus. You can do this from the troubleshooting tab in the web UI, as long as you are running Sunshine as a service or as an administrator. After installation, it is recommended to restart your computer.

ViGEmBus Installation

Usage

Basic 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.

sunshine

Specify config file

sunshine <directory of conf file>/sunshine.conf

Note

This step is optional, you do not need to specify a config file. If no config file is entered, the default location will be used. 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 use the ~/.bash_profile or ~/.bashrc files to set up the DISPLAY variable.

@seealso{See Remote SSH Headless Setup on how to set up a headless streaming server without autologin and dummy plugs (X11 + NVidia GPUs)}

Configuration

Sunshine is configured via the web ui, which is available on https://localhost:47990 by default. You may replace localhost with your internal ip address.

Note

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. Change the web-ui to your desired theme, using the dropdown menu in the navbar. Theme Selection

  2. Add games and applications. Applications

  3. Adjust any configuration settings as needed. You can search for options in the search bar. Configuration

  4. Find Moonlight clients and other tools for Sunshine in the Featured Apps tab. Featured Apps

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

  6. 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, and enter a name of your choosing for the device. You should get a Success Message!
    • In Moonlight, select one of the Applications listed

  7. If you run into issues, logs are available in the Troubleshooting tab. You can navigate through each warning/error message for clues to the issue. Logs

Arguments

To get a list of available arguments, run the following command.

@tabs{ @tab{ General | bash sunshine --help } @tab{ AppImage | bash ./sunshine.AppImage --help } @tab{ Flatpak | bash flatpak run --command=sunshine dev.lizardbyte.app.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. This can only be changed by modifying the apps.json file directly.

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.

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

  • 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.

  • If inputs (mouse, keyboard, gamepads...) aren't working after connecting:

    • On FreeBSD/Linux, add the user running sunshine to the input group.

  • The FreeBSD version of Sunshine is missing some features that are present on Linux. The following are known limitations.

    • Only X11 and Wayland capture are supported
    • DualSense/DS5 emulation is not available due to missing uhid features

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:

@tabs{ @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 here.

@admonition{Community! | Tutorials and Guides are community generated. Want to contribute? Reach out to us on our discord server.}

Previous Next
Overview Changelog
[TOC]