heretic-cli

heretic-cli

Command-line interface for managing containerized AI coding agents with layered configuration, secure secrets, build sidecars, and multi-provider support

heretic-cli runs AI coding agents (Claude Code, GitHub Copilot CLI, OpenCode, Gemini CLI) inside Docker containers on your own machine or server. It manages the agent profiles, the images they run in, the secrets they need, the MCP servers they talk to, and the sibling containers that carry build toolchains.

It is a single native executable built with Bun and TypeScript — no runtime dependency tree, no daemon of its own.

CLI-First Approach

All agent configuration is done through CLI commands. The CLI creates and manages:

  • Secret scripts — small executables that print API tokens on demand, so no token is ever written into YAML
  • Claude settings — Claude Code permissions and model configuration per agent
  • Agent profiles — the full container definition (image, volumes, env, MCP, runner)

Never edit generated config by hand

Use heretic-cli init, heretic-cli agents edit and heretic-cli local-init for all changes. Hand-edited files are not validated until you run heretic-cli agents validate or heretic-cli local-validate.

Key Features

  • Multi-provider support — Anthropic (API key or OAuth subscription), third-party Anthropic-compatible APIs (ZAI, Kimi, or any custom base URL), and GitHub Copilot
  • Layered configuration — global profile → per-project override → CLI flags, with ${VAR} interpolation
  • Secure secrets — token values come from scripts, environment references, or literals, resolved at run time
  • MCP integration — inline servers, external JSON files, and auto-detection of the three common MCP JSON shapes
  • Sessions — several isolated instances of the same agent in the same project
  • Build sidecars — keep npm, pip, mvn, go, cargo out of the agent image and run them in sibling containers over HTTP, or on a remote host over SSH
  • Image builder — generate and build agent images and builder images from templates, single- or multi-arch
  • Cross-platform — Linux, macOS and Windows

Commands at a Glance

CommandWhat it does
initInteractive global setup: GitHub tokens and agent profiles
agentsProfile CRUD: list, add, edit, show, validate, delete, mcp
local-initCreate a per-project override for a profile (or a compose.yaml template)
local-validateResolve and validate the project's local configs
runStart an agent container (also reachable as heretic-cli <profile>)
ps / stop / attachInspect, stop and re-attach to running agents
imageBuild agent images, builder (sidecar) images, or print generated templates
doctorEnvironment health checks
updateSelf-update from the latest GitHub release

Quick Overview

# 1. Global setup: tokens + first agent profile
heretic-cli init

# 2. Per-project overrides (optional but recommended)
cd ~/code/my-project
heretic-cli local-init claude

# 3. Run the agent in this directory
heretic-cli run claude          # or: heretic-cli claude

Next Steps