---
title: Windows Builds
description: Build Heretic Agent Docker images on Windows using PowerShell, Bun/TypeScript, or WSL2/Git Bash
canonical: https://giglabo.com/heretic/docs/heretic/docker-images/windows
locale: en
---

# Windows Builds

> Markdown twin of https://giglabo.com/heretic/docs/heretic/docker-images/windows
> Fetch this instead of the HTML page: same content, a fraction of the bytes.
> Site structure and the full page list for agents: https://giglabo.com/llms.txt

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.

```powershell
# 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
```

> **Warning: Execution Policy**
>
> If you get a script execution error, run: `Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser`

### Parameter Mapping (Bash vs PowerShell)

| Bash | PowerShell | Example |
|------|-----------|---------|
| `--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.

```powershell
# 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

```bash
# 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

```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
# 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)

```powershell
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

```powershell
# 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:

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

## Next Steps

- [Building Images](https://giglabo.com/heretic/docs/heretic/docker-images/building) — Full bash script reference
- [Running Containers](https://giglabo.com/heretic/docs/heretic/docker-images/running) — Docker Compose setups
- [Docker Images (CLI)](https://giglabo.com/heretic/docs/heretic-cli/configuration/docker-images) — Customize images via heretic-cli

## Related

- HTML version of this page: https://giglabo.com/heretic/docs/heretic/docker-images/windows
- Site map for agents: https://giglabo.com/llms.txt