HydeVM - Simplified VM Tool for HyDE Contributors

HydeVM is a streamlined development tool that automatically sets up HyDE in a virtual machine for testing different branches and commits.

HydeVM - Simplified VM Tool for HyDE Contributors

Supported Host Operating Systems: Arch Linux, NixOS

Hardware Requirements

CPU: x86_64 with virtualization support (Intel VT-x or AMD-V, enabled in BIOS) Memory: 4GB+ RAM (VM uses 4GB by default) GPU Compatibility:

✅ AMD GPU - Excellent (HD 7000+ series, Mesa drivers)
✅ Intel iGPU - Excellent (HD 4000+ Ivy Bridge, Mesa drivers)
⚠️ NVIDIA GPU - May need tweaking (GTX 600+ series, proprietary drivers can cause issues)

OpenGL: 3.3+ support required for Hyprland Note: Tested on AMD GPU + Intel CPU. Hyprland VM support is experimental.

Features

Zero Configuration: Automatically downloads Arch Linux base image and sets up HyDE
Branch Testing: Easily test any HyDE branch or commit hash
Smart Caching: Creates cached snapshots for faster subsequent runs (uses XDG cache directory)
Optional Persistence: Choose whether changes should be saved or discarded
OS Detection: Automatically detects your OS and handles dependencies appropriately

Quick Start

Arch Linux

# Download and run (will auto-detect missing packages)
curl -L https://raw.githubusercontent.com/HyDE-Project/HyDE/main/Scripts/hydevm/hydevm.sh -o hydevm
chmod +x hydevm
./hydevm

NixOS

# Using flakes from HyDE repository
nix run github:HyDE-Project/HyDE

# Or if you have the repository cloned locally
nix run

First-Time Setup

When you run a new branch/commit for the first time, hydevm will:

OS Detection: Automatically detects your OS and checks dependencies
Dependency Installation: (Arch only) Prompts to install missing packages
VM Setup: Shows a VM window with setup instructions
HyDE Installation: You'll need to:
- Login as arch / arch
- Run the provided curl command to download and execute the setup script
- Wait for HyDE installation to complete
  - Hit enter for defaults
  - It will prompt for a password at the end, use arch
  - If you end up missing the password check, you can rerun the install script ./setup.sh
- Run sudo poweroff to shutdown and create the snapshot

Subsequent runs are instant - uses cached snapshot!

Usage

Basic Commands

# Run master branch
hydevm

# Run specific branch or commit
hydevm feature-branch
hydevm abc123def

# Run with persistence (changes will be saved)
hydevm --persist
hydevm --persist dev-branch

# List cached snapshots
hydevm --list

# Clean all cached data
hydevm --clean

# Check dependencies
hydevm --check-deps

# Install dependencies (Arch only)
hydevm --install-deps

Environment Variables

# Customize VM resources
VM_MEMORY=8G VM_CPUS=4 hydevm

# Set extra QEMU arguments
VM_EXTRA_ARGS="-display vnc=:1" hydevm

# Override QEMU command entirely, provided $VM_DISK will be substituted with the actual disk image
VM_QEMU_OVERRIDE="qemu-system-x86_64 -m 4G -smp 2 -enable-kvm -drive file=\$VM_DISK,format=qcow2,if=virtio -device virtio-vga -display gtk" hydevm

VM Details

Login: arch / arch
SSH Access: ssh arch@localhost -p 2222
Persistence: Optional flag determines if changes are saved
Cache Directory: Uses XDG Base Directory specification ($XDG_CACHE_HOME/hydevm/)
Snapshots: Stored in $XDG_CACHE_HOME/hydevm/snapshots/ (typically ~/.cache/hydevm/snapshots/)
Base Image: Cached in $XDG_CACHE_HOME/hydevm/archbase.qcow2 (typically ~/.cache/hydevm/archbase.qcow2)

Troubleshooting

KVM Not Available

# Arch Linux
sudo usermod -a -G kvm $USER

# NixOS - add to configuration.nix
virtualisation.libvirtd.enable = true;

Missing Dependencies

Arch: Script will prompt to install missing packages
NixOS: Nix will automatically install missing packages

Clean Start

hydevm --clean  # Remove all cached data from $XDG_CACHE_HOME/hydevm/

Killing http server

If you are running into issues with the http server, you can kill it with:

pkill -f "python3 -m http.server"

VM Host Guide

HyDE uses Hyprland, which has specific requirements for VM environments. Hyprland VM support is limited - see Hyprland - Running in a VM for official guidance.

Note

I'm trying here to make HyDE easier to work with VM's. If you have any suggestions based on your hardware and experience, or find this documentation inaccurate, please let me know.

Key Requirements:

VirtIO GPU support
OpenGL 3.3+ acceleration
VT-x/AMD-V virtualization support

Hardware Requirements (Detailed)

CPU:

Intel CPU with VT-x or AMD CPU with AMD-V
Virtualization enabled in BIOS/UEFI

GPU & OpenGL Support:

✅ AMD: HD 7000+ series (Mesa drivers recommended)
✅ Intel: HD 4000+ (Ivy Bridge) or newer
⚠️ NVIDIA: GTX 600+ series (proprietary drivers may cause issues)
OpenGL 3.3+ support required

Non-NixOS Hosts using Nix

For non-NixOS hosts, use nixGL for better graphics support:

# Install nixGL first, then run HydeVM
nixGL nix run github:HyDE-Project/HyDE

AMD GPU + Any CPU ✅

Packages (Arch): qemu-desktop mesa Packages (NixOS): qemu mesa

NixOS Configuration:

{
  hardware.graphics.enable = true;
  hardware.graphics.extraPackages = with pkgs; [ amdvlk ];
  boot.kernelModules = [ "kvm-intel" ]; # or "kvm-amd" for AMD CPUs
  virtualisation.libvirtd.enable = true;
}

# Test OpenGL
glxinfo | grep "OpenGL renderer"

# Verify VirtIO support
modprobe virtio_gpu
lsmod | grep virtio

# Default QEMU args should work perfectly
hydevm

Intel CPU with iGPU ✅

Packages (Arch): qemu-desktop mesa intel-media-driver Packages (NixOS): qemu mesa intel-media-driver

NixOS Configuration:

{
  hardware.graphics.enable = true;
  hardware.graphics.extraPackages = with pkgs; [ intel-media-driver ];
  boot.kernelModules = [ "kvm-intel" ];
  virtualisation.libvirtd.enable = true;
}

# Test OpenGL
glxinfo | grep "OpenGL renderer"

# Verify VirtIO support
modprobe virtio_gpu
lsmod | grep virtio

# Default QEMU args should work perfectly
hydevm

NVIDIA GPU + Any CPU ⚠️

Option 1: Proprietary Drivers (May have issues)

# Packages (Arch)
sudo pacman -S qemu-desktop nvidia nvidia-utils

# Packages (NixOS) - add to configuration.nix:
{
  hardware.graphics.enable = true;
  hardware.nvidia.package = config.boot.kernelPackages.nvidiaPackages.stable;
  hardware.nvidia.modesetting.enable = true;
  services.xserver.videoDrivers = [ "nvidia" ];
  boot.kernelModules = [ "kvm-intel" ]; # or "kvm-amd"
  virtualisation.libvirtd.enable = true;
}

# Test OpenGL
glxinfo | grep "OpenGL renderer"

# If graphics issues occur, disable GL acceleration
VM_EXTRA_ARGS="-device virtio-vga -display gtk,gl=off" hydevm

Option 2: Nouveau Drivers

# Packages (Arch)
sudo pacman -S qemu-desktop mesa xf86-video-nouveau

# Packages (NixOS) - add to configuration.nix:
{
  hardware.graphics.enable = true;
  services.xserver.videoDrivers = [ "nouveau" ];
  boot.kernelModules = [ "kvm-intel" ]; # or "kvm-amd"
  virtualisation.libvirtd.enable = true;
}

# Test OpenGL
glxinfo | grep "OpenGL renderer"

# Should work with default args
hydevm

Option 3: Software Rendering (Fallback)

# Force software rendering
VM_EXTRA_ARGS="-device VGA -display gtk,gl=off" hydevm

Custom QEMU Configuration

The default configuration uses these optimized arguments for Hyprland:

# Current default (automatically applied)
-device virtio-vga-gl
-display gtk,gl=on,grab-on-hover=on
-enable-kvm
-cpu host

For complete control over QEMU arguments:

# Override entire QEMU command
VM_QEMU_OVERRIDE="qemu-system-x86_64 -m 4G -smp 2 -enable-kvm -cpu host -machine q35 -device intel-iommu -drive file=\$VM_DISK,format=qcow2,if=virtio -device virtio-vga-gl -display gtk,gl=on,grab-on-hover=on -usb -device usb-tablet -device ich9-intel-hda -device hda-output -vga none" hydevm

# The script will substitute $VM_DISK with the appropriate disk image

Verification Steps

# 1. Check CPU virtualization support
egrep -c '(vmx|svm)' /proc/cpuinfo    # Should return > 0

# 2. Check KVM modules
lsmod | grep kvm                       # Should show kvm and kvm_intel/kvm_amd

# 3. Check OpenGL support
glxinfo | grep "OpenGL"               # Should show your GPU and OpenGL 3.3+

# 4. Check dependencies and system info
hydevm --check-deps

# 5. If issues occur, try software rendering
VM_EXTRA_ARGS="-device VGA -display gtk,gl=off" hydevm

Troubleshooting Hyprland in VM

If you encounter issues with Hyprland in the VM:

Graphics Issues: Try disabling GL acceleration

VM_EXTRA_ARGS="-device virtio-vga -display gtk,gl=off" hydevm

Input Issues: Ensure USB tablet is enabled (included in enhanced config)
Audio Issues: The enhanced config includes Intel HDA audio support

Performance Issues: Ensure KVM is enabled and working:

# Check KVM access
ls -la /dev/kvm
# Should show your user has access (via kvm group)

Note: Hyprland VM support is experimental. For the best experience, consider using a bare metal installation for development.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

HydeVM - Simplified VM Tool for HyDE Contributors

Hardware Requirements

Features

Quick Start

Arch Linux

NixOS

First-Time Setup

Usage

Basic Commands

Environment Variables

VM Details

Troubleshooting

KVM Not Available

Missing Dependencies

Clean Start

Killing http server

VM Host Guide

Hardware Requirements (Detailed)

Non-NixOS Hosts using Nix

AMD GPU + Any CPU ✅

Intel CPU with iGPU ✅

NVIDIA GPU + Any CPU ⚠️

Custom QEMU Configuration

Verification Steps

Troubleshooting Hyprland in VM

Uh oh!

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

HydeVM - Simplified VM Tool for HyDE Contributors

Hardware Requirements

Features

Quick Start

Arch Linux

NixOS

First-Time Setup

Usage

Basic Commands

Environment Variables

VM Details

Troubleshooting

KVM Not Available

Missing Dependencies

Clean Start

Killing http server

VM Host Guide

Hardware Requirements (Detailed)

Non-NixOS Hosts using Nix

AMD GPU + Any CPU ✅

Intel CPU with iGPU ✅

NVIDIA GPU + Any CPU ⚠️

Custom QEMU Configuration

Verification Steps

Troubleshooting Hyprland in VM