Agent Profiles

Minimal Profile

image: giglabo/claude-heretic:latest
runner: docker

The image: field determines which Docker image runs the agent. See Docker Images for pre-built image options, customization with heretic-cli image commands, or building your own with the standalone image builder.

Full Profile

image: giglabo/claude-heretic:latest
runner: docker
agent_type: claude
provider: anthropic  # anthropic | thirdparty | copilot | kilocode
description: "Claude agent with full tooling"

# Secrets - scripts that output sensitive values (not stored in YAML)
secrets:
  ANTHROPIC_API_KEY: "~/.heretic/get-anthropic-key.sh"
  ZAI_API_KEY: "~/.heretic/get-secret.sh zai"

volumes:
  - source: "${CWD}"
    target: /workspace
    readonly: false
  - source: "${CWD}/.env"
    target: /workspace/.env
    readonly: true

env:
  # Secrets from scripts are available via ${VAR}
  ANTHROPIC_API_KEY: "${ANTHROPIC_API_KEY}"
  NODE_ENV: development

workdir: /workspace
command: ["--profile", "default"]
interactive: true
tty: true

extra:
  network: host
  ports:
    - "3000:3000"
    - "5173:5173"
  capabilities:
    - SYS_PTRACE
  privileged: false
  user: "1000:1000"
  hostname: heretic-agent
  memory: "4g"
  cpus: "2.0"
  shm_size: "2g"
  labels:
    team: platform

ssh:
  host: dev-server.example.com
  port: 22
  user: agent
  key_path: "${HOME}/.ssh/id_rsa"
  host_cwd: /home/agent/workspace

mcp_file: ~/shared/mcp-servers.json  # Load MCP servers from JSON file
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}"

mcp_override: false

git:
  token: "${GH_TOKEN}"
  author_name: "Heretic Agent"
  author_email: "[email protected]"

dind: false
claude_settings: ~/.heretic/claude-settings.json

compose:
  services:
    redis:
      image: redis:7-alpine
      ports:
        - "6379:6379"

Agent Type

The agent_type field determines agent-specific behavior:

The copilot-cli agent type mounts the MCP config to ~/.copilot/mcp-config.json (both /root/.copilot/ and /home/agent/.copilot/) since Copilot CLI reads MCP configuration from its home directory rather than the workspace.

The kilocode-cli agent type mounts the MCP config to /workspace/.kilocode/mcp.json and uses a Kilocode-specific format with alwaysAllow fields. Kilocode agents also mount config to ~/.config/kilo/ and auth data to ~/.local/share/kilo/.

SSH

Configures SSH for agents connecting to remote hosts.

Container receives: SSH_HOST, SSH_PORT, SSH_USER, SSH_KEY_PATH, SSH_HOST_CWD.

Git

Sets Git-related environment variables inside the container.

GitHub Token Injection

All containers receive GitHub tokens from global settings. Copilot tokens are only injected for provider: copilot agents.

Per-agent git.token overrides the global GH_TOKEN and GITHUB_TOKEN.

Docker-in-Docker (DinD)

When dind: true, mounts the host Docker socket into the container.

Platform-specific socket paths:

• Linux: /var/run/docker.sock
• macOS: ~/.docker/run/docker.sock or /var/run/docker.sock
• Windows: //./pipe/docker_engine

Runner Types

The runner: field controls how the CLI starts the agent container:

Quick Compose Example

runner: compose

compose:
  services:
    redis:
      image: redis:7-alpine
      ports:
        - "6379:6379"

The agent reaches Redis at redis:6379 via the shared compose network.

See Runners for the full guide: resource limits (extra: fields with types and units), generated compose YAML structure, networking between services, sidecar MCP server example, custom compose template walkthrough, and when to use each runner.

Container Onboarding

For Claude-based agents (claude, generic), the CLI automatically seeds .claude.json with { "hasCompletedOnboarding": true } to skip Claude Code's interactive login screen. The seed is created once per session and reused.

Copilot agents (copilot-cli): Session directory is mounted to ~/.copilot instead of ~/.claude. No onboarding seed is created.

Kilocode agents (kilocode-cli): No ~/.claude mount is created. Instead, configuration is mounted to ~/.config/kilo/ and auth data to ~/.local/share/kilo/. The kilo-auth.json file (containing { kilo: { type: "api", key: "<key>" } }) is created automatically if KILOCODE_API_KEY is resolved from secrets.