Build OCI And UEFI Images¶
Use this guide when you want image forms beyond the QEMU -kernel bundle.
Build The OCI Inspection Image¶
ct run oci-image
The local image name is:
den:dev
This target packages the staged rootfs directly. It does not require the Buildroot kernel or initramfs.
Run the smoke:
ct run oci-smoke
The smoke starts the arm64 image through Docker/OrbStack and checks:
/etc/os-release,the current Den generation,
the conda-provided bash in
/run/current-system/sw/bin/bash.
Open an interactive shell:
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 that shell, conda is on PATH:
conda --version
conda config --show channels default_channels channel_priority
The OCI image bakes in /etc/conda/.condarc with conda-forge, strict
channel priority, and an empty default_channels list. That keeps ordinary
in-container conda commands away from Anaconda’s default channels unless a user
deliberately overrides the configuration.
This image is for inspection and CI-style userland checks. It is not a VM disk and does not exercise the kernel, initramfs, GRUB, or systemd as PID 1.
Use The OCI Image As An Application Base¶
The same local image can be used as a base for application containers:
FROM den:dev
RUN conda create \
--yes \
--prefix /opt/app \
--override-channels \
--channel conda-forge \
python=3.12 \
<packages> && \
conda clean --all --force-pkgs-dirs --yes
ENV PATH=/opt/app/bin:/opt/den/bin:/run/current-system/sw/bin:/bin:/usr/bin:/sbin:/usr/sbin
See the starter examples:
This is different from running Docker inside a booted Den VM. Den does not yet package or smoke-test Docker, Podman, cgroups, or a container-host policy for a booted Den system.
Build The UEFI Disk Image¶
ct run uefi-image
The outputs are:
build/artifacts/den-uefi-aarch64.raw
build/artifacts/den-uefi-aarch64.qcow2
build/artifacts/den-uefi-aarch64.receipt.json
The task is named uefi-image because this is the disk form needed before
provider images become possible. The current artifact is still a QEMU UEFI
prototype. It includes a small Den NoCloud-compatible seed handler and
first-boot rootfs growth, but it does not query provider metadata services or
include provider-specific image metadata.
Smoke The UEFI Disk¶
ct run uefi-image-smoke
This target builds the disk, creates a smoke copy under
build/uefi-image-smoke, creates a FAT cidata seed image, boots with AArch64
UEFI firmware in QEMU, waits for den-server-smoke.service, and expects the
guest to power off.
The success marker is:
Den systemd: server smoke complete
Boot The UEFI Disk With Homebrew QEMU¶
If QEMU was installed with Homebrew on Apple Silicon, the firmware and emulator usually resolve through:
QEMU_BIN="$(brew --prefix qemu)/bin/qemu-system-aarch64"
QEMU_EFI="$(brew --prefix qemu)/share/qemu/edk2-aarch64-code.fd"
Boot the 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
For the deterministic smoke path, use ct run uefi-image-smoke; it appends
den.systemd=smoke and powers off automatically.
Boot The UEFI Disk Through The Builder Container¶
The default local smoke target runs QEMU in the optional builder container. If you want a manual container boot of the raw disk, build that image first:
docker build -f docker/buildroot-builder.Dockerfile -t den-buildroot-builder:2026.02 .
Then run:
docker run --rm -it \
-v "$PWD:/work" \
-w /work \
den-buildroot-builder:2026.02 \
bash -lc 'qemu-system-aarch64 \
-M virt \
-cpu cortex-a57 \
-m 2048 \
-nographic \
-no-reboot \
-net none \
-bios /usr/share/qemu-efi-aarch64/QEMU_EFI.fd \
-drive if=none,id=den_disk,file=/work/build/artifacts/den-uefi-aarch64.raw,format=raw \
-device virtio-blk-pci,drive=den_disk'
Convert To Another Disk Format¶
The uefi-image target already creates qcow2. To create the current VDI
handoff artifact for VirtualBox experiments, run:
ct run virtualbox-image
The output is:
build/artifacts/den-virtualbox-aarch64.vdi
This target uses qemu-img, so it does not require VirtualBox to be installed
on the host. The VDI is not boot-smoked yet.
You can also convert manually with VBoxManage:
VBoxManage convertfromraw build/artifacts/den-uefi-aarch64.raw \
build/artifacts/den-uefi-aarch64.vdi \
--format VDI
The converted VDI is not a supported Den target yet. The current boot smoke
uses QEMU virt.
Run Image Checks In GitHub Actions¶
The Images workflow consumes the hosted Den package channel, builds the
Buildroot early boot layer, rootfs image, QEMU bundle smoke, and UEFI disk smoke
directly on blacksmith-8vcpu-ubuntu-2404-arm. It does not compile Den-owned
package recipes; package builds and compiler caching live in den-forge.
The hosted-channel image path has passed end to end on GitHub Actions: Buildroot,
rootfs assembly, rootfs image verification, QEMU boot bundle smoke, and UEFI
disk smoke all consumed https://packages.den-os.org/den-forge/den-2026.6.
The workflow uses GitHub Actions caches for:
the
cxpackage cache under~/.conda/express/pkgs,Buildroot source under
build/buildroot-src,Buildroot output under
build/buildroot-output.
On Blacksmith runners, the normal actions/cache steps use Blacksmith’s
colocated cache service without changing the workflow cache actions.
The official conda-express setup-cx action tolerates a restored cx package
cache before bootstrap, so cache hits do not make cx bootstrap fail on a
non-empty runtime directory.
It uses workflow artifacts only to pass finished image outputs between jobs:
den-early-boot-aarch64,den-rootfs-aarch64.
Rootfs assembly uses the hosted Den package channel at
https://packages.den-os.org/den-forge/den-2026.6 for the conda workspace lock and
install.
Trigger it manually from GitHub Actions when you want the full image smoke path:
gh workflow run images.yml --ref main