---
title: Environment Variables
description: "Every environment variable heretic-cli reads on the host, injects into the agent container, bakes into its images, and uses for the tool-execution backends — with sources, defaults and transformations"
canonical: https://giglabo.com/ru/heretic/docs/heretic-cli/reference/environment-variables
locale: ru
---

# Environment Variables

> Markdown twin of https://giglabo.com/ru/heretic/docs/heretic-cli/reference/environment-variables
> Site structure and the full page list for agents: https://giglabo.com/llms.txt
> This page has no `ru` translation yet; the content below is the `en` original, which is what the HTML page also serves.

Every environment variable heretic-cli reads on the host, injects into the agent container, bakes into its images, and uses for the tool-execution backends — with sources, defaults and transformations

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 |

> **Warning: 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 |

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

> **Warning: 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

```bash
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](https://giglabo.com/ru/heretic/docs/heretic-cli/configuration/agent-profiles) — where these values are declared
- [Secrets](https://giglabo.com/ru/heretic/docs/heretic-cli/configuration/secrets) — how values are resolved
- [Sidecars](https://giglabo.com/ru/heretic/docs/heretic-cli/configuration/sidecars) — the backend contract
- [image](https://giglabo.com/ru/heretic/docs/heretic-cli/commands/image) — the image-level defaults

## Related

- HTML version of this page: https://giglabo.com/ru/heretic/docs/heretic-cli/reference/environment-variables
- Site map for agents: https://giglabo.com/llms.txt