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/-initrd boot path,

  • use den:dev to 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.