Getting Started

From clean Proxmox host to first endpoint stream

This guide follows the real Beagle provisioning path: install the control plane on Proxmox, prepare Sunshine inside the target VM, create a VM-specific USB artifact, boot the endpoint, and optionally pre-register Moonlight.

Prerequisites

A Proxmox VE 7.x or 8.x host that will run the Beagle control plane
A target VM that will run Sunshine
An endpoint with at least 2 GB RAM and an 8 GB USB stick
A network with at least 100 Mbit LAN, Gigabit recommended

Step 1 - Install the host layer

Clone the repository on the Proxmox node and run the full setup. This installs the Beagle control plane, UI integration, artifact hosting, and reverse proxy configuration.

git clone https://github.com/meinzeug/beagle-os.git
cd beagle-os
./scripts/setup-proxmox-host.sh

Step 2 - Prepare the VM

Inside the target VM, prepare Sunshine. Beagle keeps the target explicit: one VM, one generated profile, one endpoint path.

./scripts/configure-sunshine-guest.sh

Step 3 - Create the USB installer or live medium

Open the VM in the Proxmox UI and download the VM-specific artifact. The script downloads the host-served payload and embeds the VM profile directly into the medium.

./pve-thin-client-live-usb-vm-100.sh
./pve-thin-client-usb-installer-vm-100.sh

Step 4 - First endpoint boot

Boot the endpoint from the generated medium. The Beagle endpoint OS comes up in runtime mode and starts Moonlight against the assigned Sunshine VM.

Step 5 - Optional pre-registration

If you want to pre-register the endpoint with Sunshine before first use, run the Moonlight registration helper.

./scripts/register-moonlight-client-on-sunshine.sh

Troubleshooting

Control plane not healthy

Run the host health check and fix host-side dependencies before creating artifacts.

./scripts/check-proxmox-host.sh

Target VM is not stream-ready

Re-run the Sunshine guest preparation script inside the VM.

Wrong endpoint targets the wrong VM

Create a fresh VM-specific USB script from the correct VM. Beagle is VM-centric by design.

USB passthrough is not available

Verify that the control plane and VM assignment are correct, then use the Proxmox UI or API attach flow.

Endpoint image boots but policy state is missing

Recreate the medium from the host so the VM profile and endpoint identity data are embedded again.