Use An Existing Image¶
Use this guide when someone already has a Den artifact and wants to boot or inspect it without rebuilding Den.
The current local artifacts are:
den-qemu-aarch64.tar.zst
den:dev
den-uefi-aarch64.raw
den-uefi-aarch64.qcow2
In this repository, locally generated file artifacts normally live under:
build/artifacts/
Choose the entry point based on what you want to test:
use the QEMU bundle to test the direct
-kernel/-initrdboot path,use
den:devto inspect the rootfs in Docker/OrbStack,use the raw/qcow2 disk to test the GRUB-backed UEFI boot path in QEMU.
The raw ext4 file, den-rootfs.ext4, may exist in build/artifacts/ and is
part of the bundle workflow. It is not the recommended standalone entry point
because it still needs the matching kernel, initramfs, QEMU command line, and
boot metadata.
If you only have den-rootfs.ext4, first recreate or obtain the matching
bundle. The bundle keeps the rootfs, Buildroot kernel, Buildroot initramfs,
QEMU launcher, manifest, and checksums together.
Use The QEMU Bundle¶
The bundle normally lives at:
build/artifacts/den-qemu-aarch64.tar.zst
Extract The Bundle¶
Choose a working directory and extract the bundle:
mkdir -p /tmp/den-image
tar -xf build/artifacts/den-qemu-aarch64.tar.zst -C /tmp/den-image
cd /tmp/den-image/den-qemu-aarch64
If your host tar cannot read .tar.zst, install zstd and select it
explicitly:
mkdir -p /tmp/den-image
tar -I zstd -xf build/artifacts/den-qemu-aarch64.tar.zst -C /tmp/den-image
cd /tmp/den-image/den-qemu-aarch64
The extracted directory contains:
Image
rootfs.cpio.gz
den-rootfs.ext4
boot-qemu.sh
manifest.toml
SHA256SUMS
Inspect The Bundle¶
Read the manifest:
sed -n '1,120p' manifest.toml
The manifest records the target, architecture, Buildroot version, source commit, active generation, package count, and artifact hashes.
Verify checksums on a Linux host:
sha256sum -c SHA256SUMS
On macOS, install GNU coreutils if sha256sum is not available:
brew install coreutils
gsha256sum -c SHA256SUMS
Boot With Host QEMU¶
If qemu-system-aarch64 is installed on the host:
./boot-qemu.sh
Run the deterministic smoke path:
./boot-qemu.sh --smoke
Enable the developer autologin console:
./boot-qemu.sh --autologin
This adds den.development=1 den.console=autologin to the kernel command line.
Use more memory:
./boot-qemu.sh --memory 4096
Use a specific QEMU binary:
./boot-qemu.sh --qemu /path/to/qemu-system-aarch64
On Apple Silicon with Homebrew QEMU:
./boot-qemu.sh --qemu /opt/homebrew/bin/qemu-system-aarch64
Append extra kernel command-line text:
./boot-qemu.sh --append "systemd.log_level=debug"
Boot With The Builder Container¶
If you do not have host QEMU installed, run the existing image through the optional builder container from inside the extracted bundle directory. 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:/bundle" \
-w /bundle \
den-buildroot-builder:2026.02 \
./boot-qemu.sh
For the smoke path:
docker run --rm \
-v "$PWD:/bundle" \
-w /bundle \
den-buildroot-builder:2026.02 \
timeout 150 ./boot-qemu.sh --smoke
The smoke boot should print:
Den systemd: smoke complete
and then power off.
Boot The Existing In-Repo Extracted Bundle¶
If the bundle has already been built in this repo, the extracted copy may already exist at:
build/artifacts/den-qemu-aarch64
Boot it without extracting again:
cd build/artifacts/den-qemu-aarch64
./boot-qemu.sh
Or through Docker with the optional builder image:
docker run --rm -it \
-v "$PWD:/bundle" \
-w /bundle \
den-buildroot-builder:2026.02 \
./boot-qemu.sh
Use The OCI Image¶
If the local image has already been built, inspect it with:
docker run --rm -it --platform linux/arm64 den:dev
Use --platform linux/amd64 instead when den:dev was built from
the linux-64 Den target.
Inside the container:
conda --version
conda config --show channels default_channels channel_priority
The image includes /etc/conda/.condarc so conda uses conda-forge with
strict channel priority and no Anaconda default channels by default.
Run the deterministic OCI smoke:
ct run oci-smoke
The smoke checks /etc/os-release, the current Den generation, and the
conda-provided bash. This image is not booted with Den’s kernel or initramfs.
Use The UEFI Disk Image¶
The UEFI disk artifacts are:
build/artifacts/den-uefi-aarch64.raw
build/artifacts/den-uefi-aarch64.qcow2
The raw disk boots in QEMU with AArch64 UEFI firmware:
QEMU_BIN="$(brew --prefix qemu)/bin/qemu-system-aarch64"
QEMU_EFI="$(brew --prefix qemu)/share/qemu/edk2-aarch64-code.fd"
"$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
To verify the UEFI path without typing the QEMU command:
ct run uefi-image-smoke
Stop The Guest¶
The --smoke path powers off automatically.
For an interactive boot, use systemd’s normal shutdown command from inside the guest when a shell is available:
systemctl poweroff
If QEMU is running in a terminal and you need to leave the QEMU monitor, use QEMU’s standard escape sequence:
Ctrl-a x
Current Limitations¶
The existing artifacts are prototype QEMU AArch64 artifacts. They are not yet:
an installer,
a systemd-boot disk image,
a provider-ready cloud image,
a signed release artifact,
a redistributable image with complete SBOM, license, and provenance reports.