Troubleshooting

First moves

heretic-cli doctor                       # environment health
heretic-cli agents validate <name>       # profile shape
heretic-cli local-validate <name>        # resolved config (runs secret scripts)
heretic-cli -V run <name>                # verbose start-up
heretic-cli --log-file ./heretic.log -V run <name>

Configuration errors

Docker problems

Secrets

Inspect what would actually be used:

heretic-cli agents show <name> --resolved            # masked
heretic-cli agents show <name> --resolved --reveal   # plaintext, be careful

Agent behaviour

Claude Code shows the login screen. The onboarding seed lives in the session directory. Reset it:

rm -rf .heretic/temp/default/
heretic-cli run claude

Copilot tokens missing inside the container. Copilot tokens are only injected for provider: copilot. Set the field explicitly — when it is absent the provider is inferred from agent_type (copilot-cli → copilot, everything else → anthropic).

A model or auth variable behaves unexpectedly. OAuth mode deliberately sets ANTHROPIC_AUTH_TOKEN: "" and ANTHROPIC_BASE_URL: ""; those empty values are preserved on purpose, while any other empty value is removed. ANTHROPIC_API_KEY is rewritten into ANTHROPIC_AUTH_TOKEN and ANTHROPIC_AUTH_KEY. See Environment Variables.

Settings changes have no effect. The container reads the merged settings written into the session directory. Check the merge inputs: the profile's claude_settings file and .heretic/cli/claude-settings.json.

MCP

docker exec <container> cat /workspace/.mcp.json
cat .heretic/temp/default/.mcp.json

Build sidecars

# 1. is the wiring there?
docker exec <container> printenv BUILD_SIDECARS

# 2. which commands were wrapped?
docker exec <container> ls /opt/sidecar/wrappers/

# 3. is the builder healthy and reachable?
docker ps --filter label=heretic.role=build-sidecar
docker exec <container> curl -s http://builder-node:8080/health

# 4. test the client directly
docker exec <container> /opt/sidecar/sidecar-exec node npm --version

# 5. builder logs
docker logs heretic-builder-node-default-1a2b3c4d

SSH backend

docker exec <container> env | grep SSH_
docker exec <container> ls -la /home/agent/.ssh/id_rsa
docker exec <container> /opt/sidecar/ssh-exec npm --version
docker exec <container> ssh -vvv -o StrictHostKeyChecking=no \
    -p "${SSH_PORT:-22}" "${SSH_USER:-agent}@${SSH_HOST}" 'echo connected'

Root mode

Containers and sessions

heretic-cli stop with no argument matches heretic.project against the current directory exactly — from a subdirectory or a symlinked path it finds nothing, so pass the agent or container name instead.

Self-update

Known issues in 0.1.0

• doctor does not validate global profiles. Checks 6, 8 and 10 report 0 profile(s) validated, always find all images "available", and never check global volume paths. Use agents validate and local-validate instead.
• A fresh local-init template breaks run. The generated file is all comments and parses to null; uncomment a key or delete the file.
• ps UPTIME is container age, not time since the last start.
• The compose runner's isRunning() expects a JSON array from docker compose ps --format json; newer Compose versions emit newline-delimited JSON and the check reports "not running". heretic-cli ps (label-based) is unaffected.

Diagnostic bundle for a bug report

heretic-cli -v
heretic-cli --log-file ./doctor.log doctor
heretic-cli --log-file ./run.log -V run <agent> -d
heretic-cli ps --json > ps.json
heretic-cli agents show <agent> --resolved > resolved.yaml   # masked, safe to share
docker version > docker.txt

Next Steps

• doctor — what each check means
• Validation — every error message
• Environment Variables — what the container receives