There’s a moment when you’re setting up a headless gaming rig and the screen just stays off—no host output, no game stream, nothing. If you’ve installed Sunshine on Fedora and the service won’t start, you’re likely not dealing with a GPU driver issue at all. More often than not, the culprit is a simple mismatch in your systemd service file, pointing to the wrong Sunshine binary. Before you dive into logs, know this: a Flatpak installation and a native package installation expect different file paths, and getting those mixed up is the single most common reason why your streaming setup fails without producing a single application log.

Key facts at a glance

1Native install
  • Binary path: /usr/bin/sunshine
  • Recommended for most Fedora setups
  • Direct access to system libraries
2Flatpak install
  • Binary path: flatpak run dev.lizardbyte.sunshine
  • Sandboxed with its own dependencies
  • Requires different service file configuration
3Service location
  • User service: ~/.config/systemd/user/sunshine.service
  • Must be enabled with systemctl --user enable sunshine
  • Logs via journalctl --user -u sunshine
4Headless setup
  • SSH access is essential for remote management
  • Flatpak-specific service flags may be required
  • Testing with systemctl --user status after config changes

Active users: millions of monthly streamers · Config file: ~/.config/sunshine/sunshine.conf · Logs: journalctl --user -u sunshine -f

When a service fails silently, the issue is often in the details of how you launched it. The LizardByte documentation explains that the native install expects the service file to reference ExecStart=/usr/bin/sunshine, while a Flatpak install must use ExecStart=flatpak run dev.lizardbyte.sunshine. These two are not interchangeable, and mixing them up leads to a service that appears to start but immediately dies, or one that never initializes at all.

Diagnosing the silent failure

The first sign of trouble is when systemctl --user status sunshine shows a failed state after you’ve triple-checked your configuration. If you installed via Flatpak but your service file points to /usr/bin/sunshine, the service will exit with a “file not found” error that may not even appear in the application logs because the binary never ran. The LizardByte usage guide confirms that the user service file is expected at ~/.config/systemd/user/sunshine.service.

Check your binary path first

  • Native install: which sunshine should return /usr/bin/sunshine
  • Flatpak install: flatpak list | grep -i sunshine confirms the app ID
  • Service file check: grep ExecStart ~/.config/systemd/user/sunshine.service

The documentation notes that the service file example uses Restart=on-failure and RestartSec=5s, which can make a misconfigured service loop silently in the background, consuming CPU without ever producing a visible error. Adding StartLimitIntervalSec=500 and StartLimitBurst=5 caps this looping behavior and surfaces the problem sooner.

Bottom line: A broken Sunshine service on Fedora is usually a path mismatch in the systemd unit file—read the path before you blame the logs.

Why the Flatpak vs. native distinction matters

The choice between a native package and a Flatpak install changes more than just where the binary lives—it changes how Sunshine interacts with the system. A native install has direct access to hardware acceleration libraries and can be optimized with custom kernels. Flatpak isolates Sunshine in a sandbox, which means it needs special permissions to access your GPU and possibly your network socket. The LizardByte documentation highlights that the Flatpak service may require ExecStop=flatpak kill dev.lizardbyte.sunshine to shut down cleanly, something a native service doesn’t need.

What the documentation says

  • Native installs use ExecStart=/usr/bin/sunshine per LizardByte documentation
  • Flatpak installs require flatpak run dev.lizardbyte.sunshine per the same source
  • The service file example in the docs recommends checking journald for log output from the service

For headless systems, the situation gets more nuanced. If you’re running Fedora on a machine without a monitor or with a virtual display, Sunshine needs to be configured to start even when no graphical session is active. A community guide on setting up headless Sunshine with SSH confirms that SSH access is the first step—you need a way into the box before you can even see what the service is doing. The guide walks through configuring SSH with ssh-copy-id and ensuring the service is set to start at boot with systemctl enable --now sunshine.

Bottom line: The Flatpak sandbox demands a different service file—using the native path with a Flatpak install is the #1 reason your Sunshine service fails silently.

The implication: verify your install type before copying any service file example.

Troubleshooting from the outside in

When you’re stuck with a service that won’t start, work backward from the symptom. If journalctl --user -u sunshine -f shows nothing, the service likely never got far enough to write logs. Check the service file for obvious errors—a stray character or an incorrect path will cause systemd to fail the unit before it even attempts to run it.

Common failure points and fixes

  • Wrong binary path: Verify with ls -l /usr/bin/sunshine or flatpak info dev.lizardbyte.sunshine
  • Missing environment variables: The Sunshine service may need Environment=DISPLAY=:0 for GUI mode
  • Service not enabled: systemctl --user enable --now sunshine ensures it starts on boot

The LizardByte usage docs mention that the service file example sets StartLimitIntervalSec=500 and StartLimitBurst=5 to limit restart loops. If you’re seeing the service restart repeatedly without error, these settings will help you catch the issue. The docs also describe how systemd can forward standard output from a Flatpak app to journald, which means even if Sunshine itself crashes, you’ll see the crash output in the system journal.

The upshot

A service file that works on a native install will fail on Flatpak, and vice versa. The path mismatch is the first thing to check, and the fix is often a one-line change.

The pattern is clear: path mismatches are the root cause of silent service failures.

Step-by-step recovery for Fedora headless systems

If you’ve confirmed the path is correct and the service still won’t start, the problem is likely environmental. For headless setups, Sunshine may need to run with a virtual display. The documentation for headless Sunshine suggests using Xvfb or a dummy driver to create a virtual framebuffer, which gives the streaming service the graphical context it needs without a physical monitor.

Recovery steps

  • Reinstall the service file: Copy the example from the docs and adjust only the path
  • Test manually: Run the command from ExecStart as your user to see if it launches
  • Check QoL flags: Flatpak installs may need --share=network to access the host’s network socket
  • Run a dry-run: systemd-analyze verify ~/.config/systemd/user/sunshine.service catches file-level issues

The LizardByte documentation’s headless SSH guide walks through a complete setup that assumes a minimal GUI environment is already present, using X forwarding if necessary. The guide also shows a systemd service that wraps both the Sunshine core and required environment variables, so the service starts cleanly even over a remote session.

Why your logs are empty and what to do about it

Empty application logs are a diagnostic goldmine—they tell you the issue is in the launch layer, not in Sunshine’s code. When a systemd unit fails before the binary runs, none of Sunshine’s internal logging has a chance to write anything. The fix is to make the service fail later, at the application level, so you can see what it’s complaining about.

Unblock the log output

  • Run Sunshine in the foreground: /path/to/sunshine from a terminal
  • Look for missing libraries: ldd /usr/bin/sunshine on native builds
  • Check for permission issues: the user running the service needs read/write access to config and logs

The Flatpak variant logs to journald as documented in the Flatpak GitHub issue, but the sandbox may restrict what Sunshine can see. If Sunshine can’t access your GPU or udev rules, it may fail quietly. Running it in the foreground shows these errors immediately, which is why testing manually is the fastest way to find the fix.

Related reading: Sunshine installation and service troubleshooting on Fedora headless systems · Sunshine installation and service troubleshooting on Fedora headless systems

Additional sources

docs.lizardbyte.dev, github.com, unix.stackexchange.com, elektricm.github.io, lumeh.org, auroria.io, packages.ubuntu.com, github.com, docs.lizardbyte.dev

Frequently asked questions

What does “ExecStart” mean in the Sunshine service file?

ExecStart is the command that systemd runs to start the Sunshine service. It must match your installation type: /usr/bin/sunshine for native Fedora packages or flatpak run dev.lizardbyte.sunshine for Flatpak installations.

Why does my Sunshine service fail instantly after I start it?

An instant failure usually means the binary path is wrong or the service is missing required environment variables that point to your display server. Check the ExecStart line and try running the command manually to see the error that systemd is suppressing.

Can I run Sunshine as a system service instead of a user service?

Yes, but running it as a user service is simpler for most setups because it gives the service access to your graphical session and GPU without needing to override polkit or udev rules. The LizardByte documentation covers system service configuration as an alternative.

What is a “headless” setup and what do I need for it?

A headless setup has no physical monitor. You need SSH access, a virtual display like Xvfb, and Sunshine configured to start before login. The official headless SSH guide provides a systemd service that handles this with minimal modifications.

Why isn’t my Sunshine process showing up in journalctl?

If journalctl shows no output, the service likely failed during the path check before Sunshine’s logging was initialized. Verify the ExecStart path, then test by running the command manually and redirecting output to a file to capture warnings.

How do I make Sunshine start at boot with Flatpak on Fedora?

Enable the user service with systemctl --user enable --now sunshine, and ensure your unit file uses ExecStart=flatpak run dev.lizardbyte.sunshine. You also need to set the DISPLAY and XDG_RUNTIME_DIR environment variables in the service file for the sandbox to connect to your session.

The takeaway: checking the binary path in the systemd service file resolves the majority of silent Sunshine failures on Fedora.