Images

Images and layers

aicage uses a three-layer image model.

1) Base image

The base image is the OS + shared dev tooling. It is the foundation for all agents.

2) Agent image

An agent image is a base image plus a specific coding agent. This is what you run with aicage <agent>.

Some built-in agents are marked build_local: true because their licenses do not allow redistributing prebuilt images. Those images are built locally on your machine when needed.

3) Extensions (optional)

Extensions let you add extra tooling on top of an existing agent image. Extensions are always local and are applied in the order you select them.

Built-in vs custom

Each layer can come from:

• Built-in definitions provided by aicage.
• Custom definitions you place under ~/.aicage-custom.

If a custom definition uses the same name as a built-in one, the custom entry overrides it.