Custom images

Kiki OS images are built with Podman from a Fedora bootc base and turned into installable artifacts with image-builder. Build your own when you want a different default model, extra packages, or a tailored profile.

The profiles

Profile	Architecture	Display	For
Desktop	amd64	Yes	PCs and devices with a screen
Server	amd64	No	VPS, home servers, headless
Edge (lite)	arm64	No	ARM embedded devices

Desktop and Server build on a shared base; Edge is a standalone minimal image.

Build

make all            # desktop + server + lite
make build-desktop  # a single profile
make build-server
make build-lite

Each image is tagged with the resolved version and :latest, pushed to ghcr.io/kiki-os.

Choose the default model

The base image bakes in a default model name. Override it at build:

podman build --build-arg DEFAULT_MODEL=llama3.2:3b -f Containerfile.base .

The value lands in agentd.toml as default_model. Pick a model your target hardware can run on-device — see Models.

Produce artifacts

make iso      # dist/*.iso   — from desktop (USB / bare metal)
make qcow2    # dist/*.qcow2 — from server (QEMU/KVM, libvirt)
make ami      # an AWS AMI   — from server
make dev-vm   # boot the desktop ISO in QEMU/KVM to try it
make clean    # rm -rf dist/

Targets reference

Target	Description
all	desktop + server + lite
build-base	Build the shared base, tag version + latest
build-desktop / build-server	Build a profile (depends on base)
build-lite	Build the arm64 edge image (standalone)
iso / qcow2 / ami	Produce the matching artifact
dev-vm	Boot the desktop ISO in QEMU/KVM
clean	Remove dist/

Publishing for over-the-air updates

Once built and pushed, an image reference can be delivered to devices over the air through the cloud, or applied by hand with bootc switch (see Command line). Because updates are atomic with rollback, a bad image never bricks a device.