Running Containers

Entrypoint Modes

The container entrypoint supports two modes:

Interactive Mode — when no command is passed, starts a bash shell:

docker run -it heretic-agent:latest

Workflow Mode — when PROMPT_FILE is set, executes the agent with the prompt:

docker run -i \
  -e PROMPT_FILE=/workspace/prompt.md \
  -e REPO_PATH=/workspace \
  -v $(pwd):/workspace \
  --entrypoint /home/agent/entrypoint.sh \
  heretic-agent:latest

Environment Variables

Agent-Specific

Agent	Variable	Description
Claude	`ANTHROPIC_API_KEY`	Anthropic API key
Copilot	`GITHUB_TOKEN`	GitHub token with Copilot access
OpenCode	`ANTHROPIC_API_KEY`	Anthropic API key
Gemini	`GOOGLE_API_KEY`	Google AI API key

Common

Variable	Description	Default
`AGENT_TYPE`	Agent type identifier	`claude`
`GH_TOKEN`	GitHub token for git operations	—
`GIT_AUTHOR_NAME`	Git commit author name	`Heretic Agent`
`GIT_AUTHOR_EMAIL`	Git commit author email	`[email protected]`
`API_TIMEOUT_MS`	API request timeout	`3000000`
`HERETIC_DIR`	Agent config files directory	`/workspace/.heretic`
`REPO_PATH`	Working directory path	`/workspace`

Backend Variables

Variable	Description	Default
`BUILD_SIDECARS`	Sidecar configuration JSON	—
`SSH_HOST`	SSH backend host	—
`SSH_PORT`	SSH port	`22`
`SSH_USER`	SSH username	`agent`
`SSH_HOST_CWD`	Working directory on remote host	—

Docker Compose Setups

Basic Setup

services:
  claude:
    image: heretic-agent:latest
    container_name: claude-agent
    stdin_open: true
    tty: true
    environment:
      - AGENT_TYPE=claude
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
    volumes:
      - ./workspace:/workspace
      - ./claude-settings.json:/home/agent/.claude/settings.json:ro
    working_dir: /workspace
    command: /bin/bash

docker compose up -d
docker attach claude-agent    # Ctrl+P, Ctrl+Q to detach
docker compose down

Combined Agent Image

Use one image with multiple agents, select at runtime:

services:
  agent:
    image: heretic-local-fat:latest
    container_name: heretic-agent
    stdin_open: true
    tty: true
    environment:
      - AGENT_TYPE=${AGENT_TYPE:-claude}
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - GITHUB_TOKEN=${GITHUB_TOKEN}
      - GOOGLE_API_KEY=${GOOGLE_API_KEY}
    volumes:
      - ./workspace:/workspace
    working_dir: /workspace
    command: /bin/bash

# Start with Claude (default)
docker compose up -d

# Switch to Copilot
docker compose down
AGENT_TYPE=copilot docker compose up -d

With Docker-in-Docker (DooD)

Mount the host Docker socket for Docker access inside the container:

services:
  claude:
    image: heretic-agent:latest
    container_name: claude-dind
    stdin_open: true
    tty: true
    environment:
      - AGENT_TYPE=claude
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
    volumes:
      - ./workspace:/workspace
      - /var/run/docker.sock:/var/run/docker.sock
    working_dir: /workspace
    command: /bin/bash

Security Note

Mounting the Docker socket gives the container full access to the host Docker daemon. Only use for trusted workloads.

With Sidecars

Keep the agent image slim and route tool commands to sidecar containers:

services:
  claude:
    image: heretic-agent:latest
    container_name: claude-agent
    stdin_open: true
    tty: true
    environment:
      - AGENT_TYPE=claude
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - BUILD_SIDECARS={"python":{"internal_url":"http://python-sidecar:8080"},"node":{"internal_url":"http://node-sidecar:8080"}}
    volumes:
      - ./workspace:/workspace
    working_dir: /workspace
    command: /bin/bash
    depends_on:
      - python-sidecar
      - node-sidecar

  python-sidecar:
    image: builder-python:latest
    volumes:
      - ./workspace:/workspace

  node-sidecar:
    image: builder-node:latest
    volumes:
      - ./workspace:/workspace

The BUILD_SIDECARS JSON maps runtime names to sidecar endpoints. Commands like python3, pip, npm are transparently routed.

Detailed Sidecar Guide

For wrapper mechanics, all runtime keys, exec-server API, custom images, and debugging — see Sidecars & SSH.

With SSH Backend

Route tool commands to a remote host via SSH:

services:
  claude:
    image: heretic-agent:latest
    container_name: claude-ssh
    stdin_open: true
    tty: true
    environment:
      - AGENT_TYPE=claude
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - SSH_HOST=${SSH_HOST}
      - SSH_PORT=${SSH_PORT:-22}
      - SSH_USER=${SSH_USER:-agent}
      - SSH_HOST_CWD=${SSH_HOST_CWD:-/workspace}
    volumes:
      - ./workspace:/workspace
      - ${SSH_KEY_FILE:-/dev/null}:/home/agent/.ssh/id_rsa:ro
    working_dir: /workspace
    command: /bin/bash

SSH_HOST=devbox.example.com SSH_KEY_FILE=~/.ssh/id_rsa docker compose up -d

Detailed SSH Guide

For key management, combined sidecar + SSH setups, and debugging — see Sidecars & SSH.

Multi-Agent Setup

Run multiple agent types simultaneously:

services:
  claude:
    image: heretic-agent:latest
    container_name: claude-agent
    stdin_open: true
    tty: true
    environment:
      - AGENT_TYPE=claude
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
    volumes:
      - ./workspace:/workspace
    working_dir: /workspace
    command: /bin/bash

  copilot:
    image: heretic-agent-copilot:latest
    container_name: copilot-agent
    stdin_open: true
    tty: true
    environment:
      - AGENT_TYPE=copilot
      - GITHUB_TOKEN=${GITHUB_TOKEN}
    volumes:
      - ./workspace:/workspace
    working_dir: /workspace
    command: /bin/bash

  gemini:
    image: heretic-agent-gemini:latest
    container_name: gemini-agent
    stdin_open: true
    tty: true
    environment:
      - AGENT_TYPE=gemini
      - GOOGLE_API_KEY=${GOOGLE_API_KEY}
    volumes:
      - ./workspace:/workspace
    working_dir: /workspace
    command: /bin/bash

Troubleshooting

Container Exits Immediately

docker logs claude-agent
docker run -it --rm heretic-agent:latest /bin/bash

Permission Denied on Workspace

sudo chown -R 1000:1000 ./workspace

Agent Settings Not Loading

# Claude
docker exec claude-agent cat /home/agent/.claude/settings.json
# OpenCode
docker exec opencode-agent cat /home/agent/.config/opencode/config.json
# Check HERETIC_DIR
docker exec claude-agent ls -la /workspace/.heretic/

Sidecar Commands Not Found

docker exec claude-agent env | grep BUILD_SIDECARS
docker exec claude-agent curl http://python-sidecar:8080/health
docker exec claude-agent ls /opt/sidecar/wrappers/

SSH Backend Not Working

docker exec claude-agent env | grep SSH_HOST
docker exec claude-agent ssh -o StrictHostKeyChecking=no ${SSH_USER:-agent}@${SSH_HOST} echo "connected"
docker exec claude-agent ls -la /home/agent/.ssh/id_rsa

Docker Commands Fail (DinD)

docker run -it --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  heretic-agent:latest docker ps

Next Steps

Sidecars & SSH — Detailed sidecar and SSH setup guide
Building Images — Build script reference
Customizing Images — Tools, versions, and backends
Windows Builds — Building on Windows
Docker Images (CLI) — Customize images via heretic-cli