GPU passthrough and Windows VM with Looking Glass

[slawomir-andreasik]

GPU passthrough and Windows VM with Looking Glass

TL;DR: Run Windows 11 with dedicated GPU passthrough, Looking Glass for low-latency gaming and hardware spoofing for anti-cheat compatibility. Tested with Fortnite and Counter-Strike 2.

Demo: Omarchy: GPU passthrough + Windows 11 VM installation - Complete setup, gaming with Fortnite and Counter-Strike 2, benchmarks and switching GPU back to host for LM Studio.

See discussion thread for community testing and feedback: #3455

---

What's New

This PR adds GPU passthrough automation, Looking Glass integration and Windows VM enhancements:

GPU Passthrough Tools (omarchy-gpu-passthrough)

Automated GPU passthrough with mode switching between VM and host usage.

Commands:

omarchy-gpu-passthrough setup              # One-time setup wizard
omarchy-gpu-passthrough setup --uninstall  # Remove configuration

omarchy-gpu-passthrough mode vm            # Bind GPU for VM passthrough
omarchy-gpu-passthrough mode host          # Return GPU to host
omarchy-gpu-passthrough mode none          # Unbind GPU (power saving)

omarchy-gpu-passthrough info status        # Current system status
omarchy-gpu-passthrough info detect        # Hardware compatibility check
omarchy-gpu-passthrough info verify        # Verify configuration
omarchy-gpu-passthrough info report        # Hardware config
omarchy-gpu-passthrough info diagnose      # Full diagnostic report

What it does:

• Interactive setup wizard with GPU detection
• Automatic driver binding (vfio-pci <-> nvidia/amdgpu)
• IOMMU and kernel parameter configuration
• Hyprland iGPU setup (keeps desktop on integrated GPU)
• Diagnostics and safety checks
• Desktop icons for easy access

Files added:

• omarchy-gpu-passthrough - Main dispatcher
• omarchy-gpu-passthrough-bind - Mode control
• omarchy-gpu-passthrough-info - Diagnostics
• omarchy-gpu-passthrough-setup - Setup wizard
• omarchy-gpu-passthrough-utils - Shared library

Looking Glass Integration (omarchy-looking-glass-install, omarchy-looking-glass-launch)

Low-latency VM display using shared memory (IVSHMEM). Near-native gaming performance.

Commands:

omarchy-looking-glass-install    # Installation
omarchy-looking-glass-launch     # Launch client

What it does:

• Installation with dependency management
• IVSHMEM device setup
• Permission management (kvm group)
• Integration with Windows VM

Note: Default escape key is Scroll Lock. If your keyboard lacks this key, configure a different key in ~/.config/looking-glass/client.ini before launching (see Looking Glass documentation for key names).

Files added:

• omarchy-looking-glass-install - Installation script
• omarchy-looking-glass-launch - Client launcher

Windows VM Management (omarchy-windows-vm)

Enhanced with GPU passthrough, Looking Glass support and hardware spoofing.

New commands:

omarchy-windows-vm install          # Enhanced: GPU passthrough detection, Looking Glass integration
omarchy-windows-vm launch --lg      # New: Connect via Looking Glass

Existing commands:

omarchy-windows-vm launch           # Interactive connection menu (RDP, LG, VNC)
omarchy-windows-vm launch -k        # Keep VM running after disconnect (existing)
omarchy-windows-vm stop             # Shutdown VM
omarchy-windows-vm status           # Check VM status
omarchy-windows-vm show-compose     # Display docker-compose.yml config (testing/debugging)
omarchy-windows-vm remove           # Remove VM

What's new:

• GPU passthrough detection and automatic configuration
• Looking Glass integration with automatic installation prompt
• SMBIOS spoofing (auto-detected from host hardware)
• Hardware spoofing for anti-cheat compatibility
• Installation wizard with progress tracking
• Quick reinstall vs Fresh reinstall options
• Desktop icons: "Windows" (RDP) and "Windows [Looking Glass]" (LG)
• Interactive connection menu with multiple options
• Progress display and ETA
• show-compose command for testing docker-compose generation

Installation options:

• Fresh install: Complete Windows reinstall (removes VM disk)
• Quick reinstall: Reconfigure docker-compose and GPU settings (keeps VM disk)
• Shared folder: ~/Windows is never removed (preserved across reinstalls)

Both installation and uninstall are idempotent (safe to run multiple times).

Files modified:

• omarchy-windows-vm

---

Hardware Requirements

BIOS Settings (one-time):

• Enable CPU Virtualization (AMD-V/SVM or Intel VT-x)
• Enable IOMMU (AMD-Vi or Intel VT-d)
• Set Primary Display to IGD (integrated graphics)
• Connect monitor to motherboard ports (not GPU)

Hardware:

• 2 GPUs required: 1 dedicated + 1 integrated
• Dedicated GPU for VM passthrough
• Integrated GPU for host desktop (Hyprland)

Tested Hardware:

# omarchy-gpu-passthrough info report

=== Hardware Configuration Report ===
 
SYSTEM
  CPU: AMD Ryzen 7 8700G w/ Radeon 780M Graphics (16 cores)
  Kernel: 6.17.8-arch1-1
  OS: Arch Linux
  RAM: 58 GB
 
  Omarchy:
    Version: 3.1.7
    Branch: feat/omarchy-gpu-passthrough
    Bootloader: Limine
 
MOTHERBOARD
  Vendor: Micro-Star International Co., Ltd.
  Model: MAG B650M MORTAR WIFI (MS-7D76)
  BIOS: A.H0
 
BIOS SETTINGS
  IOMMU: Enabled ✓
  AMD-Vi: Active
  IOMMU Mode: Passthrough
 
GPUs
  [1] NVIDIA Corporation GB205 [GeForce RTX 5070] (01:00.0)
      Type: Dedicated | Driver: vfio-pci | Mode: vm ✓ | vRAM: 16 GB
 
  [2] Advanced Micro Devices, Inc. [AMD/ATI] Phoenix1 (41:00.0)
      Type: Integrated | Driver: amdgpu | vRAM: 4 GB (allocated)
 
DISPLAY CONFIGURATION
  Primary GPU: AMD Radeon 780M Graphics (radeonsi, phoenix, LLVM 21.1.5, DRM 3.64, 6.17.8-arch1-1)
  Session: Wayland
  Compositor: Hyprland
 
  Monitors per GPU:
    [1] NVIDIA Corporation GB205 [GeForce RTX 5070]: N/A (bound to vfio-pci for VM)
    [2] Advanced Micro Devices, Inc. [AMD/ATI] Phoenix1: 2 monitor(s) via DP,HDMI-A
 
DRIVER VERSIONS
  AMD/Mesa: 4.6
  VFIO: Built-in (kernel 6.17.8-arch1-1)
 
GPU PASSTHROUGH STATUS
  Configured: Yes ✓
  Dynamic Binding: Enabled
  Current Mode: vm
  Ready for VM: Yes ✓
 
Generated: 2025-11-19 00:54:00

Known working: NVIDIA RTX 5070 (dedicated), AMD Ryzen 8700G (iGPU)
Not tested: Other NVIDIA/AMD models, Intel Arc GPUs

---

Quick Start

1. Install GPU Passthrough

# Configure BIOS (see requirements above)
omarchy-gpu-passthrough info detect    # Verify hardware compatibility
omarchy-gpu-passthrough setup          # Run setup wizard
reboot                                 # Apply kernel parameters

2. Install Windows VM

omarchy-windows-vm install             # Interactive wizard (~20 min)

During installation you'll be prompted to install Looking Glass. Installation is automated if you choose yes. You can also install manually with omarchy-looking-glass-install.

3. Launch Windows VM

omarchy-windows-vm launch --lg         # Looking Glass (low-latency)
# OR
omarchy-windows-vm launch              # Interactive menu (RDP, LG, VNC)

4. Switch GPU back to host (optional)

omarchy-windows-vm stop
omarchy-gpu-passthrough mode host      # Use GPU on host (CUDA, LM Studio, etc.)

---

Known Limitations

Experimental Status

Only tested on one hardware configuration. No community testing yet. Backup your system before installation.

Black Screen Risk

Can occur after first GPU passthrough setup (first boot with blacklisted GPU). System blacklists dedicated GPU for VM passthrough. If Hyprland configuration fails, desktop won't start.

Recovery:

1. Press Ctrl+Alt+F2 to switch to TTY2
2. Login with credentials
3. Run: omarchy-gpu-passthrough setup (re-configure)
   OR: omarchy-gpu-passthrough setup --uninstall (remove)
4. Reboot

Prevention: Set "Primary Display = IGD" in BIOS before setup.

Anti-Cheat Compatibility

Hardware spoofing included (SMBIOS, CPU flags).

Tested: Fortnite/EasyAntiCheat, Counter-Strike 2
Not tested: Valorant/Vanguard, BattlEye, other anti-cheat systems

Upstream Dependency (Temporary)

Waiting for new dockurr/windows release. SPICE support fix merged to qemus/qemu (PR #978) but dockurr/windows hasn't released new version yet.

Workaround (for testing now):

git clone https://github.com/dockur/windows.git
cd windows
git fetch origin pull/1567/head:spice-support
git checkout spice-support
docker build -t dockurr/windows:latest .

This creates local dockurr/windows:latest image. Scripts will use this local image. Workaround won't be needed after new release.

Other Limitations

• GPU compatibility: Only tested with NVIDIA RTX 5070 and AMD iGPU
• Hardware variations: Different motherboards/GPUs/BIOS may behave differently
• Uninstall: omarchy-gpu-passthrough setup --uninstall

---

Related Discussion

This addresses the feature request from #3307

Community testing and feedback welcome in the discussion thread.

---

Credits

Thanks to @sspaeti for the original omarchy-windows-vm implementation and @dhh for Omarchy and inspiration.

[sspaeti]

Wow, this seems amazing! Thanks for making this! 🙌 The black-screen risk is real. I had to turn off GPU acceleration in Brave/Chromium because I got black screens during Google Meet meetings regularly. I assume this could be related (don't have to be). Do you think this is a one-off, or that could happen again? Or is that a misconfiguration or a bug in the latest packages? (I didn't have that before, so when I troubleshooted, I thought it could be because of a Mesa or similar update, but I'm not sure.

[slawomir-andreasik]

The black screen risk I mentioned is specifically about the first boot after GPU passthrough setup - it happened to me during testing when something didn't configure correctly (kernel params or Hyprland trying to start on the wrong GPU).
I've fixed those installer bugs, but since I only tested on my hardware, there's still a chance someone with different hardware might hit it. That's why I documented the recovery steps.

Your Brave/Chromium issue sounds different.

[landsman]

This is truly amazing. I would never have believed I would see GPU-heavy tasks like playing Counter-Strike 2 in a Windows VM running via Docker on Linux, in a home setting. Good job!

[Tenosiey]

This is just awesome, hope this gets implemented into the main branch!