Aicage Custom Samples

aicage - Runs agentic coding assistants in Docker containers

---

This project holds samples for customization of aicage images.

Aicage Images

Image Layers

Aicage images are built in layers:

1. base-image: The core layer with the OS and all software needed for development
2. agent: The coding agent is added to a base-image
3. optional extensions: Custom extensions add more software to images

All layers can be fully customized. Users can write their own, and aicage builds the remaining layers on the user's PC.

Image Updates

aicage also updates the images when needed by checking:

• base-image digest local vs. remote
• agent version
• (extensions currently not checked)

Usage

Clone this repo to ~/.aicage-custom and start aicage with a coding agent.

git clone https://github.com/aicage/aicage-custom-samples.git ~/.aicage-custom

aicage <AGENT>

Extensions

Extensions are the easiest way to add more software to Aicage images.

Current extension samples in this repository:

• act: Run GitHub Actions locally
• crane: Install crane
• cosign: Install sigstore/cosign
• dotnet: Install the .NET SDK
• gcloud: Install the Google Cloud CLI
• gh: Install GitHub CLI
• nvidia-cuda: Install NVIDIA CUDA user-space tooling
• php: Install PHP CLI tooling and Composer
• regctl: Install regctl
• shellcheck: Install ShellCheck
• skopeo: Work with remote container images and registries

Aicage will automatically build a custom image with your chosen extensions on top of the base+agent image.

Add your own extension

You can easily add your own extension by adding a folder to ~/.aicage-custom/extensions.

Examples/Templates:

• act
• crane
• cosign
• dotnet
• gcloud
• gh
• nvidia-cuda
• php
• regctl
• shellcheck
• skopeo

Custom agents

Current custom agent samples in this repository:

• auggie
• forge
• kimi
• vibe

Use one with:

aicage <AGENT>

Aicage will automatically build a custom image with your chosen base.

Add your own coding agent

You can easily add your own custom agent by adding a folder to ~/.aicage-custom/agents.

Examples/Templates:

• auggie
• forge
• kimi
• vibe
• aicage-image/agents for the builtin agents.

Base-images

Current custom base-image samples in this repository:

• act
• debian-mirror
• minimal
• php

Add your own custom base-image

Extensions are much easier and more convenient than custom bases.

Add a folder to ~/.aicage-custom/base-images for your personal base-image.

Examples/Templates:

• act
• debian-mirror
• minimal
• php
• aicage-image-base/bases for the builtin bases

Notes:

• A base-image must contain everything for development.
• Plus the entrypoint.sh from aicage - feel free to copy and extend it.
• Use the same base.yml schema as the builtin bases.

Test build your custom base-image

aicage builds images automatically on start, this helps when writing your custom base-image.

Test-build it with (example for base minimal):

BASE=minimal
FROM_IMAGE=alpine:latest

docker build \
  --tag aicage-image-base:${BASE} \
  --build-arg FROM_IMAGE=${FROM_IMAGE} \
  ~/.aicage-custom/base-images/${BASE}

YAML validation

You can validate your YAML files against their schemas.

Setup

cd ~/.aicage-custom

echo "Setting up dependencies"
python3 -m venv .venv
source .venv/bin/activate
pip install check-jsonschema

echo "Validate agent.yml files with schema"
check-jsonschema \
  --schemafile validation/agent.schema.json \
  agents/*/agent.yml

echo "Validate base.yml files with schema"
check-jsonschema \
  --schemafile validation/base.schema.json \
  base-images/*/base.yml

echo "Validate extension.yml files with schema"
check-jsonschema \
  --schemafile validation/extension.schema.json \
  extensions/*/extension.yml