# 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: ```text 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: ```text 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: ```bash 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: ```text Den systemd: smoke complete ``` To verify the UEFI disk path through OrbStack: ```bash 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: ```text 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: ```bash docker build -f docker/buildroot-builder.Dockerfile -t den-buildroot-builder:2026.02 . ``` ```bash 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: ```bash 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: ```bash 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: ```text build/buildroot-src build/buildroot-output build/buildroot ``` Generation-update smoke uses this Docker volume for the in-guest conda package cache: ```text 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: ```bash 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: ```bash build/artifacts/den-qemu-aarch64/boot-qemu.sh --qemu "$QEMU_BIN" ``` Boot the UEFI raw disk: ```bash "$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](https://download.oracle.com/virtualbox/UserManual.pdf) sections on guest operating systems and Arm host limitations. ## Try A VirtualBox Conversion Create the current VDI handoff artifact: ```bash ct run virtualbox-image ``` The output is: ```text build/artifacts/den-virtualbox-aarch64.vdi ``` This uses `qemu-img`. You can also convert the UEFI raw disk manually with VirtualBox tooling: ```bash 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.