Skip to content

Unraid VM & VirtFS Integration Guide

All imago flavors are engineered for seamless operation in Unraid's KVM environment.

1. Importing the Image to Unraid

An image of 2 GiB or more is too large for one release asset, so the release carries it as <asset>.part00, <asset>.part01, and so on, and the curl below fails for that flavor. Download the parts with SHA256SUMS, check and join them as Supply Chain Security shows, and decompress the joined file with zstdcat.

  1. Download and decompress the release image into your Unraid domains share:
cd /mnt/user/domains/my-appliance/
curl -fsSL https://github.com/cordanaLLM/imago/releases/latest/download/imago-cloud-docker-generic.qcow2.zst | zstdcat > vdisk1.qcow2
  1. In the Unraid Web GUI:
  2. Navigate to VMs -> Add VM -> Linux.
  3. Primary vDisk Location: Select Manual and browse to /mnt/user/domains/my-appliance/vdisk1.qcow2.
  4. Primary vDisk Bus: VirtIO (or SATA).
  5. Network Bridge: br0 (VirtIO).
  6. Graphics / Sound: VNC or GPU Passthrough.

2. Guest Agent & ACPI Clean Shutdown

  • qemu-guest-agent is pre-installed and enabled. Once the VM boots, its IP address appears directly in the Unraid VM management table.
  • acpid is installed, ensuring that clicking Stop in the Unraid GUI triggers a clean, graceful ACPI shutdown.

3. Host Share Passthrough (VirtFS & virtiofs)

All imago kernels load 9p, 9pnet, and virtiofs modules at boot.

Using virtiofs

  1. In Unraid VM settings, add a virtiofs share tag:
  2. Share Name: media
  3. Source Path: /mnt/user/data
  4. Inside the guest VM:
sudo mkdir -p /mnt/unraid
sudo mount -t virtiofs media /mnt/unraid
  1. To mount automatically on boot, add to /etc/fstab:
media  /mnt/unraid  virtiofs  defaults,_netdev  0  0