feat(install): auto-detect VirtualBox and apply guest fixes

Adds lib/vbox.sh that runs systemd-detect-virt and, on VirtualBox guests:
  - installs virtualbox-guest-utils + enables vboxservice
  - links files/hypr/vbox.conf into ~/.config/hypr/ which sets
    WLR_NO_HARDWARE_CURSORS=1, WLR_RENDERER_ALLOW_SOFTWARE=1,
    LIBGL_ALWAYS_SOFTWARE=1 and overrides the monitor rule to
    preferred mode (3440x1440@120 doesn't exist in VBox)

On bare metal an empty stub is linked instead, so the source= line in
hyprland.conf always resolves.

README adds a 'Testing in VirtualBox first' section listing the host-side
VBox settings (3D Acceleration on, 128MB video mem, VMSVGA, 8GB RAM, 40GB
disk) and the known-broken pieces (bluetooth, gpu-screen-recorder).

install/README.md

@@ -26,6 +26,44 @@ Omarchy-based approach.
 | Additional packages | `git sudo curl` |
 | User account | regular user with sudo |
 
+## Testing in VirtualBox first (recommended before bare metal)
+
+The installer auto-detects VirtualBox via `systemd-detect-virt` and applies
+the changes Hyprland needs to start in a VM:
+
+- Installs `virtualbox-guest-utils` and enables `vboxservice`.
+- Links `files/hypr/vbox.conf` into `~/.config/hypr/` to set
+  `WLR_NO_HARDWARE_CURSORS`, `WLR_RENDERER_ALLOW_SOFTWARE`,
+  `LIBGL_ALWAYS_SOFTWARE`, and override the monitor rule to `preferred`
+  mode (the 3440x1440@120 default doesn't exist in VBox).
+
+On bare metal, an empty stub is linked instead so the `source =` line in
+`hyprland.conf` always resolves.
+
+### VBox host-side settings (do these before booting the VM)
+
+| Setting | Value |
+|---------|-------|
+| System → Processor | 4+ CPUs |
+| System → Memory | 8 GB+ |
+| Display → Video Memory | **128 MB** (max) |
+| Display → Graphics Controller | **VMSVGA** |
+| Display → Enable 3D Acceleration | **on** |
+| Storage | 40 GB+ (Hyprland + tools + AUR builds) |
+| Network | NAT or Bridged (needs internet) |
+
+Without 3D Acceleration on and 128 MB video memory, Hyprland will not start.
+
+### Things that won't work in VBox (and that's fine)
+
+- Bluetooth (no virtual adapter)
+- GPU screen recording (`gpu-screen-recorder` has no VAAPI in VBox)
+- Real performance — software rendering is slow but functional
+- 3440x1440@120 — you'll get the VM's preferred mode instead
+
+If Hyprland is unusable even with the overrides, increase video memory or
+re-run `install/install.sh --dotfiles-only` after toggling 3D acceleration.
+
 ## Install
 
 ```bash

install/files/hypr/hyprland.conf

@@ -53,3 +53,7 @@ misc {
 
 source = ~/.config/hypr/keybinds.conf
 source = ~/.config/hypr/autostart.conf
+
+# VBox-only overrides (only linked into ~/.config/hypr/ when running on
+# VirtualBox; absent on bare metal). Hyprland silently skips missing sources.
+source = ~/.config/hypr/vbox.conf

install/files/hypr/vbox-stub.conf

@@ -0,0 +1,3 @@
+# Placeholder linked into ~/.config/hypr/vbox.conf on bare-metal installs so
+# the `source = ~/.config/hypr/vbox.conf` line in hyprland.conf doesn't error.
+# Replaced with vbox.conf when running on VirtualBox.

install/files/hypr/vbox.conf

@@ -0,0 +1,12 @@
+# VirtualBox-only Hyprland overrides. Sourced from hyprland.conf if present.
+# Conditionally linked by lib/vbox.sh when systemd-detect-virt reports VBox.
+
+# Software rendering + cursor fixes — VBox vmsvga has no working HW cursor and
+# Hyprland often needs the SW renderer fallback to start at all.
+env = WLR_NO_HARDWARE_CURSORS,1
+env = WLR_RENDERER_ALLOW_SOFTWARE,1
+env = LIBGL_ALWAYS_SOFTWARE,1
+
+# Use the monitor's preferred mode (VBox doesn't expose 3440x1440@120).
+# Comes after monitors.conf so it overrides the wildcard rule.
+monitor=,preferred,auto,1

install/install.sh

@@ -20,6 +20,7 @@ source "$SCRIPT_DIR/lib/common.sh"
 source "$SCRIPT_DIR/lib/packages.sh"
 source "$SCRIPT_DIR/lib/dotfiles.sh"
 source "$SCRIPT_DIR/lib/hyprland.sh"
+source "$SCRIPT_DIR/lib/vbox.sh"
 source "$SCRIPT_DIR/lib/services.sh"
 
 usage() {
@@ -55,6 +56,7 @@ do_packages() {
 do_dotfiles_and_config() {
   link_dotfiles
   link_hyprland_config
+  setup_vbox
   apply_desktop_settings
   install_tpm
   install_nvm

install/lib/vbox.sh

@@ -0,0 +1,34 @@
+#!/bin/bash
+# VirtualBox detection + guest setup. Runs after packages + dotfiles so the
+# Hyprland config swap happens before the user logs into the session.
+
+is_virtualbox() {
+  command -v systemd-detect-virt >/dev/null 2>&1 || return 1
+  [[ "$(systemd-detect-virt 2>/dev/null)" == "oracle" ]]
+}
+
+install_vbox_guest_additions() {
+  info "VirtualBox detected — installing virtualbox-guest-utils..."
+  pac_install virtualbox-guest-utils virtualbox-guest-utils-nox 2>/dev/null \
+    || pac_install virtualbox-guest-utils
+  sudo systemctl enable --now vboxservice.service \
+    || warn "vboxservice not enabled (guest additions may need manual install)"
+}
+
+link_vbox_overrides() {
+  local target="$HOME/.config/hypr/vbox.conf"
+  if is_virtualbox; then
+    info "Linking VBox Hyprland overrides (SW renderer, preferred monitor mode)"
+    backup_and_link "$INSTALL_FILES/hypr/vbox.conf" "$target"
+  else
+    info "Bare metal — linking vbox.conf stub"
+    backup_and_link "$INSTALL_FILES/hypr/vbox-stub.conf" "$target"
+  fi
+}
+
+setup_vbox() {
+  if is_virtualbox; then
+    install_vbox_guest_additions
+  fi
+  link_vbox_overrides
+}