Quick Start: Fast Lane

Pick a provider and follow the three steps. Each recipe ends with a running agent that has your project mounted at /workspace and its MCP tools wired up.

Example 1: Anthropic Claude

Step 1 — Initialize

heretic-cli init

Choose Anthropic (direct API), name the profile claude, accept the default image (giglabo/claude-heretic), paste your token and pick its type:

• API Key — API billing; written as ANTHROPIC_API_KEY
• OAuth Token — Claude subscription; written as CLAUDE_CODE_OAUTH_TOKEN plus deliberately empty ANTHROPIC_AUTH_TOKEN and ANTHROPIC_BASE_URL

Step 2 — Add MCP servers

From an existing JSON file (Claude, VS Code, or bare-map shape — all three are auto-detected):

heretic-cli agents mcp claude --file ./mcp.json

Or inline in the profile (~/.heretic/agents/claude.yaml):

image: giglabo/claude-heretic:latest
runner: docker
provider: anthropic
agent_type: claude

mcp:
  - name: filesystem
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"]
  - name: github
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_TOKEN: "${GH_TOKEN}"

Step 3 — Run

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

The generated config is mounted at /workspace/.mcp.json. If the project already contains a usable .mcp.json, heretic leaves it alone unless the profile sets mcp_override: true.

Example 2: GitHub Copilot CLI

Step 1 — Initialize

heretic-cli init

Choose Copilot (custom API), name the profile copilot, and give the image explicitly (there is no default for Copilot). A dedicated token is optional — without one the container uses the global Copilot token from phase 1.

Need an image? Build one:

heretic-cli image build --agent copilot     # → heretic-agent-copilot:latest

Step 2 — Point at your VS Code MCP config

# ~/.heretic/agents/copilot.yaml
image: heretic-agent-copilot:latest
runner: docker
provider: copilot
agent_type: copilot-cli

mcp_file: ${CWD}/.vscode/mcp.json
mcp_override: true

Or import the servers into the profile once:

heretic-cli agents mcp copilot --file .vscode/mcp.json

Copilot entries are converted automatically — every server gets type: "stdio" (when missing) and tools: ["*"].

Step 3 — Run

cd /path/to/your/project
heretic-cli copilot

The MCP file is mounted to both /root/.copilot/mcp-config.json and /home/agent/.copilot/mcp-config.json, so it resolves whether the container runs as root or as the agent user.

Example 3: Third-party API (ZAI / Kimi / custom)

Any Anthropic-compatible endpoint works — the wizard ships two presets.

Step 1 — Initialize

heretic-cli init

Choose Third-Party (ZAI, Kimi, or custom), then the preset:

A token is required here. You also choose whether the model configuration lands in the profile's env or in the agent's Claude settings JSON.

Step 2 — Review the profile

# ~/.heretic/agents/claude-zai.yaml
image: giglabo/claude-heretic:latest
runner: docker
provider: thirdparty
agent_type: claude

env:
  ANTHROPIC_BASE_URL: https://api.z.ai/api/anthropic
  ANTHROPIC_API_KEY: ${CLAUDE_ZAI_API_KEY}
  ANTHROPIC_MODEL: glm-4.7
  ANTHROPIC_DEFAULT_OPUS_MODEL: glm-4.7
  ANTHROPIC_DEFAULT_SONNET_MODEL: glm-4.7
  ANTHROPIC_SMALL_FAST_MODEL: glm-4.5-air
  ANTHROPIC_DEFAULT_HAIKU_MODEL: glm-4.5-air
  CLAUDE_CODE_SUBAGENT_MODEL: glm-4.5-air
  CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: "1"
  API_TIMEOUT_MS: "600000"

secrets:
  CLAUDE_ZAI_API_KEY: /home/you/.heretic/get-claude-zai-key.sh

Step 3 — Run

cd /path/to/your/project
heretic-cli claude-zai

Give the agent a build toolchain

Slim agent images have no npm, pip, mvn, go or cargo. Run the toolchain in a sibling container that shares the same workspace:

heretic-cli image build-sidecar node      # → heretic-builder-node:latest
heretic-cli run claude --sidecar node

Inside the container npm ci && npm test now works — the commands execute in the builder over HTTP, against the same files. See Sidecars.

Common operations

heretic-cli ps                     # list heretic agent containers
heretic-cli attach claude          # re-attach (Ctrl+P, Ctrl+Q to detach)
heretic-cli stop claude            # stop + remove the container and its sidecars
heretic-cli claude -s feature-x    # separate session: own ~/.claude state and container
heretic-cli claude -d              # detached
heretic-cli claude -- npm test     # run a command instead of the agent shell

Next Steps

• Commands — full command reference
• MCP Servers — transports, formats, mount paths
• Configuration — the three-layer config system
• Runners — docker, compose, custom
• Sessions — parallel agents in one project