agent-containers

A bunch of container-ed AI agents with some simple instructions for running them against your local code in slightly safer ways.

Where possible, I've documented how to persist configuration from session to session as well. As a lot of these agents store your API credentials in their configuration files, you should be really cautious about checking in config to some place like your dotfiles repo.

Prerequisites

You'll need either Docker (preferably running rootless) or podman installed on your system to build and launch these containers.

Building

To build all the containers:

make all

To build any specific container use the directory name. For example:

make claude-code

Architecture

The project uses a multi-stage build approach with a common base image (agent-base) that contains shared dependencies and configuration. Tool-specific images extend this base with their unique requirements:

agent-base
├── claude-code
└── openai-codex

Each Dockerfile uses multi-stage builds to:

• Separate build-time dependencies from runtime dependencies
• Minimize final image sizes by ~20-40%
• Improve security by reducing the attack surface
• Speed up builds through better layer caching

Build Options

The build system supports caching control options:

# Build all containers (base, claude-code, openai-codex)
make all

# Build just the base image
make base

# Build a specific tool (automatically builds base if needed)
make claude-code

# Build without cache
make claude-code DISABLE_CACHE=1

# Build using a specific image as cache source
make claude-code CACHE_FROM=claude-code:latest

Cleaning

To remove built images:

# Remove images but preserve build cache
make clean

# Remove images and prune build cache older than 24h
make deep-clean

Running

See the README files in the sub-directories for instructions on initial setup, configuration persistence and executing the AI agents in their container environments.

For launching the containers, I recommend a small set of shell functions. These will work in zsh or bash and automatically adjust for podman and docker.

function __ai_container_launcher() {
  if type podman >/dev/null; then
    LAUNCHER="podman run --userns=keep-id"
  else
    LAUNCHER="docker run"
  fi
  echo $LAUNCHER
}

function claude() {
  eval "$(__ai_container_launcher) --tty --interactive -v ${HOME}/.config/claude/claude.json:/home/codeuser/.claude.json:rw \
    -v ${HOME}/.config/claude:/home/codeuser/.claude:rw \
    -v $(pwd):/app:rw \
    claude-code $@"
}

function codex() {
  eval "$(__ai_container_launcher) --rm --tty --interactive -e OPENAI_API_KEY -v $(pwd):/app:rw openai-codex $@"
}

Put those some place in your .zshrc or .bashrc file and you'll be able to launch the agent in a working directory with a call to claude or codex. You can test they work by getting a bash shell in them with claude bash or claude codex.

See Also

• My dotfiles