Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/LizardByte/Sunshine/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Sunshine can run as a systemd service on Linux, providing automatic startup, process management, and logging integration. Two service types are available:
  • sunshine.service - Unprivileged service for XDG Portal or X11 capture
  • sunshine-kms.service - Privileged service for KMS (Kernel Mode Setting) capture

​
Prerequisites

  • Linux system with systemd
  • Sunshine installed from package manager
  • User account with appropriate permissions

​
Service Types

Runs as your user account with access to your display session. Best for:
  • Desktop installations
  • X11 or Wayland capture
  • Standard gaming setups

​
System Service

Runs as a system service with elevated privileges. Best for:
  • Headless servers
  • KMS capture
  • Multi-user environments

​
Installation

1
Step 1: Verify Service Files
2
After installing Sunshine, verify the service files exist:
3
# User service files
ls -l ~/.config/systemd/user/sunshine*.service

# Or system service files (if installed system-wide)
ls -l /usr/lib/systemd/user/sunshine*.service
4
Step 2: Create User Service Directory (if needed)
5
mkdir -p ~/.config/systemd/user
6
Step 3: Choose Service Type
7
Decide which service to use based on your needs:
8
XDG Portal / X11 (Standard)
systemctl --user enable sunshine.service
KMS Capture (Advanced)
systemctl --user enable sunshine-kms.service

​
Service Configuration

​
Standard Service (sunshine.service)

Example service file for unprivileged capture:
sunshine.service
[Unit]
Description=Sunshine - Self-hosted game stream host for Moonlight
StartLimitIntervalSec=500
StartLimitBurst=5
Conflicts=sunshine-kms.service
After=graphical-session.target xdg-desktop-autostart.target xdg-desktop-portal.service

[Service]
# Avoid starting Sunshine before the desktop is fully initialized
ExecStartPre=/bin/sleep 5
ExecStart=/usr/bin/sunshine
Restart=on-failure
RestartSec=5s
NoNewPrivileges=true

[Install]
WantedBy=graphical-session.target

​
KMS Service (sunshine-kms.service)

Example service file for KMS capture:
sunshine-kms.service
[Unit]
Description=Sunshine - Self-hosted game stream host for Moonlight (KMS)
StartLimitIntervalSec=500
StartLimitBurst=5
Conflicts=sunshine.service
After=graphical-session.target xdg-desktop-autostart.target

[Service]
# Avoid starting Sunshine before the desktop is fully initialized
ExecStartPre=/bin/sleep 5
ExecStart=/usr/bin/sunshine
Restart=on-failure
RestartSec=5s

[Install]
WantedBy=graphical-session.target

​
Custom Service File

To customize the service, create an override: 
systemctl --user edit sunshine.service
Add customizations: 
[Service]
# Custom environment variables
Environment="DISPLAY=:0"
Environment="PULSE_SERVER=unix:/run/user/1000/pulse/native"

# Custom startup delay
ExecStartPre=/bin/sleep 10

# Resource limits
MemoryLimit=2G
CPUQuota=80%

​
Service Management

​
Enable Service (Start on Boot)

# Disable KMS service first (if enabled)
systemctl --user --now disable sunshine-kms.service

# Enable standard service
systemctl --user enable sunshine.service

​
Start Service Immediately

# Start standard service
systemctl --user start sunshine.service

# Or start KMS service
systemctl --user start sunshine-kms.service

​
Enable and Start Together

# Enable and start in one command
systemctl --user enable --now sunshine.service

​
Stop Service

systemctl --user stop sunshine.service

​
Restart Service

systemctl --user restart sunshine.service

​
Disable Service

# Disable and stop
systemctl --user disable --now sunshine.service

​
Monitoring

​
Check Service Status

systemctl --user status sunshine.service
Example output: 
● sunshine.service - Sunshine - Self-hosted game stream host
     Loaded: loaded (/home/user/.config/systemd/user/sunshine.service; enabled)
     Active: active (running) since Mon 2024-03-04 12:00:00 EST; 2h 15min ago
   Main PID: 12345 (sunshine)
      Tasks: 24 (limit: 18972)
     Memory: 145.2M
        CPU: 3.521s
     CGroup: /user.slice/user-1000.slice/sunshine.service
             └─12345 /usr/bin/sunshine

​
View Service Logs

journalctl --user -u sunshine.service

​
Log Filtering

# Errors only
journalctl --user -u sunshine.service -p err

# Last hour
journalctl --user -u sunshine.service --since "1 hour ago"

# Specific date range
journalctl --user -u sunshine.service --since "2024-03-01" --until "2024-03-04"

​
Troubleshooting

​
Service Won’t Start

1
Step 1: Check Service Status
2
systemctl --user status sunshine.service
3
Step 2: View Detailed Logs
4
journalctl --user -u sunshine.service -n 50
5
Step 3: Verify Binary Location
6
which sunshine
# Should output: /usr/bin/sunshine
7
Step 4: Test Manual Start
8
# Stop service
systemctl --user stop sunshine.service

# Run manually to see errors
sunshine

​
Display Not Available

# Set DISPLAY environment variable
systemctl --user edit sunshine.service
Add: 
[Service]
Environment="DISPLAY=:0"
Then reload and restart: 
systemctl --user daemon-reload
systemctl --user restart sunshine.service

​
Service Crashes on Start

Increase startup delay: 
systemctl --user edit sunshine.service
Add: 
[Service]
ExecStartPre=/bin/sleep 10

​
Permission Denied Errors

Add user to required groups: 
# Add to input group (for gamepad/keyboard/mouse)
sudo usermod -aG input $USER

# Add to video group (for GPU access)
sudo usermod -aG video $USER

# Add to audio group (for audio capture)
sudo usermod -aG audio $USER

# Log out and back in for changes to take effect

​
Service Stops After Logout

Enable lingering for your user: 
sudo loginctl enable-linger $USER
This keeps user services running after logout.

​
Advanced Configuration

​
Resource Limits

Control resource usage: 
[Service]
# Memory limit
MemoryMax=2G
MemoryHigh=1.5G

# CPU quota (80% of one core)
CPUQuota=80%

# Process limits
TasksMax=100

# File descriptor limit
LimitNOFILE=4096

​
Restart Behavior

[Service]
# Always restart (even on clean exit)
Restart=always

# Restart delay
RestartSec=10s

# Prevent restart loops
StartLimitIntervalSec=500
StartLimitBurst=5

​
Environment Variables

[Service]
# Display
Environment="DISPLAY=:0"
Environment="WAYLAND_DISPLAY=wayland-0"

# Audio
Environment="PULSE_SERVER=unix:/run/user/1000/pulse/native"

# Custom config
Environment="SUNSHINE_CONFIG=/home/user/.config/sunshine/sunshine.conf"

​
Dependencies

Control service startup order: 
[Unit]
# Start after these services
After=graphical-session.target
After=network-online.target
After=pulseaudio.service

# Require these services
Requires=network-online.target

# Stop if these services stop
BindsTo=graphical-session.target

​
Multiple Instances

Run multiple Sunshine instances:

​
Create Instance Service

# Copy service file
cp ~/.config/systemd/user/sunshine.service \
   ~/.config/systemd/user/sunshine@.service
Edit for instance support:
sunshine@.service
[Unit]
Description=Sunshine Instance %i

[Service]
ExecStart=/usr/bin/sunshine /home/user/.config/sunshine/%i/sunshine.conf

[Install]
WantedBy=graphical-session.target

​
Start Instances

# Create config directories
mkdir -p ~/.config/sunshine/instance1
mkdir -p ~/.config/sunshine/instance2

# Start instances
systemctl --user start sunshine@instance1.service
systemctl --user start sunshine@instance2.service

​
System-Wide Service

For system-level installation (not recommended for most users): 
# Create system service file
sudo nano /etc/systemd/system/sunshine.service

[Unit]
Description=Sunshine Game Streaming
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=sunshine
Group=sunshine
ExecStart=/usr/bin/sunshine
Restart=on-failure
RestartSec=5s

[Install]
WantedBy=multi-user.target
Manage system service: 
# Enable
sudo systemctl enable sunshine.service

# Start
sudo systemctl start sunshine.service

# Check status
sudo systemctl status sunshine.service

# View logs
sudo journalctl -u sunshine.service -f

Build docs developers (and LLMs) love

Get started for freeTalk to us