Customizing Images | VibeCoder Heretic

Quick Customizations via CLI

The same customizations are available from the CLI with heretic-cli image build (and heretic-cli image generate to inspect the Dockerfile first). See heretic-cli image.

Base Image Selection

Choose the base image based on your use case:

Image	Use Case	Size
`node:22-bookworm-slim`	Production, CI/CD, K8s	Small
`ubuntu:22.04`	Local development, full terminal	Medium
`debian:bookworm-slim`	Middle ground	Small

# Local dev with full terminal
./build-heretic-agent --base ubuntu:22.04 --with-python --with-docker

# Slim production image
./build-heretic-agent --base node:22-bookworm-slim

Ubuntu base images automatically configure en_US.UTF-8 locale for proper Unicode handling.

Tool Version Control

Control versions for all major tools. Version flags automatically enable the corresponding --with-* flag.

Python

./build-heretic-agent --python-version 3.13   # Default
./build-heretic-agent --python-version 3.12
./build-heretic-agent --python-version 3.11

Includes: pip, poetry, pytest, black, ruff, mypy.

Node.js

./build-heretic-agent --node-version 22   # Default
./build-heretic-agent --node-version 20
./build-heretic-agent --node-version 18

Includes: npm, yarn (via corepack), pnpm (via corepack). Node.js is automatically installed for non-node base images.

Go

./build-heretic-agent --go-version 1.23.4   # Default
./build-heretic-agent --go-version 1.22.0
./build-heretic-agent --go-version 1.21.5

Includes: go, gofmt.

Java

./build-heretic-agent --java-version 21   # Default
./build-heretic-agent --java-version 17
./build-heretic-agent --java-version 11

Includes: Java (Eclipse Temurin), Maven 3.9.6, Gradle 8.5.

Rust

./build-heretic-agent --rust-version stable   # Default
./build-heretic-agent --rust-version nightly
./build-heretic-agent --rust-version beta
./build-heretic-agent --rust-version 1.75

Includes: cargo, rustfmt, clippy.

Combining Versions

./build-heretic-agent \
  --agent claude \
  --python-version 3.12 \
  --node-version 20 \
  --go-version 1.22.0 \
  --java-version 17 \
  --rust-version nightly \
  --base ubuntu:22.04

Combined Mode

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

# Build combined image
./build-heretic-agent \
  --agent claude --agent copilot \
  --combined \
  --with-python --with-docker \
  --name heretic-multi

# Use Claude
docker run -it -e AGENT_TYPE=claude -e ANTHROPIC_API_KEY=$KEY heretic-multi:latest

# Use Copilot (same image)
docker run -it -e AGENT_TYPE=copilot -e GITHUB_TOKEN=$TOKEN heretic-multi:latest

Benefits:

Smaller total disk usage (shared base layers)
One image tag to manage
Runtime agent switching without rebuilding

Build all agents in one image:

./build-heretic-agent \
  --agent claude --agent copilot --agent opencode --agent gemini \
  --combined \
  --with-all \
  --name heretic-fat

Always-Included Tools

All images include these tools by default:

Tool	Description
vim	Text editor
git	Version control
curl	HTTP client
jq	JSON processor
ssh	SSH client (openssh-client)
ca-certificates	SSL/TLS certificates

Agent-Specific Configuration

Each agent type has different settings requirements:

Agent	Config File	Config Source	Env Vars
Claude	`~/.claude/settings.json`	`${HERETIC_DIR}/claude-settings.json`	`ANTHROPIC_API_KEY`, `GH_TOKEN`
Copilot	Token-based (no config)	—	`GITHUB_TOKEN`, `GH_TOKEN`
OpenCode	`~/.config/opencode/config.json`	`${HERETIC_DIR}/opencode.json`	`ANTHROPIC_API_KEY`, `GITHUB_TOKEN`
Gemini	Environment only	—	`GOOGLE_API_KEY`, `GITHUB_TOKEN`

Execution Backends

Tool commands are resolved at container start using three backends in priority order:

1. Fat/Local (Built-in)

Tools installed in the image, used directly. Enable with --with-* flags.

./build-heretic-agent --with-python --with-docker

2. Sidecar (HTTP)

Set BUILD_SIDECARS at runtime to route commands to sidecar containers:

docker run -it \
  -e BUILD_SIDECARS='{"python":{"internal_url":"http://python-sidecar:8080"}}' \
  heretic-agent:latest

3. SSH

Set SSH_HOST at runtime to route commands to a remote host:

docker run -it \
  -e SSH_HOST=devbox.example.com \
  -e SSH_USER=developer \
  -v ~/.ssh/id_rsa:/home/agent/.ssh/id_rsa:ro \
  heretic-agent:latest

The entrypoint generates wrapper scripts in /opt/sidecar/wrappers/ for any command not natively available. The same image works with any backend.

Backend	When to Use
Built-in	Local dev, small images acceptable
Sidecar	CI/CD, slim images, shared tools
SSH	Remote dev environments, security isolation

Next Steps

Building Images — Full build script reference
Running Containers — Docker Compose setups
Docker Images (CLI) — Quick customizations via heretic-cli