---
title: "Quick Start: Fast Lane"
description: "Get your first AI agent running in minutes — working recipes for Anthropic Claude, GitHub Copilot, and third-party APIs (ZAI, Kimi) with MCP servers and build sidecars"
canonical: https://giglabo.com/heretic/docs/heretic-cli/quick-start
locale: en
---

# Quick Start: Fast Lane

> Markdown twin of https://giglabo.com/heretic/docs/heretic-cli/quick-start
> 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

Get your first AI agent running in minutes — working recipes for Anthropic Claude, GitHub Copilot, and third-party APIs (ZAI, Kimi) with MCP servers and build sidecars

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.

> **Note: Prerequisites**
>
> Docker must be running and the `docker` CLI must be on your `PATH`. Install heretic-cli first — see [Installation](https://giglabo.com/heretic/docs/heretic-cli/installation).

---

## Example 1: Anthropic Claude

### Step 1 — Initialize

```bash
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):

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

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

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

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

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

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

### Step 2 — Point at your VS Code MCP config

```yaml
# ~/.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:

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

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

> **Note: Copilot tokens**
>
> `GH_COPILOT_TOKEN` and `GITHUB_COPILOT_TOKEN` are only injected into profiles with `provider: copilot`. If the field is missing, the provider is inferred from `agent_type: copilot-cli`.

---

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

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

### Step 1 — Initialize

```bash
heretic-cli init
```

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

| Preset | Base URL | Model | Small / fast model |
|--------|----------|-------|--------------------|
| `zai` | `https://api.z.ai/api/anthropic` | `glm-4.7` | `glm-4.5-air` |
| `kimi` | `https://api.moonshot.ai/anthropic` | `kimi-k2.5` | `kimi-k2.5` |
| `custom` | your own URL | your own | your own |

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

```yaml
# ~/.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

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

```bash
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](https://giglabo.com/heretic/docs/heretic-cli/configuration/sidecars).

## Common operations

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

> **Warning: Pass commands after --**
>
> In the shorthand form (`heretic-cli claude …`) trailing words are not treated as a command: use `heretic-cli claude -- npm test`, or the explicit `heretic-cli run claude npm test`.

## Next Steps

- [Commands](https://giglabo.com/heretic/docs/heretic-cli/commands) — full command reference
- [MCP Servers](https://giglabo.com/heretic/docs/heretic-cli/configuration/mcp-servers) — transports, formats, mount paths
- [Configuration](https://giglabo.com/heretic/docs/heretic-cli/configuration) — the three-layer config system
- [Runners](https://giglabo.com/heretic/docs/heretic-cli/configuration/runners) — docker, compose, custom
- [Sessions](https://giglabo.com/heretic/docs/heretic-cli/configuration/sessions) — parallel agents in one project

## Related

- HTML version of this page: https://giglabo.com/heretic/docs/heretic-cli/quick-start
- Site map for agents: https://giglabo.com/llms.txt