Customization Base Images

Custom base images

Custom base images let you build and update base layers locally. They live under ~/.aicage-custom/base-images/ and show up alongside built-in bases during selection.

If a custom base name matches a built-in base name, the custom base overrides it.

Directory layout

~/.aicage-custom/base-images/<BASE>/
├─ base.yml (or base.yaml)
└─ Dockerfile

base.yml

from_image: debian:bookworm
base_image_distro: Debian
base_image_description: "Debian base image"

Dockerfile

The Dockerfile builds the custom base image. The build arg FROM_IMAGE is provided:

ARG FROM_IMAGE
FROM ${FROM_IMAGE} AS from_image

Keep the build non-interactive and deterministic.

Examples

• PHP sample
• Debian mirror sample