feat(linux): add portal token setup script for headless systems

[neatnoise]

Description

On headless Linux systems using Wayland, the XDG portal Start call requires user confirmation via a monitor selection dialog. When Sunshine runs as a systemd service, there is no way to approve this popup without a physical display.

This script automates the portal token setup:

1. Starts the Sunshine systemd service with portal capture (hangs waiting for approval)
2. Launches a temporary KMS instance on a different port so the user can connect via Moonlight
3. User approves the portal popup from the KMS session
4. Cleans up the temporary KMS instance
5. The systemd service continues with a saved portal token that persists across restarts

Screenshot

Issues Fixed or Closed

Roadmap Issues

Type of Change

• feat: New feature (non-breaking change which adds functionality)
• fix: Bug fix (non-breaking change which fixes an issue)
• docs: Documentation only changes
• style: Changes that do not affect the meaning of the code (white-space, formatting, missing semicolons, etc.)
• refactor: Code change that neither fixes a bug nor adds a feature
• perf: Code change that improves performance
• test: Adding missing tests or correcting existing tests
• build: Changes that affect the build system or external dependencies
• ci: Changes to CI configuration files and scripts
• chore: Other changes that don't modify src or test files
• revert: Reverts a previous commit
• BREAKING CHANGE: Introduces a breaking change (can be combined with any type above)

Checklist

• Code follows the style guidelines of this project
• Code has been self-reviewed
• Code has been commented, particularly in hard-to-understand areas
• Code docstring/documentation-blocks for new or existing methods/components have been added or updated
• Unit tests have been added or updated for any new or modified functionality

AI Usage

• None: No AI tools were used in creating this PR
• Light: AI provided minor assistance (formatting, simple suggestions)
• Moderate: AI helped with code generation or debugging specific parts
• Heavy: AI generated most or all of the code changes

[ReenigneArcher]

As this PR stands right now, this script will not be included in any Sunshine packages. Is that the intent?

[neatnoise]

As this PR stands right now, this script will not be included in any Sunshine packages. Is that the intent?

Hhm, maybe would be better to just have it in the docs for copy paste and use? It's to automate portal token generation for systems without physical monitor. I had the issues to generate it in this case and it will help to automate.

[ReenigneArcher]

Could we achieve the same from within Sunshine's src code and have a button in the UI or CLI arg to handle this instead of an external script?

[sonarqubecloud]

Quality Gate failed

Failed conditions
7 New issues
7 New Code Smells (required ≤ 0)

See analysis details on SonarQube Cloud

Catch issues before they fail your Quality Gate with our IDE extension SonarQube for IDE

[neatnoise]

What do you think about installing it to like /usr/bin/sunshine-portal-setup and documenting in the docs? It requires the user's interaction unfortunately to connect using Moonlight to Sunshine instance on custom port (KMS), access for setcap etc

[ReenigneArcher]

@psyke83 tagging you in case you have some thoughts on how to handle this

[psyke83]

Having it as an optional script may be OK, I suppose? I also run a headless host, so I do need to run a similar script that I wrote for GNOME sessions. On KDE, it probably makes better sense to use the secondary permission system:

flatpak permission-set kde-authorized remote-desktop dev.lizardbyte.app.Sunshine yes

If this script is added, the above should probably be documented for KDE users as an easier alternative.