nixos/docs/proxmox-images.md

Proxmox VM disk images

proxmox-* hosts (VM platform, not lxc-*) can be built as standalone, ready-to-attach .raw disk images via disko's own image-builder — no nixos-install, no live installer boot. This uses the same disko.devices config (modules/disko/proxmox.nix) already used to format a real disk on install, so there's nothing host-specific to write; it's available for every proxmox-* target automatically.

Building

nix build .#nixosConfigurations.proxmox-server.config.system.build.diskoImagesScript
sudo ./result --build-memory 2048

This produces <hostname>.raw in the current directory (e.g. server.raw for proxmox-server, matching networking.hostName, not the flake attribute name — every proxmox-* host gets a distinctly named image instead of all of them producing an identical main.raw). The script builds inside a temporary QEMU VM and moves the finished image out to the working directory when done; --build-memory controls how much RAM that build VM gets.

disko.devices.disk.main.imageSize (currently 20G, in modules/disko/proxmox.nix) sets the image's total size — disko doesn't support auto-resizing, so this needs to comfortably fit ESP + swap + root at build time. Grow the virtual disk (and resize the filesystem) in Proxmox after attaching if a host needs more than that; this is the normal way to size these images, not a one-time decision to get exactly right up front.

Host keys

The disko image script runs a real activation pass inside its temporary build VM while constructing the image — the same sops-nix activation-before-first-boot problem the installer and LXC tarball workflows have (see docs/auto-installer.md) applies here too, unmodified. Disko has a native mechanism for it:

sudo ./result \
  --pre-format-files host-keys/server_ssh_host_ed25519_key /etc/ssh/ssh_host_ed25519_key \
  --pre-format-files host-keys/server_ssh_host_ed25519_key.pub /etc/ssh/ssh_host_ed25519_key.pub \
  --build-memory 2048

Generate the key first with scripts/prepare-host-key.sh <hostname>, same as any other host — see docs/auto-installer.md for the full sops.yaml registration walkthrough.

Deploying to Proxmox

The image needs UEFI (OVMF), not Proxmox's default SeaBIOS — modules/boot/efi.nix uses systemd-boot, which only works with UEFI firmware. virtio-scsi is safe to use as the disk bus: hardware-configuration/vm/proxmox.nix already includes virtio_scsi in its initrd kernel modules.

1. Copy the image to the Proxmox host:

   scp server.raw root@<proxmox-host>:/var/lib/vz/import/
   

2. Create an empty VM shell (no disk yet) — replace <vmid> with a free ID and <storage> with your storage pool's name (pvesm status or Datacenter → Storage in the web UI):

   qm create <vmid> --name proxmox-server --memory 2048 --cores 2 \
     --net0 virtio,bridge=vmbr0 \
     --bios ovmf --machine q35 \
     --scsihw virtio-scsi-pci \
     --efidisk0 <storage>:1,efitype=4m,pre-enrolled-keys=0
   

   (--efidisk0 is required for UEFI — it's where OVMF persists boot-entry NVRAM; without it, systemd-boot's boot entry may not survive a reboot.)

3. Import the raw disk into storage:

   qm importdisk <vmid> /var/lib/vz/import/server.raw <storage>
   

   This prints the resulting disk identifier (e.g. vm-<vmid>-disk-1).

4. Attach it and set it as the boot disk:

   qm set <vmid> --scsi0 <storage>:vm-<vmid>-disk-1
   qm set <vmid> --boot order=scsi0
   

5. Boot it:

   qm start <vmid>
   

No install step — it boots straight into the already-activated system.

Why not nix build .#nixosConfigurations.<host>.config.system.build.vm?

That's a different, unrelated feature — system.build.vm (nixos-rebuild build-vm) produces an ephemeral QEMU script for locally testing a configuration, not a distributable disk image. It's not part of this workflow.