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 |
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 |
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 --smokeinside 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
virtvirtual 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:
aarch64for Apple Silicon hosts,x86_64for 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.