Setup & Upgrade

This guide takes you from an empty machine to a running agent, then covers upgrades and health checks.

1. Prerequisites

• Docker Engine or Docker Desktop — running, API version ≥ 1.41
• docker CLI on PATH — used for attach, docker compose, and image builds
• Bun ≥ 1.2 — for the package install (not needed for a native binary)

curl -fsSL https://bun.sh/install | bash          # macOS / Linux
powershell -c "irm bun.sh/install.ps1 | iex"      # Windows

2. Install

bun install -g @giglabo/heretic-cli
heretic-cli -v

Other options (native binary, from source) are on the Installation page.

3. Global setup: heretic-cli init

heretic-cli init

The wizard has two phases and no flags — it is fully interactive and idempotent, so you can re-run it any time.

Phase 1 — GitHub tokens. Two optional prompts (GitHub token, GitHub Copilot token). Existing values are shown masked; pressing Enter keeps them. Each token is written into a secret script and only the script path is stored in ~/.heretic/settings.yaml.

Phase 2 — agent profiles. A loop where you add or delete profiles. Adding one starts with the agent type:

Profile names must match [a-z0-9-_]+. For Anthropic agents you also choose the token type — API key (API billing) or OAuth token (Claude subscription) — which decides the environment block written into the profile.

The full prompt-by-prompt reference is on the init page.

What gets created

~/.heretic/
├── settings.yaml                    # github.token / github.copilot_token (paths to scripts)
├── agents/
│   └── claude.yaml                  # one file per agent profile
├── get-github-token-key.sh          # GitHub token script   (.cmd on Windows)
├── get-copilot-token-key.sh         # Copilot token script  (.cmd on Windows)
├── get-claude-key.sh                # per-agent token script: get-<profile>-key.sh
└── claude-settings.json             # per-agent Claude Code settings: <profile>-settings.json

Token security

Tokens live inside generated scripts, and the profile only references the script path. The default script is a plain echo — replace the body with your own secret store and nothing else changes:

#!/bin/bash
# macOS Keychain
security find-generic-password -s 'anthropic-key' -w

# 1Password CLI
op read 'op://vault/Anthropic API/credential'

# pass
pass show anthropic/api-key

See Secrets for the three secret value modes and the exact resolution rules.

4. Project setup

cd /path/to/your/project
heretic-cli local-init claude

This creates .heretic/cli/claude.yaml (a commented template), .heretic/cli/claude-settings.json, and .heretic/temp/, and suggests adding .heretic/cli/ to .gitignore.

5. Run the agent

heretic-cli run claude
# shorthand:
heretic-cli claude

The CLI resolves the global profile, merges the local override and CLI flags, runs secret scripts, generates the session files, and starts the container. See run.

6. More agents

heretic-cli agents add claude-zai     # interactive, container-focused prompts
heretic-cli init                      # full wizard, provider presets and model env vars
heretic-cli agents list

agents add cannot set secrets, mcp, provider, tool_backends and similar fields — use heretic-cli agents edit <name> --editor or the init wizard for those. See agents.

Upgrading

heretic-cli update downloads the latest GitHub release asset and stages it next to the executable as .heretic-cli.pending; the next heretic-cli invocation applies it, prints Update applied successfully! and exits without running your command — so run it twice:

heretic-cli update
heretic-cli -v        # applies the staged update, then prints the new version

For package installs the command detects it and points you at bun update instead. Full behaviour, including rollback, is on the update page.

Health checks

heretic-cli doctor
heretic-cli doctor --fix

doctor checks the Docker daemon, Docker API version, Docker Compose availability, ~/.heretic, settings.yaml, global profiles, local configs, required images, Docker Hub reachability, and volume source paths. --fix does exactly two things: create ~/.heretic and pull missing profile images.

Verbose output

-V/--verbose and --log-file are program-level options and must come before the subcommand — anything after the agent name is passed to the container instead:

heretic-cli -V run claude
heretic-cli --log-file ./heretic.log doctor

Deleting an agent

heretic-cli agents delete claude        # -f to skip the confirmation

Stops and removes that agent's containers, then deletes the profile YAML, its secret scripts (.sh and .cmd) and its Claude settings file. Project-local .heretic/ files, images and cache volumes are left alone.

Next Steps

• Quick Start — three complete agent recipes
• Agent Profiles — full profile schema
• Docker Images — pick or build an agent image
• MCP Servers — give the agent tools
• Troubleshooting — verified symptoms and fixes