[Tomblarom]

✍️ Description

Prepare a Debian 13 game-streaming host and client as independently usable Proxmox VE VM scripts. Users currently have to assemble the desktop, streaming application, GPU assignment and frontend integration separately.

• vm/sunshine-vm.sh: KDE Plasma Wayland, PipeWire, the upstream Sunshine Debian package, and optional Debian Steam/Dolphin packages. Optional Pegasus uses its upstream alpha build, adds a Sunshine launcher without replacing existing applications, and registers an initially empty, user-owned Dolphin collection.
• vm/moonlight-vm.sh: Xfce/LightDM, PipeWire and the upstream Moonlight AppImage, extracted without FUSE. Moonlight can start at graphical login; pairing stays in the normal application UI.
• Both use the existing Core VM lifecycle, q35/OVMF, Cloud-Init credentials and a non-root desktop user. Desktop autologin is opt-in. VM creation is reported separately from guest first-boot installation.
• Guided device selection requires an explicitly chosen, already VFIO-bound, non-boot GPU. It checks IOMMU grouping and existing local VM assignments, shows all functions in the chosen slot, confirms exclusivity, and checks again before attachment. The client optionally assigns USB devices by physical port. The picker refuses storage, hubs, network devices, conflicting assignments and configurations using unresolved resource mappings.

The initial hardware path expects a monitor or suitable dummy, AMD/Intel Mesa drivers, and prepared host passthrough. NVIDIA needs a compatible driver installed inside the guest separately. Dummy-only server operation needs the explicit desktop-autologin option. 4K60 SDR is a validation target, not a tested performance claim; display mode, encoding, decoding and game rendering must all be checked on the actual hardware.

Host boot parameters, driver blacklists, initramfs and IOMMU overrides are not modified. LXC, virtual headless displays and automatic game/emulator library provisioning are outside this draft. Custom Pegasus launch commands can be added for other emulators.

Installation sources and runtime

These are upstream-built native C++/Qt applications, with no application database. Sunshine's Debian package supplies its runtime dependencies; Moonlight's AppImage bundles its application runtime. Desktop, graphics, audio, Steam/i386 and Dolphin packages come from Debian 13 repositories. Guest setup runs after Cloud-Init on the real guest kernel, including Sunshine's udev/module setup.

Release names and digests are resolved through vm_release_asset and fetched with vm_fetch_image; the Debian image uses Core's vendor-checksum handling. Verified during development: Sunshine v2026.914.233613, Moonlight v6.2.0, and Pegasus continuous (0.16.109, explicitly opt-in). Production scripts resolve the release instead of hardcoding these versions.

🔗 Related PR / Issue

No issue closure is claimed. Existing Sunshine and Moonlight requests/contributions were checked before implementation. This draft adds Debian VM entries; it does not depend on another unpublished GPU helper.

✅ Prerequisites

• Self-review completed – Revised against the repository and current VM authoring contracts.
• Tested thoroughly – Real Proxmox guest installation and hardware tests are still required.
• No breaking changes – Existing production scripts are unchanged.
• No security risks – Device guards are covered by synthetic tests; guest permissions and device isolation still need hardware validation.

🏗️ arm64 Support

• arm64 supported
• arm64 not tested
• arm64 not supported – This implementation selects the x86_64 Moonlight AppImage and Steam's amd64/i386 packages, and explicitly requires amd64. Sunshine upstream's separate arm64 artifacts are not exposed by this VM pair.

🖥️ Tested on

• Proxmox VE – Real guest boot and streaming tests pending.
• Incus – These are Proxmox-only VM scripts.

Automated QA

Checks used Core commit af0fe772dd02bed10fd0124e3aacc86f2bc900d7. No install script was executed on the development machine and no real host, GPU binding or guest was changed.

GitHub's script-requirements check has passed. The upstream VM metadata, Bash syntax and VM wizard workflow runs currently report action_required; no successful upstream execution of those workflows is claimed. The local checks below passed against the submitted commit.

bash -n: 238 application/VM/tool scripts passed
ShellCheck 0.10.0: both new host scripts and rendered guest scripts passed
All 12 VM scripts: default, advanced, unattended and cancellation checked.
All 12 VM scripts: 72 complete mocked runs and 61 failure cases passed.
Ran 22 tests: OK
Sunshine, Moonlight and Pegasus: live Core release resolution passed; sha256 present
Both catalog entries: slug, script path, architecture/platform, resources and notes validated
git diff --check: passed

Reproduce with Core checked out locally:

CORE=/path/to/core/pve/vm-core.func bash .github/workflows/scripts/vm-wizard-test.sh
CORE=/path/to/core/pve/vm-core.func bash .github/workflows/scripts/vm-lifecycle-test.sh
python3 .github/workflows/scripts/vm-game-streaming-test.py
shellcheck --severity=warning --exclude=SC1090,SC2034 vm/sunshine-vm.sh vm/moonlight-vm.sh

The ShellCheck exclusions cover the runtime Core import and globals consumed by Core; rendered guest scripts are checked without those exclusions. The device tests use synthetic sysfs/configuration trees and mocked qm, never the host's devices. They cover conflicting and changing ownership, boot GPUs, missing IOMMU, unrelated group members, cancellation, unattended confirmation and USB exclusions. Guest tests render a non-default username, check shell syntax, preserve Sunshine app entries across repeated Pegasus merges, and verify Debian repository-component edits remain idempotent.

The existing lifecycle fixtures were extended for the new assets and first-boot checks. One pre-existing HAOS channel fixture lacked the hassos.generic-aarch64 field already used by its script; the failure was reproduced against the unchanged base, then the fixture alone was corrected so the full suite runs.

Hardware QA still needed: Debian guest bootstrap, graphical login/autologin, firmware after guest reboot, AMD/Intel/NVIDIA-specific behavior, physical display/USB/audio, PIN pairing, gamepad mapping, Steam and Dolphin launch/return, guest restart, and 4K60 encode/decode/frame pacing. No UI screenshots or successful hardware-test claims are supplied in place of those checks.

🛠️ Type of Change

• 🐞 Bug fix
• ✨ New feature
• 💥 Breaking change
• 🆕 New script – Debian Sunshine/Moonlight VM draft; hardware validation pending.
• 🌍 Website update – Matching VM catalog entries.
• 🔧 Refactoring / Code Cleanup
• 📝 Documentation update

🔍 Code & Security Review

• Follows CODE-AUDIT.md & CONTRIBUTING.md guidelines, with the current VM-specific Core contract.
• Uses correct script structure – vm/*.sh and matching catalog entries.
• No hardcoded credentials
• No Docker / Docker Compose
• No git pull – Release assets use the VM Core release/download helpers. Automated application updates are not advertised.

🤖 AI Assistance

• No AI used
• AI was used – AGENTS.md and .github/agents/pve-script-creator.agent.md were read, with VM-specific guidance applied where CT-only rules do not apply. Output was reviewed and corrected against the project contracts.

GPT-6.1-Sol (high reasoning) coordinated research, integration, review and validation. Muse 1.3 Contributor (max reasoning) researched public upstreams and drafted the two VM scripts. The automated checks above do not substitute for the pending real-platform tests.

📋 Additional Information

Optional settings: VM_INSTALL_STEAM=yes|no, VM_INSTALL_DOLPHIN=yes|no, VM_INSTALL_PEGASUS=yes|no, VM_CLIENT_AUTOSTART=yes|no and VM_DESKTOP_AUTOLOGIN=yes|no. The interactive wizard offers these choices. Pegasus and desktop autologin default to no.

For unattended device selection, use an explicit VM_GPU_PCI=0000:01:00.0 and/or client VM_USB_PORTS=1-2,1-3.4, together with VM_PASSTHROUGH_CONFIRM=yes. These are examples, not automatically selected devices. Core's normal VM and Cloud-Init environment overrides remain available.

📦 Application Requirements (for new scripts)

• The application is at least 6 months old
• The application is actively maintained
• The application has 600+ GitHub stars
• Official release tarballs are published
• I understand that not all scripts will be accepted due to various reasons and criteria by the community-scripts ORG

🌐 Source

• Sunshine installation and user service, upstream Debian build, package post-install
• Moonlight Qt upstream and releases, Linux setup
• Pegasus releases, Linux build workflow, metadata format
• Debian Steam setup, Dolphin package, Dolphin launch arguments
• Proxmox PCI passthrough, Community Scripts VM authoring, Core VM helper contract

[github-actions]

Try these scripts

vm/moonlight-vm.sh, run in the Proxmox VE shell:

bash -c "$(curl -fsSL https://raw.githubusercontent.com/Tomblarom/DevScripts/feat/debian-game-streaming/vm/moonlight-vm.sh)"

vm/sunshine-vm.sh, run in the Proxmox VE shell:

bash -c "$(curl -fsSL https://raw.githubusercontent.com/Tomblarom/DevScripts/feat/debian-game-streaming/vm/sunshine-vm.sh)"

Against a core branch as well

Add COMMUNITY_SCRIPTS_CORE_URL=https://raw.githubusercontent.com/OWNER/core/BRANCH
to test an engine change at the same time. The two resolve independently.