Heretic

Windows Builds

Build Heretic Agent Docker images on Windows using PowerShell, Bun/TypeScript, or WSL2/Git Bash

Three ways to build Heretic Agent Docker images on Windows.

Prerequisites

  • Docker Desktop for Windows (WSL2 backend recommended)
  • At least one of: PowerShell 5.1+, Bun runtime, or WSL2/Git Bash

Option 1: PowerShell (Recommended)

Native Windows experience with no extra tools required.

# Build Claude agent (default)
.\build-heretic-agent.ps1

# Build specific agent type
.\build-heretic-agent.ps1 -Agent copilot

# Build multiple agents (separate images)
.\build-heretic-agent.ps1 -Agent claude,copilot

# Combined mode (one image)
.\build-heretic-agent.ps1 -Agent claude,copilot -Combined

# With tools
.\build-heretic-agent.ps1 -WithPython -WithDocker

# With specific Python version
.\build-heretic-agent.ps1 -PythonVersion 3.12

# Custom base and name
.\build-heretic-agent.ps1 -Base ubuntu:22.04 -Name my-agent -Tag v1.0

# Dry run
.\build-heretic-agent.ps1 -DryRun

# Multi-arch build and push
.\build-heretic-agent.ps1 -Arch both -Push -Registry ghcr.io/myorg

Execution Policy

If you get a script execution error, run: Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Parameter Mapping (Bash vs PowerShell)

BashPowerShellExample
--agent claude-Agent claude-Agent claude,copilot
--combined-Combined(switch)
-n, --name-Name-Name my-agent
-t, --tag-Tag-Tag v1.0
-r, --registry-Registry-Registry ghcr.io/org
-p, --push-Push(switch)
--no-cache-NoCache(switch)
--dry-run-DryRun(switch)
-a, --arch-Arch-Arch arm64
--base-Base-Base ubuntu:22.04
--with-python-WithPython(switch)
--python-version-PythonVersion-PythonVersion 3.12
--with-node-WithNode(switch)
--node-version-NodeVersion-NodeVersion 20
--with-go-WithGo(switch)
--go-version-GoVersion-GoVersion 1.22.0
--with-java-WithJava(switch)
--java-version-JavaVersion-JavaVersion 17
--with-rust-WithRust(switch)
--rust-version-RustVersion-RustVersion nightly
--with-docker-WithDocker(switch)
--with-github-cli-WithGithubCli(switch)
--with-all-WithAll(switch)

Option 2: Bun / TypeScript (Cross-Platform)

Same script works on Windows, macOS, and Linux. Requires Bun installed.

# Install Bun
irm bun.sh/install.ps1 | iex

# Build (uses same flags as bash version)
bun images/build-heretic-agent.ts
bun images/build-heretic-agent.ts --agent copilot --with-python
bun images/build-heretic-agent.ts --agent claude --agent copilot --combined --with-all

Option 3: WSL2 / Git Bash

Run the original bash script directly.

With WSL2

# From PowerShell
wsl bash images/build-heretic-agent --agent claude --with-python

# Or open WSL2 terminal first
wsl
cd /mnt/c/path/to/heretic
./images/build-heretic-agent --agent claude --with-python

With Git Bash

./images/build-heretic-agent --agent claude --with-python

Running Built Images on Windows

Docker Desktop runs Linux containers via WSL2. All built images work the same way.

Interactive Mode

# PowerShell
docker run -it --rm `
  -e ANTHROPIC_API_KEY=$env:ANTHROPIC_API_KEY `
  -v ${PWD}:/workspace `
  heretic-agent:latest

# CMD
docker run -it --rm ^
  -e ANTHROPIC_API_KEY=%ANTHROPIC_API_KEY% ^
  -v %cd%:/workspace ^
  heretic-agent:latest

With Docker Socket (DooD)

docker run -it --rm `
  -v //var/run/docker.sock:/var/run/docker.sock `
  -v ${PWD}:/workspace `
  heretic-agent:latest

Troubleshooting

Docker Desktop Not Running

Start Docker Desktop from the Start Menu or system tray.

WSL2 Integration

Ensure Docker Desktop has WSL2 integration enabled:

  1. Open Docker Desktop Settings
  2. Go to Resources > WSL Integration
  3. Enable integration with your WSL2 distro

Path Issues with Volume Mounts

# Use ${PWD} in PowerShell (not $(pwd))
docker run -v ${PWD}:/workspace heretic-agent:latest

# In CMD, use %cd%
docker run -v %cd%:/workspace heretic-agent:latest

Buildx Not Available

Multi-arch builds require Docker Buildx:

docker buildx version
docker buildx create --name heretic-builder --use

Next Steps