Codakey
Play
← Back to Sunshine

How to Deploy & Use Sunshine

Sunshine Deployment and Usage Guide

1. Prerequisites

Hardware Requirements

  • A host computer with a dedicated GPU (AMD, Intel, or Nvidia) for optimal performance
  • Software encoding is available if hardware encoding is not supported
  • Sufficient RAM and CPU for game streaming (minimum 4GB RAM, modern multi-core CPU recommended)

Software Requirements

  • Operating System: Windows, Linux, macOS, or FreeBSD
  • Moonlight Client: Required on the streaming device (available for Windows, macOS, Linux, Android, iOS, and more)
  • Modern web browser for accessing Sunshine's web UI

Network Requirements

  • Host and client devices on the same local network for best performance
  • Port forwarding may be required for remote access (ports 47984-47990, 48010)
  • Wired Ethernet connection recommended for both host and client

2. Installation

Windows

Using Winget (recommended):

winget install LizardByte.Sunshine

Manual installation:

  1. Download the latest installer from GitHub Releases
  2. Run the installer executable
  3. Sunshine will install as a Windows service

Linux

Using Flatpak (recommended):

flatpak install flathub dev.lizardbyte.app.Sunshine
flatpak run dev.lizardbyte.app.Sunshine

Using Package Manager (Ubuntu/Debian):

# Add Sunshine repository
curl -fsSL https://repo.lizardbyte.dev/apt/key.gpg | sudo gpg --dearmor -o /etc/apt/keyrings/lizardbyte.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/lizardbyte.gpg] https://repo.lizardbyte.dev/apt/ubuntu $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/lizardbyte.list > /dev/null

# Install Sunshine
sudo apt update
sudo apt install sunshine

Using Docker:

docker pull lizardbyte/sunshine
docker run -d --name sunshine \
  --restart unless-stopped \
  -p 47984-47990:47984-47990/tcp \
  -p 48010:48010/tcp \
  -p 47998-48000:47998-48000/udp \
  --device /dev/dri:/dev/dri \
  --device /dev/uinput:/dev/uinput \
  -v /home/$USER/sunshine:/config \
  lizardbyte/sunshine

macOS

Using Homebrew:

brew install --cask sunshine

Building from Source

# Clone the repository
git clone https://github.com/LizardByte/Sunshine.git
cd Sunshine

# Install build dependencies (Linux example)
sudo apt install build-essential cmake ninja-build libavcodec-dev libavformat-dev libavutil-dev libavdevice-dev libopus-dev libpulse-dev libx11-dev libxfixes-dev libxrandr-dev libxtst-dev libcap-dev libevdev-dev libdrm-dev libwayland-dev libxkbcommon-dev libssl-dev

# Build
mkdir build && cd build
cmake -GNinja -B build .
ninja

3. Configuration

Initial Setup

  1. After installation, Sunshine starts automatically as a service
  2. Access the web UI at https://localhost:47990 (or your host's IP address)
  3. Accept the self-signed certificate warning in your browser
  4. Default credentials:
    • Username: sunshine
    • Password: Generated on first run (check logs or config file)

Configuration Files

Location:

  • Windows: C:\ProgramData\Sunshine\config\sunshine.conf
  • Linux: ~/.config/sunshine/sunshine.conf
  • macOS: ~/Library/Application Support/sunshine/sunshine.conf

Key Configuration Options:

# Web UI settings
port = 47990
pkey = sunshine.pem
cert = sunshine.pem

# Streaming settings
fps = 60
bitrate = 100000
hevc_mode = 1
encoder = nvenc  # Options: nvenc, amdvce, vaapi, software

# Audio settings
audio_sink = auto

# Gamepad emulation
gamepad = x360  # Options: x360, ds4, auto

Environment Variables

# Docker-specific
SUNSHINE_USER=your_username
SUNSHINE_PASSWORD=your_password
SUNSHINE_ENCODER=nvenc

# General
DISPLAY=:0  # For Linux with X11
WAYLAND_DISPLAY=wayland-0  # For Wayland

4. Build & Run

Development Build

# Clone and setup
git clone https://github.com/LizardByte/Sunshine.git
cd Sunshine

# Configure with debug options
cmake -B build -DCMAKE_BUILD_TYPE=Debug -DSUNSHINE_ENABLE_TESTS=ON .

# Build
cmake --build build --parallel

# Run locally
./build/sunshine

Production Build

# Release build with optimizations
cmake -B build -DCMAKE_BUILD_TYPE=Release -DSUNSHINE_ASSETS_DIR=/usr/share/sunshine .

# Build and install
cmake --build build --parallel
sudo cmake --install build

Running Manually

# Linux/Unix
sunshine

# Windows (as admin)
sunshine.exe

# With custom config
sunshine --config /path/to/config.conf

5. Deployment

Docker Deployment

docker-compose.yml:

version: '3.8'
services:
  sunshine:
    image: lizardbyte/sunshine:latest
    container_name: sunshine
    restart: unless-stopped
    network_mode: host
    devices:
      - /dev/dri:/dev/dri
      - /dev/uinput:/dev/uinput
    volumes:
      - ./config:/config
      - ./games:/games
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=America/New_York
    privileged: true

System Service (Linux)

# Enable and start the service
sudo systemctl enable sunshine
sudo systemctl start sunshine

# Check status
sudo systemctl status sunshine

# View logs
sudo journalctl -u sunshine -f

Windows Service

# Install as service (done automatically by installer)
sc.exe create Sunshine binPath="C:\Program Files\Sunshine\sunshine.exe" start=auto

# Start service
Start-Service Sunshine

# Check status
Get-Service Sunshine

Cloud Deployment Considerations

  • Port Forwarding: Forward TCP ports 47984-47990 and 48010, UDP ports 47998-48000
  • Security: Use VPN for remote access instead of exposing ports directly
  • Performance: Ensure sufficient GPU resources in cloud environments
  • Storage: Persistent storage for configuration and game data

6. Troubleshooting

Common Issues

1. Web UI not accessible

# Check if Sunshine is running
sudo systemctl status sunshine

# Check firewall rules
sudo ufw allow 47984:47990/tcp
sudo ufw allow 48010/tcp
sudo ufw allow 47998:48000/udp

# Check logs for errors
sudo journalctl -u sunshine -n 50

2. No hardware encoding available

# Check available encoders
sunshine --help | grep encoder

# Verify GPU drivers are installed
nvidia-smi  # For Nvidia
vainfo      # For Intel/AMD VAAPI

# Switch to software encoding in config
encoder = software

3. Authentication failures

# Reset password
sunshine --reset-password

# Or manually edit config
nano ~/.config/sunshine/sunshine.conf
# Remove or change the "creds" section

4. Gamepad not working

# Check uinput permissions
sudo chmod 666 /dev/uinput

# Or add user to input group
sudo usermod -a -G input $USER

# Try different gamepad modes in config
gamepad = auto  # or x360, ds4

5. Performance issues

  • Reduce streaming resolution or bitrate in web UI
  • Ensure both host and client are on wired Ethernet
  • Close unnecessary applications on host
  • Update GPU drivers to latest version
  • Consider using HEVC encoding if supported

Getting Help

Debug Mode

# Run with verbose logging
sunshine --verbosity debug

# Or modify config file
verbosity = debug
log_level = 3
← Project overviewView alternatives to Sunshine →