Skip to main content

QEMU

QEMU is the fastest way to try Avocado OS. No hardware required — the virtual machine runs inside Docker on your development machine.

Prerequisites​

  • macOS 10.12+ or Linux (Ubuntu 22.04+, Fedora 39+)
  • Docker Desktop installed and running
  • The latest version of the Avocado CLI
  • 8 GB available disk space

Initialize​

Create a new project targeting QEMU x86-64. The init command scaffolds an avocado.yaml with the default configuration for the target.

avocado init --target qemux86-64 qemux86-64
cd qemux86-64

Install​

Install the SDK toolchain, extension dependencies, and runtime packages defined in avocado.yaml.

avocado install -f

This pulls the SDK container image and installs all required packages into their respective sysroots. The -f flag skips confirmation prompts.

Build​

Build the system image — this compiles extensions and assembles the runtime.

avocado build

Provision​

Provision creates the bootable disk image for the dev runtime. Because QEMU is virtual, the provisioning artifacts are written to disk on your development machine rather than flashed to hardware.

avocado provision -r dev

Run​

Boot the virtual machine using the SDK container's built-in QEMU:

avocado sdk run -iE vm dev

Log in as root with an empty password.

To verify the system is running:

uname -a
systemctl status

To shut down the VM:

poweroff

SSH access​

Linux only

The --host-fwd flag is supported on Linux only.

To boot QEMU with SSH port forwarding:

avocado sdk run -iE vm dev --host-fwd "2222-:22"

Then from another terminal:

ssh -o StrictHostKeyChecking=no -p 2222 root@localhost