Documentation · Virtualization

air/OS in a virtual machine.

Try air/OS without a spare computer. The x86-64 and ARM64 ISOs start in QEMU on Linux and in UTM on a Mac, and install onto a virtual disk.

Pick the image

Your computerImageRuns as
Linux PC with an Intel or AMD processor; Intel Macx86-64 ISOVirtualized: close to native speed
Mac with Apple silicon (M1 and later); ARM64 Linux machineARM64 ISOVirtualized: close to native speed
Any other combinationEitherEmulated: works, but several times slower

Download the image and its SHA-256 file from the downloads page, check it, and unpack it. The Raspberry Pi and Cubie images are for those boards and don’t start in a virtual machine.

# Linux
sha256sum -c airos-x86_64.iso.xz.sha256
xz -dk airos-x86_64.iso.xz

# macOS (brew install xz first)
shasum -a 256 -c airos-arm64.iso.xz.sha256
xz -dk airos-arm64.iso.xz

On a Mac without Homebrew, unpack the .xz file with Keka or The Unarchiver instead. Give the virtual machine at least 4 GB of memory, 2 to 4 processor cores and a 32 GB disk.

QEMU on Linux

Install QEMU and its UEFI firmware. On Debian and Ubuntu:

sudo apt install qemu-system-x86 qemu-system-arm qemu-utils ovmf qemu-efi-aarch64

Fedora calls the firmware packages edk2-ovmf and edk2-aarch64; Arch Linux calls them edk2-ovmf and edk2-aarch64 as well, with QEMU in qemu-full. The firmware file paths below are Debian’s and Ubuntu’s; elsewhere, look under /usr/share/edk2/. To use KVM, add yourself to the kvm group, then log out and in again.

x86-64

Make a disk and a copy of the firmware’s settings, then start the installer:

qemu-img create -f qcow2 airos.qcow2 32G
cp /usr/share/OVMF/OVMF_VARS_4M.fd airos-vars.fd

qemu-system-x86_64 -machine q35 -accel kvm -cpu host -m 4G -smp 4 \
  -drive if=pflash,format=raw,readonly=on,file=/usr/share/OVMF/OVMF_CODE_4M.fd \
  -drive if=pflash,format=raw,file=airos-vars.fd \
  -drive if=none,id=disk,file=airos.qcow2 -device nvme,drive=disk,serial=airos,bootindex=1 \
  -cdrom airos-x86_64.iso \
  -device qemu-xhci -device usb-tablet \
  -nic user,model=virtio-net-pci \
  -audio pa,model=hda \
  -vga std

ARM64

The ARM64 machine has no CD drive, so the ISO goes on a virtual USB stick. The firmware files must be 64 MB, which Debian’s are:

qemu-img create -f qcow2 airos.qcow2 32G
cp /usr/share/AAVMF/AAVMF_VARS.fd airos-vars.fd

qemu-system-aarch64 -machine virt -accel kvm -cpu host -m 4G -smp 4 \
  -drive if=pflash,format=raw,readonly=on,file=/usr/share/AAVMF/AAVMF_CODE.fd \
  -drive if=pflash,format=raw,file=airos-vars.fd \
  -drive if=none,id=disk,file=airos.qcow2 -device nvme,drive=disk,serial=airos,bootindex=1 \
  -device qemu-xhci -device usb-kbd -device usb-tablet \
  -drive if=none,id=iso,format=raw,readonly=on,file=airos-arm64.iso \
  -device usb-storage,drive=iso \
  -nic user,model=virtio-net-pci \
  -device ramfb

To run the ARM64 image on an Intel or AMD PC, replace -accel kvm -cpu host with -cpu cortex-a72. QEMU then emulates the processor: it works, but starting takes a few minutes.

Install and start from the disk

  1. air/OS starts from the ISO and asks for your language and keymap. Choose Install air/OS (or Try air/OS to look around first).
  2. In the Installer, choose the 32 GB QEMU NVMe Ctrl disk under Erase a whole disk and set it up for UEFI in the Onto menu, click Begin, then Erase disk and install. The Installer partitions the disk, sets it up for UEFI and copies the system.
  3. When it finishes, click Restart. bootindex=1 makes the firmware try the NVMe disk first, so air/OS now starts from it even with the ISO still attached. (While the disk is empty, the firmware skips it and starts the ISO.) Drop the ISO from the command whenever you like: -cdrom airos-x86_64.iso, or the two lines naming airos-arm64.iso.

Click inside the window to use the mouse; Ctrl+Alt+G releases it. Ctrl+Alt+F toggles full screen. The network uses QEMU’s built-in address translation: air/OS reaches the internet, but other computers can’t reach it.

UTM on a Mac

UTM ↗ is a free virtual machine app for macOS built on QEMU. Use the ARM64 ISO on a Mac with Apple silicon and the x86-64 ISO on an Intel Mac.

Create the virtual machine

  1. Open UTM, click + (Create a New Virtual Machine) and choose Virtualize, then Other.
  2. Under Boot ISO Image, click Browse and choose the unpacked airos-arm64.iso (or airos-x86_64.iso on an Intel Mac). Continue.
  3. Set Memory to 4096 MB and CPU Cores to 4. Leave hardware OpenGL acceleration off. Continue.
  4. Set the disk to 32 GB. Continue, and skip Shared Directory.
  5. On the summary, name the machine “air/OS”, tick Open VM Settings and click Save.

Check the settings

On a Mac with Apple silicon, UTM’s defaults for Other need two changes before the first start; on an Intel Mac, the defaults work as they are.

SettingApple silicon (ARM64)Intel Mac (x86-64)
Display → Emulated Display CardChange to ram framebuffer standalone device (ramfb)virtio-vga (the default)
The 32 GB drive (under Drives) → InterfaceChange from VirtIO to NVMeIDE (the default; air/OS sees it as a SATA disk)
Network → Emulated Network Cardvirtio-net-pci (the default)Intel Gigabit Ethernet (e1000) (the default)
QEMU → UEFI BootOn (the default)On (the default)

Click Save, then start the machine with ▶︎. It starts from the ISO: install as in Install and start from the disk, choosing the 32 GB disk (QEMU NVMe Ctrl on Apple silicon, QEMU HARDDISK on an Intel Mac). When the Installer has finished, don’t click Restart: shut air/OS down from the Deskbar menu (Shutdown… → Power off), then in UTM’s window select the CD/DVD drive and choose Clear: UTM starts the drives in the order they are listed, so with the ISO still attached it would start the installer again.

UTM captures the mouse when you click in the window; press Control+Option to release it.

If something goes wrong

  • The Installer doesn’t list the disk. The virtual disk probably uses the VirtIO interface: air/OS, like Haiku, has no VirtIO disk driver on x86-64. Use NVMe as above (SATA works too).
  • A black screen on a Mac with Apple silicon. Check that the display card is ramfb, the display these instructions were checked with. Display cards with their own video memory, such as VGA, generally don’t work in ARM64 virtual machines on Apple silicon.
  • The firmware tries the network (“Start PXE over IPv4”) or opens a UEFI shell. It didn’t find a disk to start. Before installing, check that the ISO is attached. After installing in QEMU, check that the disk has bootindex=1: without it, the firmware can keep the boot order it saved while starting the ISO and never reach the disk.
  • It started, then stopped in the kernel debugger. Report an issue with the virtual machine’s settings and, if you can, the serial output (QEMU: add -serial file:serial.log).