How To Reset Sunshine Password: Complete Web UI Recovery Guide

To reset your Sunshine game streaming server password, stop the running Sunshine background service and execute the application through your system command line using the --creds argument followed by your new username and password. Alternatively, locating and deleting or renaming the sunshine.sqlite database file inside your local configuration directory forces the application to launch its initial credentials setup wizard on the next startup. This comprehensive recovery guide provides exact terminal syntax, configuration directory paths, and troubleshooting procedures for Windows, Linux, SteamOS, and macOS hosts.

Core Prerequisites and System Access Standards for Web UI Recovery

Before attempting to reset your Sunshine credentials, you must understand how Sunshine manages its authentication layer. Unlike basic web services that store plain-text configuration files, Sunshine uses an SQLite database file named sunshine.sqlite to secure its credentials, pairing keys, and application configurations. This database uses modern hashing protocols to protect your login details from unauthorized access. If you get locked out of the Web UI due to a forgotten password, a changed host IP, or an SSL configuration mismatch, you cannot retrieve the old password; you must perform a clean credential override or database reset.

To successfully execute a credential reset, your host system must meet several operational requirements. Ensure you have direct or remote administrative access (such as SSH or Remote Desktop) to the machine hosting the Sunshine server. Modifying the system configuration files or running the executable with administrative arguments requires elevated privileges.

Host Recovery Checklist

• Administrative Access: Administrator privileges on Windows (via an elevated Command Prompt or PowerShell) or Sudo/Root access on Linux and macOS platforms.
• System Terminal Interface: A functioning command-line interface, such as Windows PowerShell, Command Prompt, macOS Terminal, or Linux Konsole.
• Service Control Knowledge: The ability to stop and start system daemons or background processes, as attempting to write new credentials to an active database will cause database lock errors.
• Time and Budget Benchmarks: This recovery operation takes approximately 5 to 10 minutes to complete. It requires zero monetary budget and utilizes open-source tools already built into your operating system.

Operational Workflows: Reclaiming Web UI Access via Command Line or Database File

There are two primary methods to regain access to your Sunshine Web UI. Method 1 is the cleanest approach, as it uses the command line to overwrite only the username and password without affecting your custom game paths, paired Moonlight clients, or streaming configurations. Method 2 is a fallback option that involves renaming or deleting the local database file, which completely resets Sunshine to its factory defaults.

Step 1: Terminating the Active Sunshine Daemon or Service

Sunshine locks its SQLite database while the background service is running. If you attempt to update credentials or delete configuration files while the process is active, database corruption or file write-lock errors will occur.

On Windows operating systems where Sunshine is installed as a system service, open your Start menu, search for "Services", and open the Services management console. Scroll down to locate the service named Sunshine Service or sunshine. Right-click the service and select "Stop". Alternatively, you can open PowerShell as an Administrator and execute the command Stop-Service -Name sunshine to halt the background process safely.

On Linux distributions running native systemd services, open your system terminal and execute systemctl --user stop sunshine to terminate the user-level background daemon. If you installed Sunshine as a system-wide service, execute sudo systemctl stop sunshine instead.

On Steam Deck consoles running SteamOS, switch to Desktop Mode, open the system monitor (KSysGuard or Dolphin), locate the process named sunshine, and terminate it. If Sunshine is running as a Flatpak, running the flatpak kill command or stopping it via your system tray interface is mandatory before proceeding.

On macOS installations, open your terminal and unload the launch agent using the command launchctl unload ~/Library/LaunchAgents/com.lizardbyte.sunshine.plist to shut down the server process.

Step 2: Performing the Command-Line Credential Override

Once the background service is fully terminated, you can use Sunshine's built-in command-line arguments to force write a new username and password directly into the secure configuration database.

For Windows hosts:

1. Open your Start menu, search for "Command Prompt" or "PowerShell", right-click the application, and select "Run as Administrator".
2. Navigate to the directory where Sunshine is installed. By default, the installer places the application files in the program files directory. Navigate there by executing: cd "C:\Program Files\Sunshine"
3. Run the Sunshine executable with the credential flags. Replace your_username and your_new_password with your desired credentials. Execute: .\sunshine.exe --creds your_username your_new_password
4. The terminal will output confirmation messages indicating that the configuration database has been updated with the new hashed credentials.

For Linux native hosts:

1. Open your terminal application.
2. If Sunshine is installed globally in your system path, execute the credentials update directly: sunshine --creds your_username your_new_password
3. If the command is not in your system path, navigate to the binary location (usually in /usr/bin/ or /usr/local/bin/) and run: ./sunshine --creds your_username your_new_password

For Linux Flatpak hosts (including SteamOS/Steam Deck):

1. Open the Konsole terminal application.
2. Run the credential override through the Flatpak runtime environment using: flatpak run dev.lizardbyte.app.Sunshine --creds your_username your_new_password

For macOS hosts:

1. Open the Terminal application.
2. Navigate to the application contents folder: cd /Applications/Sunshine.app/Contents/MacOS
3. Execute the binary directly with the required flags: ./sunshine --creds your_username your_new_password

Pro-Tip: Ensure your new password contains at least 8 characters and avoids special characters like backslashes, double quotes, or spaces. These characters can sometimes be parsed incorrectly by the terminal or the Sunshine web server parser, leading to authentication issues during login.

Step 3: The Database Deletion Workaround (Fallback Method)

If the command-line override throws errors, fails to write to the database, or if you prefer a complete factory reset, you can manually rename or delete the sunshine.sqlite database file. This action removes all credentials, custom configuration profiles, and paired Moonlight clients, forcing the server to present the initial setup wizard upon the next launch.

1. Navigate to your operating system's dedicated Sunshine configuration directory.
2. Locate the file named sunshine.sqlite.
3. Instead of permanently deleting the file, rename it to sunshine.sqlite.bak. This preserves a backup copy of your previous configuration in case you need to restore your paired devices or application list later.
4. If you also want to clear custom application paths and global settings, you can rename or delete the files named sunshine.conf and apps.json within this same directory.

Warning: Renaming or deleting the sunshine.sqlite file will unpair all currently connected Moonlight streaming client devices (such as your phone, tablet, or TV). You will have to repeat the PIN pairing process for every client machine once the server is back online.

Step 4: Restarting the Service and Initializing the Web UI

After updating the credentials or clearing the database, you must restart the background service to re-initialize the Sunshine web server.

On Windows systems, return to your administrative PowerShell window and execute: Start-Service -Name sunshine. Alternatively, open the Services application, locate Sunshine Service, and click "Start".

On Linux native setups, launch the background daemon using: systemctl --user start sunshine or sudo systemctl start sunshine depending on your installation type.

On Steam Deck systems, launch the Sunshine application from your Application Launcher or return to Game Mode and ensure the Sunshine system shortcut executes successfully.

On macOS setups, reload the launch agent with: launchctl load ~/Library/LaunchAgents/com.lizardbyte.sunshine.plist.

Once the service is active, open a web browser on the host machine or another device on the same local network. Enter the following address into your browser's address bar: https://localhost:47990 (or replace localhost with the local static IP address of your host machine, such as https://192.168.1.100:47990).

When the page loads, your browser will display a security warning stating that the SSL certificate is self-signed or invalid. This warning is normal and expected because Sunshine generates a unique local SSL certificate to encrypt your credentials over your local network. Click on "Advanced" and select "Proceed to localhost (unsafe)" or "Accept the Risk and Continue" to load the login portal. If you performed a command-line reset, enter your new username and password. If you performed a database deletion, you will be prompted to create a brand-new administrator account.

Sunshine Cross-Platform Configuration Paths and Service Commands

The operating system environment directly dictates where Sunshine stores its system-level configuration databases and how the background process is managed. Refer to the table below to locate configuration directories, database files, and system service control commands for your platform.

Diagnostic Protocols for Web UI Verification and Access Failures

When resetting your Sunshine password, you may encounter system-level permission issues, locked file handles, or network verification failures. Use these diagnostic protocols to resolve common errors quickly.

Database Lock Error (SQLITE_BUSY)

• Root Cause: The Sunshine background daemon, system service, or a stray process is still actively running in the background. It maintains an exclusive write-lock on the sunshine.sqlite database file, preventing terminal commands or manual deletion tasks from executing.
• Actionable Fix: Open your system’s process manager (Task Manager on Windows, System Monitor on Linux, or Activity Monitor on macOS). Search for all active processes containing the word "sunshine". Force-terminate all instances of these processes. On Windows, check the Services tab to ensure sunshine_svc is labeled as "Stopped" before running your command-line override arguments.

Command Prompt Displays "Command Not Found" or "Not Recognized"

• Root Cause: The operating system terminal cannot locate the Sunshine executable because the current directory path is not set to the installation folder, or the executable is not in the system's global environment variables (PATH).
• Actionable Fix: Use the change directory command (cd) to navigate directly to the folder containing the binary file. On Windows, execute cd "C:\Program Files\Sunshine". Ensure you prefix the executable with .\ in PowerShell (e.g., .\sunshine.exe --creds admin pass123) to instruct the shell to search the current directory for the application.

Infinite Login Loop or Web UI Rejecting New Credentials

• Root Cause: This issue is typically caused by corrupted browser cookies, outdated local storage data from previous sessions, or an old session state mismatch between the browser and the freshly reset database.
• Actionable Fix: Open your web browser's developer tools (press F12), navigate to the Application or Storage tab, and clear all cookies, local storage, and session storage associated with your Sunshine port (typically port 47990). Alternatively, open a private browsing window (Incognito Mode) and attempt to log in using the newly configured credentials.

Secure Connection Failed or Connection Refused

• Root Cause: Sunshine requires HTTPS connections to secure your credentials. If you attempt to connect using standard HTTP (http://localhost:47990), or if your browser's security settings prevent self-signed certificates, the connection will drop or be refused entirely.
• Actionable Fix: Verify that the URL begins with https:// and not http://. If your web browser completely blocks access to the page with a certificate error, you can bypass this in Google Chrome or Microsoft Edge by clicking anywhere on the error page and typing thisisunsafe directly on your keyboard to force the browser to trust the local self-signed certificate.

Frequently Asked Questions About Sunshine Access Management

Where is the Sunshine password stored?

The Sunshine username and password are not stored in plain text. Instead, they are cryptographically hashed and saved in an SQLite database file named sunshine.sqlite, which is located in your system's Sunshine configuration directory. This prevents malicious local applications or users from reading your server login credentials directly from the host filesystem.

Can I recover my old Sunshine password instead of resetting it?

No. Because Sunshine uses secure cryptographic hashing, you cannot decrypt or recover your old password. If you forget your credentials, you must write a new password using the command-line override flag (--creds) or delete the sunshine.sqlite database to initiate the first-time installation setup wizard.

Why does Sunshine force a password reset on first launch?

Sunshine enforces a strict security policy that requires users to define a unique username and password immediately upon installation. Because Sunshine runs with elevated privileges on the host system to capture screen data and process inputs, leaving a default credential set active would expose your computer to severe remote code execution risks over your local network.

Does resetting my Sunshine password delete my games list?

If you use the command-line interface reset method (--creds), your games list, custom execution paths, and paired Moonlight clients will remain safe. If you use the database deletion method (removing sunshine.sqlite), all of your custom configurations, system settings, and client pairings will be deleted, requiring you to rebuild your configuration from scratch.

How do I configure Sunshine to skip the login prompt on my home network?

For safety reasons, Sunshine does not allow you to disable authentication entirely. However, you can check the "Remember Me" option during login to store a secure session cookie in your local web browser, which prevents you from having to input your username and password every time you access the dashboard.

Optimize Your Game Streaming Infrastructure

Once you have successfully restored access to your Sunshine server, ensure your local streaming parameters are tuned for maximum efficiency and security. To keep your system running at peak performance, consider setting up a static local IP address for your host machine and updating your client network profiles to prevent future disconnection issues.