Environment Variables | VibeCoder Heretic

Four different environments are involved: your shell, the agent container, the agent images, and the build sidecars. This page lists all four.

1. Read on the host by the CLI

Variable	Used for
any variable	`${VAR}` interpolation in profiles and overrides, and `$VAR` references in `secrets:`
`HOME`	`${HOME}`, the location of `~/.heretic`, and the macOS Docker socket probe
`EDITOR`, then `VISUAL`	`agents edit --editor` and the `agents mcp` paste prompt (falls back to `vi`)
`TMPDIR`	temporary files for `agents edit --editor` and image builds
`DOCKER_HOST`	honoured by the Docker client and by the `docker` CLI heretic shells out to; without it the platform default socket is used
`PATH`	finding `docker` — required for `attach`, `docker compose` and image builds

There is no environment variable for the log level: use -V/--verbose and --log-file.

2. Injected into the agent container

Assembled in this order, so later entries can overwrite earlier ones: resolved secrets → profile env → transformations → token injection → git.* → root mode → sidecars → SSH.

Tokens

Variable	Source	Applies to
`GH_TOKEN`, `GITHUB_TOKEN`	`~/.heretic/settings.yaml` → `github.token`, overridden by the profile's `git.token`	every agent
`GH_COPILOT_TOKEN`, `GITHUB_COPILOT_TOKEN`	`github.copilot_token`, falling back to `github.token`	`provider: copilot` only

Git identity

Variable	Source
`GIT_AUTHOR_NAME`	`git.author_name`
`GIT_AUTHOR_EMAIL`	`git.author_email`

Anthropic and provider variables

These come from your profile — heretic-cli init writes them for you.

Variable	Meaning
`ANTHROPIC_API_KEY`	API-key mode. The docker runner rewrites it into `ANTHROPIC_AUTH_TOKEN` and `ANTHROPIC_AUTH_KEY`, dropping the original name
`CLAUDE_CODE_OAUTH_TOKEN`	subscription mode
`ANTHROPIC_AUTH_TOKEN: ""`, `ANTHROPIC_BASE_URL: ""`	written deliberately empty in OAuth mode to prevent an API-mode fallback
`ANTHROPIC_BASE_URL`	third-party endpoint, e.g. `https://api.z.ai/api/anthropic`
`ANTHROPIC_MODEL`, `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`	primary model
`ANTHROPIC_SMALL_FAST_MODEL`, `ANTHROPIC_DEFAULT_HAIKU_MODEL`, `CLAUDE_CODE_SUBAGENT_MODEL`	small / fast model
`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`	`1` in the third-party presets
`API_TIMEOUT_MS`	`600000` in the third-party presets

Empty values are stripped — with one deliberate exception

Any variable that resolves to an empty string is removed so it cannot shadow an image default. A key written explicitly as "" in env is kept, which is exactly how OAuth mode disables the API fallback.

Heretic's own variables

Variable	Set when	Value
`HERETIC_RUN_AS_ROOT`	`extra.run_as_root: true` or `--root`	`1` — the entrypoint then exports `HOME=/home/agent` and `USER=root`
`BUILD_SIDECARS`	build sidecars configured	`{"<runtime>":{"internal_url":"http://builder-<runtime>:<port>"}}`
`SIDECAR_ENV_PASSTHROUGH`	build sidecars configured	comma-separated union of every sidecar's `env_passthrough`
`SSH_HOST`, `SSH_PORT`, `SSH_USER`, `SSH_KEY_PATH`, `SSH_HOST_CWD`	an `ssh:` block is present	`SSH_KEY_PATH` carries the host path; the key itself is mounted at `/home/agent/.ssh/id_rsa`

Variable names are logged at info level; values only at debug level and masked.

3. Baked into the agent images

heretic-cli image build sets these defaults so the image also works outside heretic-cli run — in CI or an orchestrator.

Variable	Default	Meaning
`AGENT_TYPE`	the built agent, or `combined`	which CLI the entrypoint starts
`PROMPT_FILE`	`""`	empty → interactive mode; set → workflow mode
`REPO_PATH`	`/workspace`	directory the agent runs in, in workflow mode
`AGENT_ARGS`	`""`	extra CLI arguments; `file:<path>` is replaced by that file's contents, `exec:<cmd>` by the command's output
`AGENT_OUTPUT_FORMAT`	`stream-json`	Claude's `--output-format` in workflow mode
`API_TIMEOUT_MS`	`3000000`	image-level default, overridden by the profile
`GH_TOKEN`	`""`	placeholder; workflow mode configures git credentials from it (or `GITHUB_TOKEN`)
`TASK_ID`, `STEP_NAME`	`""`	free-form identifiers for orchestrators
`HERETIC_DIR`	unset → `/workspace/.heretic`	where workflow mode looks for `claude-settings.json` / `opencode.json`
`PATH`	includes `/opt/sidecar/wrappers` first	so generated tool wrappers take effect

docker run -it --rm \
  -e PROMPT_FILE=/workspace/prompt.md \
  -e REPO_PATH=/workspace \
  -e AGENT_OUTPUT_FORMAT=stream-json \
  -v "$(pwd)":/workspace \
  heretic-agent:latest

4. Tool-execution backends

`sidecar-exec` (inside the agent)

Variable	Default	Meaning
`BUILD_SIDECARS`	—	required; the routing table injected by heretic
`SIDECAR_TIMEOUT`	`600`	seconds sent to the builder; the transport deadline is this plus 30
`SIDECAR_CWD`	current directory	working directory sent with the request
`SIDECAR_STREAM`	unset	`1` streams output over SSE instead of buffering
`SIDECAR_ENV_PASSTHROUGH`	—	comma-separated allowlist of variables forwarded per command

`ssh-exec` (inside the agent)

Uses SSH_HOST (required), SSH_PORT (22), SSH_USER (agent), SSH_KEY_PATH (falls back to /home/agent/.ssh/id_rsa), SSH_HOST_CWD (current directory).

`exec-server` (inside a builder)

Variable	Default	Meaning
`EXEC_SERVER_PORT`	`8080`	listening port; `-port` overrides it
`EXEC_SERVER_CWD`	`/workspace`	working directory for commands
`EXEC_SERVER_RUNTIME`	the built runtime	reported by `/info`
`EXEC_SERVER_TOKEN`	unset	when set, every endpoint except `/health` requires `Authorization: Bearer …`

env_passthrough is an allowlist for a reason

The agent container holds ANTHROPIC_API_KEY, GH_TOKEN and similar. Only names listed in a sidecar's env_passthrough are forwarded into builds — for example env_passthrough: ["NPM_TOKEN"].

Inspecting what a container actually got

heretic-cli agents show <name> --resolved      # planned env, sensitive values masked
heretic-cli local-validate <name>              # complete resolved config (plaintext secrets)
docker exec <container> printenv | sort
docker exec <container> printenv BUILD_SIDECARS
docker inspect <container> --format '{{json .Config.Env}}'

Next Steps

Agent Profiles — where these values are declared
Secrets — how values are resolved
Sidecars — the backend contract
image — the image-level defaults