Run With OrbStack And VirtualBox

Use this guide to run the current Den artifacts through OrbStack and to understand the current VirtualBox boundary.

Current Runtime Matrix

Runtime

Current status

Notes

OrbStack with Docker

Current repo path

Used by OCI image checks and Docker-backed smoke runners.

Host QEMU

Current bundle path

Requires qemu-system-aarch64 on the host.

Host QEMU with UEFI

Current disk-image path

Requires AArch64 QEMU and EDK2 firmware.

VirtualBox

Experimental only

A raw UEFI disk exists, but the tested virtual hardware target is QEMU virt.

The direct QEMU bundle artifact is:

build/artifacts/den-qemu-aarch64.tar.zst

It contains a QEMU launcher, a Buildroot kernel, a Buildroot initramfs, and a Den ext4 rootfs. That is the input set used by the current QEMU launcher. It is not enough for VirtualBox because VirtualBox expects a VM disk and firmware/bootloader path rather than a QEMU -kernel and -initrd command line.

The UEFI disk artifacts are:

build/artifacts/den-uefi-aarch64.raw
build/artifacts/den-uefi-aarch64.qcow2

These contain a GPT, a FAT EFI system partition, a GRUB standalone BOOTAA64.EFI, the Buildroot kernel/initramfs, and the Den rootfs partition. They are smoke-tested with QEMU AArch64 UEFI firmware.

Run With OrbStack

Start OrbStack, then run the normal smoke from the repository root:

ct run image-bundle-smoke

This target:

  • builds or refreshes the QEMU bundle,

  • extracts it into build/image-bundle-smoke,

  • verifies SHA256SUMS,

  • runs ./boot-qemu.sh --smoke inside the optional builder container,

  • waits for the guest to power off.

The expected success marker is:

Den systemd: smoke complete

To verify the UEFI disk path through OrbStack:

ct run uefi-image-smoke

This boots a smoke copy of the raw disk with QEMU and AArch64 UEFI firmware in the optional builder container. It also attaches a cidata seed disk, checks seeded hostname and root SSH keys, checks first-boot rootfs growth, and verifies the server service set.

Run An Existing Bundle With OrbStack

If the bundle is already extracted at:

build/artifacts/den-qemu-aarch64

boot it through the optional builder container without rebuilding. Build the image from the repository root first if it is not already present:

docker build -f docker/buildroot-builder.Dockerfile -t den-buildroot-builder:2026.02 .
docker run --rm -it \
  -v "$PWD/build/artifacts/den-qemu-aarch64:/bundle" \
  -w /bundle \
  den-buildroot-builder:2026.02 \
  ./boot-qemu.sh

Run the deterministic smoke path:

docker run --rm \
  -v "$PWD/build/artifacts/den-qemu-aarch64:/bundle" \
  -w /bundle \
  den-buildroot-builder:2026.02 \
  timeout 150 ./boot-qemu.sh --smoke

Use OrbStack For Build Work

The OCI and Docker-backed smoke paths can use OrbStack:

ct run smoke
ct run generation-smoke
ct run image-bundle-smoke
ct run oci-smoke
ct run uefi-image-smoke

Generated Buildroot state stays under this checkout:

build/buildroot-src
build/buildroot-output
build/buildroot

Generation-update smoke uses this Docker volume for the in-guest conda package cache:

den-update-pkgs

Do not delete these directories or the volume unless you intentionally want to rebuild cached state.

Host QEMU With Homebrew

If QEMU was installed with Homebrew on Apple Silicon:

QEMU_BIN="$(brew --prefix qemu)/bin/qemu-system-aarch64"
QEMU_EFI="$(brew --prefix qemu)/share/qemu/edk2-aarch64-code.fd"

Boot the direct QEMU bundle:

build/artifacts/den-qemu-aarch64/boot-qemu.sh --qemu "$QEMU_BIN"

Boot the UEFI raw disk:

"$QEMU_BIN" \
  -M virt \
  -cpu cortex-a57 \
  -m 2048 \
  -nographic \
  -no-reboot \
  -net none \
  -bios "$QEMU_EFI" \
  -drive if=none,id=den_disk,file=build/artifacts/den-uefi-aarch64.raw,format=raw \
  -device virtio-blk-pci,drive=den_disk

VirtualBox Status

The current Den image is not validated as a VirtualBox target.

Reasons:

  • the supported smoke path uses QEMU virt virtual hardware,

  • the Buildroot kernel config has not been tuned or tested for VirtualBox,

  • the current disk image is not a VirtualBox VM export,

  • the current target is AArch64 and VirtualBox guests must match the host architecture family.

Oracle’s VirtualBox manual says VirtualBox can run x86 operating systems on x86_64 hosts and a selection of Arm guests on Arm hosts. It also says x86 guest operating systems are not supported on Arm hosts. See the Oracle VirtualBox User Guide sections on guest operating systems and Arm host limitations.

Try A VirtualBox Conversion

Create the current VDI handoff artifact:

ct run virtualbox-image

The output is:

build/artifacts/den-virtualbox-aarch64.vdi

This uses qemu-img. You can also convert the UEFI raw disk manually with VirtualBox tooling:

VBoxManage convertfromraw build/artifacts/den-uefi-aarch64.raw \
  build/artifacts/den-uefi-aarch64.vdi \
  --format VDI

Do not treat a VirtualBox boot failure as a Den regression yet. The converted VDI is not part of the verified target matrix.

What VirtualBox Needs Later

A VirtualBox target exists only as a VDI image conversion today.

Minimum work:

  • choose target architecture: aarch64 for Apple Silicon hosts, x86_64 for Intel/AMD hosts,

  • add a matching conda lock platform and Den package artifacts,

  • add a Buildroot or kernel config for the VirtualBox virtual hardware,

  • add a VirtualBox-specific smoke target,

  • add a smoke test that boots the VM target and reaches the systemd smoke unit.

Practical Recommendation

Use OrbStack and QEMU for Den today. Treat VirtualBox as a future Milestone 7 runtime target after the project has a VirtualBox-specific kernel and smoke path.