Skip to main content

QEMU Quickstart (Experimental)

View source on GitHub

This guide walks you through booting Avocado OS in QEMU with Avocado Connect and Tunnels for remote device management. This is the fastest way to get a running Avocado OS instance with cloud connectivity.

Prerequisites​

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

Initialize​

Clone the reference or initialize a new project from it:

avocado init --reference qemu-quickstart qemu-quickstart
cd qemu-quickstart

Install​

Install the SDK toolchain, extension dependencies, and runtime packages:

avocado install -f

Build​

Build the runtime image:

avocado build

There are no compile steps — the build assembles the runtime from pre-built packages and extensions.

Deploy​

Provision and boot the QEMU VM:

avocado provision -r dev
avocado sdk run -iE vm dev

To SSH in from another terminal:

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

# From another terminal:
ssh -o StrictHostKeyChecking=no -p 2222 root@localhost

Verify​

Log in as root with an empty password.

Confirm the system is running:

uname -a
systemctl status

Check Avocado Connect status:

systemctl status avocado-conn

Customize​

Configure Avocado Connect​

Edit overlay/etc/avocado-conn/config.toml with your Peridio organization credentials to enable cloud device management and remote tunnels.

Add application extensions​

Edit avocado.yaml to add extensions to the runtime:

runtimes:
  dev:
    extensions:
      - avocado-ext-dev
      - avocado-ext-sshd-dev
      - avocado-bsp-{{ avocado.target }}
      - avocado-ext-connect
      - avocado-ext-tunnels
      - avocado-ext-docker        # add Docker support
      - avocado-ext-cockpit       # add web-based management UI
      - config

Rebuild after changes​

After any change, rebuild and reprovision:

avocado build
avocado provision -r dev