Skip to main content
This guide will walk you through getting Sunshine up and running quickly. By the end, you’ll be streaming from your host computer to a Moonlight client.

​
Prerequisites

Before you begin, ensure you have:
  • Completed the installation for your platform
  • A device with a Moonlight client installed (download Moonlight)
  • Both host and client on the same network (for initial setup)

​
Initial Setup

1

Platform-Specific Setup

Some platforms require additional configuration after installation.
Configure ServicesChoose between unprivileged (XDG Portal/X11) or privileged (KMS) capture:Start once:
systemctl --user start sunshine
Enable on boot (unprivileged):
systemctl --user --now disable sunshine-kms
systemctl --user --now enable sunshine
Enable on boot (KMS - privileged):
systemctl --user --now disable sunshine
systemctl --user --now enable sunshine-kms
Two service unit files are available: sunshine for unprivileged XDG Portal or X11 capture, and sunshine-kms for privileged KMS capture.
Virtual Input DevicesIf inputs aren’t working, add your user to the input group:
sudo usermod -a -G input $USER
Log out and log back in for changes to take effect.
2

Start Sunshine

If Sunshine is not running as a service, start it manually:
sunshine
A service is a process that runs in the background. When installed from the Windows installer or using systemd on Linux, Sunshine runs as a service automatically.
Optional: Specify a custom config file location:
sunshine /path/to/sunshine.conf
SSH on Linux (X11):
ssh user@host 'export DISPLAY=:0; sunshine'
3

Access the Web UI

Open your web browser and navigate to:
https://localhost:47990
Replace localhost with your server’s IP address if accessing from another device.
Your browser will warn about an “insecure website” due to the self-signed SSL certificate. This is normal - proceed past the warning.
On first access, you’ll be prompted to create:
  • A username
  • A password
Save these credentials securely - you’ll need them to access the web UI in the future.
4

Configure Sunshine

Configure Sunshine through the web UI:Set Your ThemeChoose your preferred theme from the dropdown menu in the navbar.Add ApplicationsNavigate to the “Applications” tab and add games or applications you want to stream:
  1. Click “Add New”
  2. Enter the application name (e.g., “Steam”, “Desktop”)
  3. Set the command to launch the application
  4. Configure the working directory if needed
  5. Optionally add an image (e.g., steam.png, desktop.png)
  6. Save the application
The “Desktop” app works differently - it has no commands and simply starts a stream of your desktop. If you removed it, create a new application named “Desktop” with “desktop.png” as the image.
Adjust SettingsExplore the “Configuration” tab to:
  • Set video encoding preferences
  • Configure audio settings
  • Adjust network settings
  • Enable HDR if supported
Use the search bar to quickly find specific settings.
Most default settings work well for typical setups. Only adjust if you encounter issues or have specific requirements.
5

Pair Moonlight Client

On your client device running Moonlight:
  1. Add PC Manually (if not auto-discovered)
    • Click the ”+” or “Add PC” button
    • Enter your host computer’s IP address
  2. Initiate Pairing
    • Moonlight will display a 4-digit PIN code
  3. Enter PIN in Sunshine
    • In the Sunshine web UI, navigate to the “PIN” tab in the navbar
    • Enter the 4-digit PIN shown in Moonlight
    • Provide a name for the client device
    • Press Enter or click Submit
You should see a success message in the web UI. The client is now authorized to connect.
6

Start Streaming

In your Moonlight client:
  1. Select your paired host computer
  2. Choose an application from the list (e.g., “Desktop” or a game)
  3. Click to start streaming
The stream should start within a few seconds!
Start with the “Desktop” app to test basic functionality before streaming games.

​
Keyboard Shortcuts

While streaming, these shortcuts are available (all start with Ctrl+Alt+Shift):
ShortcutAction
Ctrl+Alt+Shift+NHide/Unhide cursor (useful for Remote Desktop Mode)
Ctrl+Alt+Shift+F1 to F12Switch to different monitor

​
Troubleshooting

If you encounter issues:

​
Check Logs

  1. Navigate to the “Troubleshooting” tab in the web UI
  2. Review warning and error messages
  3. Click on individual messages for detailed information

​
Common Issues

Linux/FreeBSD: Add your user to the input group:
# Linux
sudo usermod -a -G input $USER

# FreeBSD
pw groupmod input -m $USER
Log out and log back in.
Install ViGEmBus from the Troubleshooting tab in the web UI, then restart your computer.
The application may be starting as a detached process. Try:
  • Use “detached” mode in the application configuration
  • For Steam, this is expected behavior when launched directly
  • Check if the application command is correct
Verify:
  • Sunshine is running
  • Host and client are on the same network
  • Firewall allows connections on ports 47984-47990 (TCP) and 47998-48000 (UDP)
  • Try adding the PC manually by IP address in Moonlight
Try:
  • Use a wired connection instead of WiFi
  • Lower the resolution or bitrate in Moonlight settings
  • Enable hardware encoding in Sunshine configuration
  • Close bandwidth-intensive applications

​
Get Help

For additional support:

​
Advanced Topics

Once you have basic streaming working, explore these advanced features:

HDR Streaming

Learn how to configure HDR streaming for supported platforms (Windows officially, Linux experimentally).

Application Configuration

Advanced application setup including environment variables, prep/post commands, and working directories.

Network Configuration

Configure port forwarding, UPnP, and remote access for streaming over the internet.

Performance Tuning

Optimize encoding settings, capture methods, and system configuration for best performance.

​
Next Steps

Now that you’re up and running, explore the rest of the documentation to learn more about:
  • Detailed configuration options
  • Platform-specific optimizations
  • Advanced networking and remote access
  • Command-line arguments and scripting
Experiment with different settings to find what works best for your specific hardware and network setup.

Build docs developers (and LLMs) love

Get started for freeTalk to us