Building Images | VibeCoder Heretic

Alternative: heretic-cli image commands

To build the same images without a checkout of this script, use heretic-cli image build — the Dockerfile, entrypoint and backend clients are embedded in the CLI binary. See heretic-cli image.

Basic Usage

# Default build (Claude agent, slim, node-based)
./build-heretic-agent

# Build specific agent type
./build-heretic-agent --agent copilot

# With specific tools
./build-heretic-agent --agent claude --with-python --with-docker

# With all tools
./build-heretic-agent --agent gemini --with-all

Agent Selection

Build one, multiple, or all agents. Without --combined, each agent gets its own image:

# Single agent
./build-heretic-agent --agent claude

# Multiple agents (separate images)
./build-heretic-agent --agent copilot --agent gemini
# Creates: heretic-agent-copilot:latest, heretic-agent-gemini:latest

# All agent types (separate images)
./build-heretic-agent --agent all
# Creates 5 images: heretic-agent:latest, heretic-agent-copilot:latest, etc.

# Combined mode — multiple agents in ONE image
./build-heretic-agent --agent claude --agent copilot --combined
# Creates: heretic-agent:latest (both CLIs installed)

With combined mode, select the agent at runtime via AGENT_TYPE:

docker run -it -e AGENT_TYPE=claude heretic-agent:latest
docker run -it -e AGENT_TYPE=copilot heretic-agent:latest

Command-Line Options

Agent Options

Option	Description	Default
`--agent TYPE`	Agent type: `claude`, `copilot`, `opencode`, `gemini`, `all`. Can be specified multiple times.	`claude`
`--combined`	Install all specified agents in ONE image	`false`

Image Options

Option	Description	Default
`-n, --name NAME`	Image name	`heretic-agent`
`-t, --tag TAG`	Image tag	`latest`
`-r, --registry REG`	Registry prefix	(none)
`-p, --push`	Push after build	`false`
`--dry-run`	Print Dockerfile only	`false`
`--no-cache`	Build without Docker cache	`false`

Architecture Options

Option	Description	Default
`-a, --arch ARCH`	Architecture: `amd64`, `arm64`, `both`	Current platform

Base Image Options

Option	Description
`--base IMAGE`	Base Docker image

Recommended base images:

Image	Use Case
`node:22-bookworm-slim`	Slim, good for K8s/production
`ubuntu:22.04`	Full terminal, good for local dev
`debian:bookworm-slim`	Middle ground

Tool Options

Option	Includes	Default Version	Version Flag
`--with-python`	Python 3, pip, poetry, pytest, black, ruff, mypy	3.13	`--python-version 3.11\|3.12\|3.13`
`--with-node`	Node.js (npm, yarn, pnpm via corepack)	22	`--node-version 18\|20\|22`
`--with-go`	Go compiler, gofmt	1.23.4	`--go-version 1.21.5\|1.22.0\|1.23.4`
`--with-java`	Java (Temurin), Maven 3.9.6, Gradle 8.5	21	`--java-version 11\|17\|21`
`--with-rust`	Rust, Cargo, rustfmt, clippy	stable	`--rust-version stable\|nightly\|beta\|1.75`
`--with-docker`	Docker CLI (for DinD/DooD)	latest	—
`--with-github-cli`	GitHub CLI (gh)	latest	—
`--with-all`	All tools above	—	Use individual version flags

Version Flags

Version flags automatically enable the corresponding --with-* flag. Node.js is always installed for non-node base images (required for agent CLIs).

Agent User Options

Option	Description	Default
`--agent-user USER`	Agent username	`agent`
`--agent-uid UID`	Agent user ID	`1000`
`--agent-gid GID`	Agent group ID	`1000`

Multi-Architecture Builds

# ARM64 (Apple Silicon)
./build-heretic-agent --agent claude --arch arm64

# Both architectures with registry push
./build-heretic-agent \
  --agent claude \
  --arch both \
  --with-all \
  --push \
  --registry ghcr.io/myorg

Environment Variables

Override defaults via environment variables:

Variable	Description
`AGENT_TYPE`	Default agent type
`IMAGE_NAME`	Default image name
`IMAGE_TAG`	Default image tag
`REGISTRY`	Default registry
`BASE_IMAGE`	Default base image

Examples

Local Development Image

./build-heretic-agent \
  --agent claude \
  --base ubuntu:22.04 \
  --with-python \
  --with-go \
  --with-docker \
  --with-github-cli \
  --name claude-local \
  --tag dev

Slim Production Image

./build-heretic-agent \
  --agent gemini \
  --base node:22-bookworm-slim \
  --with-github-cli \
  --name gemini-prod \
  --tag v1.0.0

Multi-Arch Registry Push

./build-heretic-agent \
  --agent copilot \
  --with-python \
  --with-node \
  --with-docker \
  --arch both \
  --push \
  --registry ghcr.io/myorg \
  --name copilot-agent \
  --tag v2.0.0

All Agents with All Tools

./build-heretic-agent --agent all --with-all --push --registry ghcr.io/myorg

Next Steps

Windows Builds — PowerShell and cross-platform alternatives
Customizing Images — Tools, versions, and combined mode in detail
Running Containers — Docker Compose setups and execution backends
Docker Images (CLI) — Customize images via heretic-cli