vmix

Composable QEMU VM image building and orchestration for NixOS.

What it does

vmix provides:

• Image building — reproducible Linux (Debian) and Windows qcow2 images via Nix derivations
• NixOS module — declarative VM management with QEMU in network namespaces
• CLI tool — build, copy-to-disk, and run images from the command line

Usage

As a flake input

# flake.nix
inputs.vmix.url = "git+https://git.sagar.ch/dotfiles/vmix.nix.git";

# In your NixOS configuration (or globally via serverFunctions)
imports = [ inputs.vmix.nixosModules.default ];

# Use vmixLib via overlay
nixpkgs.overlays = [ inputs.vmix.overlays.default ];
# Then: pkgs.vmixLib.linux, pkgs.vmixLib.windows, pkgs.vmixLib.network

As a CLI

# Enter dev shell
nix develop

# Build an image
vmix build --image windows.images.win10.laptop \
  --generalize username=User,password=secret,hostname=PC

# Write to local disk
vmix copy --image windows.images.win10.laptop \
  --generalize username=User,password=secret \
  --to-disk /dev/sda

# Write to remote disk (streamed via SSH + LZ4)
vmix copy --image windows.images.win10.laptop \
  --generalize username=User,password=secret \
  --to-remote-disk root@10.10.10.100:/dev/nvme0n1

# Boot a built image with QEMU
vmix run ./result --mem 8192 --smp 8 --ahci

Flake outputs

Output	Description
overlays.default	Nix overlay exposing pkgs.vmixLib
nixosModules.default	NixOS module for declarative VM management
lib.x86_64-linux	Library functions (images + network utilities)
packages.x86_64-linux.default	vmix CLI tool
apps.x86_64-linux.default	Runnable vmix app

Repository structure

flake.nix          # Flake entry point
module.nix         # NixOS module export
overlay.nix        # Nix overlay (vmixLib pinned to nixpkgs 25-11)
cli.nix            # CLI tool (build, copy, run)

lib/
  default.nix      # Exports: images (linux + windows) + network
  network.nix      # IPv4/CIDR utilities
  images/
    linux/         # Debian image building + customization
    windows/       # Windows image building + customization
      helpers/     # makeImage, customizeImage, makeWinISO, etc.
      templates/   # Registry tweaks, app installers, essentials
      drivers/     # VirtIO, AMD GPU drivers
      win10/       # Windows 10 LTSC images
      win11/       # Windows 11 images

nixos/
  default.nix      # NixOS module entry point
  networks/        # Network namespace management (LAN, WAN, macvtap)
  vms/             # VM lifecycle management (QEMU, tap devices, DHCP)

Image building

Windows pipeline

1. makeImage — unattended install from upstream ISO via QEMU
2. customizeImageFold — apply modular templates (registry, apps, drivers)
3. generalize — sysprep + OOBE for deployment to real hardware

Linux pipeline

1. Fetch upstream Debian cloud image
2. customizeImageFold — apply templates via virt-customize

Key patterns

• customizeImageFold — builtins.foldl' over templates for composable layered images
• _vmixOsType — all images carry "linux" or "windows" metadata for auto-detection
• Offline registry — Windows templates use ControlSet001 for offline virt-win-reg --merge

NixOS module

Declare VMs and networks:

vmix.namespaces."lab" = {
  networks.lan1 = {
    subnet = "10.99.1.0/24";
    dhcp.enable = true;
  };
  vms.myvm = {
    image = pkgs.vmixLib.linux.images.debian.v12.upstream;
    memory = 2048;
    cores = 2;
    interfaces.lan1 = { ip = "10.99.1.10"; };
    autostart = true;
  };
};

Features:

• Network namespaces with WAN (veth), LAN (bridge + dnsmasq), macvtap
• ACPI graceful shutdown via QMP socket
• 9p shares with auto-created mount targets
• Conditional macvtap service (only created when macvtaps are configured)