Docker Images

Every agent runs inside a Docker container. The image: field in your agent profile controls which image is used:

# ~/.heretic/agents/claude.yaml
image: giglabo/claude-heretic:latest

The image is pulled automatically when you run heretic-cli run <agent>. You can use pre-built images, build from scratch with the standalone builder, or extend any image with heretic-cli image commands.

Pre-Built Images

Giglabo publishes slim images for each agent type:

What's Inside Every Pre-Built Image

All pre-built images include the same base layer:

Plus the agent-specific CLI:

Changing the Image

Update via CLI:

heretic-cli agents edit claude

Or edit the YAML directly:

# ~/.heretic/agents/claude.yaml
image: my-custom-agent:v2

Local overrides can change the image per-project:

# .heretic/cli/claude.yaml
image: my-project-agent:latest

Building Images from Scratch

Use the standalone build-heretic-agent script for full control over base image, tools, and architecture. This is a separate tool outside of heretic-cli.

Example 1: Node.js 22 + Python 3.13 (Most Common)

The standard full-stack image for projects that use both JavaScript/TypeScript and Python — Next.js + FastAPI, monorepos with mixed languages, or any project where the agent needs both ecosystems:

./build-heretic-agent \
  --agent claude \
  --base ubuntu:22.04 \
  --with-python \
  --with-node \
  --name claude-fullstack

What this creates (~1.1GB):

What the agent can do with this image:

• Run npm install, pnpm build, yarn test for JS/TS projects
• Run pip install, poetry install, pytest, black, ruff for Python projects
• Use git for all repo operations (clone, commit, push, create branches)
• Use gh pr create, gh issue list for GitHub workflows
• Edit files with vim
• Fetch APIs with curl, parse JSON with jq

Use in your profile:

# ~/.heretic/agents/claude.yaml
image: claude-fullstack:latest

heretic-cli run claude

Example 2: Python Full-Stack + Docker Access

Same as above but with Docker CLI for projects where the agent needs to build or run containers (e.g., testing Docker Compose setups, building images):

./build-heretic-agent \
  --agent claude \
  --base ubuntu:22.04 \
  --with-python \
  --with-docker \
  --name claude-python-dev

What this adds on top of Example 1 (~1.2GB total):

Use in your profile:

# ~/.heretic/agents/claude.yaml
image: claude-python-dev:latest
dind: true   # Mount Docker socket so agent can run containers

heretic-cli run claude

Example 3: Multi-Language CI/CD Image

For an agent that needs to work across multiple languages:

./build-heretic-agent \
  --agent claude \
  --base ubuntu:22.04 \
  --with-python \
  --with-go \
  --with-java \
  --with-docker \
  --python-version 3.12 \
  --go-version 1.22.0 \
  --java-version 17 \
  --name claude-polyglot

What this creates (~1.8GB):

Example 4: Slim Production Image with Sidecars

For K8s deployments where tools run in separate sidecar containers:

./build-heretic-agent \
  --agent claude \
  --base node:22-bookworm-slim \
  --name claude-slim

What this creates (~450MB):

No Python, Go, Java, or Rust — tool commands are routed to sidecars via HTTP or to a remote host via SSH at runtime. The same image works in any environment depending on which env vars you set.

Example 5: Combined Multi-Agent Image

Build one image with multiple agent CLIs, select at runtime with AGENT_TYPE:

./build-heretic-agent \
  --agent claude --agent copilot --agent gemini \
  --combined \
  --with-python \
  --with-docker \
  --base ubuntu:22.04 \
  --name heretic-multi

What this creates (~1.5GB):

Use in your profile — switch agents without rebuilding:

# ~/.heretic/agents/claude.yaml
image: heretic-multi:latest

# ~/.heretic/agents/copilot.yaml
image: heretic-multi:latest   # Same image, different agent_type

Example 6: Rust Systems Development Image

For an agent working on Rust projects:

./build-heretic-agent \
  --agent claude \
  --base ubuntu:22.04 \
  --with-rust \
  --rust-version stable \
  --with-docker \
  --name claude-rust

What this creates (~1.4GB):

See the Docker Images Builder documentation for the full reference:

• Building images — all CLI options and flags
• Windows builds — PowerShell, Bun/TypeScript, and WSL2 approaches
• Customizing images — tool versions, combined mode, execution backends
• Running containers — Docker Compose, DinD, sidecars, SSH backend

Customizing Images with heretic-cli

For project-specific tweaks on top of an existing image — pinning a package version, adding a few system packages, or installing project-specific tools — use heretic-cli image commands instead of rebuilding from scratch.

How It Works

heretic-cli image customize generates a Dockerfile.custom that extends any base image. You edit it, then heretic-cli image apply builds the result. The generated Dockerfile has two sections: root user (for apt-get install, system-level changes) and agent user (for npm install -g, user-level tools).

heretic-cli image customize

heretic-cli image customize [options]
  --base <image>       Base image to extend (default: heretic-agent:latest)
  --output <path>      Output path (default: .heretic/Dockerfile.custom)
  --global             Write to ~/.heretic/Dockerfile.custom instead
  --agent-user <user>  Agent username for USER directive (default: agent)

heretic-cli image apply

heretic-cli image apply [options]
  --file <path>        Path to custom Dockerfile (auto-detected if omitted)
  --base <image>       Override BASE_IMAGE build arg
  -n, --name <name>    Output image name (default: heretic-agent-custom)
  -t, --tag <tag>      Image tag (default: latest)
  -r, --registry <reg> Registry prefix
  -p, --push           Push after build
  --no-cache           Build without Docker cache
  --dry-run            Print resolved path and exit
  -a, --arch <arch>    Architecture: amd64, arm64, or both

Auto-detection order when --file is not specified:

1. .heretic/Dockerfile.custom (project-level)
2. ~/.heretic/Dockerfile.custom (global fallback)
3. Error with suggestion to run heretic-cli image customize

Real-World Examples

Example A: Pin pnpm for a Monorepo

Your monorepo requires pnpm 9.x but the base image ships corepack with pnpm 10:

# 1. Generate the Dockerfile
heretic-cli image customize --base giglabo/claude-heretic:latest

# 2. Edit .heretic/Dockerfile.custom:

ARG BASE_IMAGE=giglabo/claude-heretic:latest
FROM ${BASE_IMAGE}

# --- Root section (system packages) ---
USER root
# Nothing needed here

# --- Agent section (user tools) ---
USER agent
RUN corepack install -g [email protected]

# 3. Build and name it
heretic-cli image apply --name claude-monorepo

# 4. Update your local override to use it
# .heretic/cli/claude.yaml
# image: claude-monorepo:latest

Result: Same as giglabo/claude-heretic:latest but with pnpm pinned to 9.15.4.

Example B: Add PostgreSQL Client and Redis CLI

Your agent needs to inspect databases and caches during debugging:

heretic-cli image customize --base claude-python-dev:latest

ARG BASE_IMAGE=claude-python-dev:latest
FROM ${BASE_IMAGE}

# --- Root section (system packages need root) ---
USER root
RUN apt-get update && apt-get install -y --no-install-recommends \
    postgresql-client \
    redis-tools \
  && rm -rf /var/lib/apt/lists/*

# --- Agent section ---
USER agent

heretic-cli image apply --name claude-python-db

Result: Your Python dev image + psql and redis-cli available for the agent to query databases.

Example C: Add Project-Specific Python Packages

Your project uses specific ML libraries that take a long time to install:

heretic-cli image customize --base claude-python-dev:latest

ARG BASE_IMAGE=claude-python-dev:latest
FROM ${BASE_IMAGE}

USER agent
RUN pip install --user \
    pandas==2.2.0 \
    sqlalchemy==2.0.25 \
    alembic==1.13.1 \
    httpx==0.27.0

heretic-cli image apply --name claude-ml-agent

Result: Python packages pre-installed so the agent doesn't waste time on pip install during every session.

Example D: Global Custom Image Shared Across Projects

Install your team's standard tools once and share across all projects:

# Generate global Dockerfile
heretic-cli image customize --global --base giglabo/claude-heretic:latest

ARG BASE_IMAGE=giglabo/claude-heretic:latest
FROM ${BASE_IMAGE}

USER root
RUN apt-get update && apt-get install -y --no-install-recommends \
    ripgrep \
    fd-find \
    bat \
    htop \
  && rm -rf /var/lib/apt/lists/*

USER agent
RUN npm install -g tsx typescript@5

heretic-cli image apply --name team-claude-base

# Set as default image for your agent
heretic-cli agents edit claude
# image: team-claude-base:latest

Result: Every project using this agent gets ripgrep, fd, bat, htop, tsx, and TypeScript pre-installed. Individual projects can further extend with their own .heretic/Dockerfile.custom.

Next Steps

• Agent Profiles — Full profile YAML reference
• Docker Images Builder — Build images from scratch with the standalone script
• Running Containers — Docker Compose setups, DinD, sidecars, SSH