Docker Images
Build, customize, and run Heretic Agent Docker images with configurable tools, multi-arch support, and multiple execution backends
The Heretic Agent Image Builder (build-heretic-agent) is a standalone build system for creating agent Docker images. It supports multiple agent types, configurable tools, multi-architecture builds, and three execution backends.
Two Ways to Customize Images
heretic-cli image build covers the same ground from the CLI, with the templates embedded in the binary — see heretic-cli image and Docker Images (CLI). Use the build-heretic-agent script documented here when you want a self-contained shell build outside the CLI.
Supported Agents
| Agent | CLI Package | Authentication |
|---|---|---|
| Claude | @anthropic-ai/claude-code | ANTHROPIC_API_KEY |
| Copilot | @github/copilot | GITHUB_TOKEN |
| OpenCode | opencode-ai | ANTHROPIC_API_KEY |
| Gemini | @google/gemini-cli | GOOGLE_API_KEY |
Quick Start
# Build Claude agent (default)
./build-heretic-agent
# Build with Python and Docker CLI for local dev
./build-heretic-agent --agent claude --with-python --with-docker --name claude-local
# Run interactively
docker run -it --rm \
-v /var/run/docker.sock:/var/run/docker.sock \
-v $(pwd):/workspace \
claude-local:latest
Key Features
- Multiple agent types — build one, multiple, or all at once
- Combined mode — install multiple agents in ONE image, select at runtime with
AGENT_TYPE - Tool version control — Python (3.11–3.13), Node.js (18–22), Go (1.21–1.23), Java (11–21), Rust (stable/nightly/beta)
- Multi-arch — build for amd64, arm64, or both
- Three execution backends — fat/local, sidecar (HTTP), and SSH — resolved at runtime
Execution Backends
Tool commands are resolved at container start using three backends in priority order:
| Priority | Backend | Detection | How It Works |
|---|---|---|---|
| 1 | Fat/local | Binary in PATH | Tool installed in image, used directly |
| 2 | Sidecar | BUILD_SIDECARS env var | HTTP wrappers via sidecar-exec |
| 3 | SSH | SSH_HOST env var | SSH wrappers via ssh-exec |
The same image works with any backend depending on environment variables set at runtime — no build-time flags needed.
Image Size Reference
| Configuration | Base Image | Tools | Agents | Size |
|---|---|---|---|---|
| Minimal | node:22-bookworm-slim | GitHub CLI only | Claude | ~450MB |
| Standard | ubuntu:22.04 | Python, Node, Docker CLI, GitHub CLI | Claude | ~1.2GB |
| Combined | ubuntu:22.04 | Python, Node, Docker CLI, GitHub CLI | Claude + Copilot | ~1.5GB |
| Fat | ubuntu:22.04 | All tools | All 4 agents | ~2.0GB |
Documentation
- Building Images — Complete build script reference and CLI options
- Windows Builds — PowerShell, Bun/TypeScript, and WSL2 approaches
- Customizing Images — Base images, tool selection, version control, combined mode
- Running Containers — Docker Compose, DinD, sidecars, SSH, multi-agent setups