> ## Documentation Index
> Fetch the complete documentation index at: https://docs.harborframework.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Environment variables

> Control which environment variables reach Harbor, sandboxes, agents, and verifiers.

Harbor separates variables by where they are needed: the Harbor process, the
sandbox, the agent phase, or the verifier phase.

<Warning>
  Keep sandbox-provider credentials such as `DAYTONA_API_KEY` in the Harbor
  process. Passing them through `environment.env`, `--agent-env`, or
  `--verifier-env` unnecessarily exposes them inside the sandbox and is **not
  recommended**.
</Warning>

<Note>
  `export` and `--env-file` do not copy every variable into the sandbox. To pass
  a host variable such as `DATABASE_URL`, set `environment.env.DATABASE_URL` to
  `${DATABASE_URL}` explicitly.
</Note>

<Frame caption="Environment variable scope for shared verifier">
  <img src="https://mintcdn.com/harborframework/XHi-ZTogIM2NSVlh/images/environment-variable-reach.png?fit=max&auto=format&n=XHi-ZTogIM2NSVlh&q=85&s=d6366aabc26d2bf45404a82980ebd484" alt="Matrix showing which variables reach the Harbor process, agent phase, verifier phase, and lifecycle commands" width="2880" height="808" data-path="images/environment-variable-reach.png" />
</Frame>

Lifecycle commands include health checks, step setup, and collection hooks.
They run around the agent and verifier phases and receive sandbox variables only.

| Scope and availability                                      | Shell or CLI              | `config.json`     | Example           |
| ----------------------------------------------------------- | ------------------------- | ----------------- | ----------------- |
| **Harbor process** and environment provider                 | `export`, `--env-file`    | —                 | `DAYTONA_API_KEY` |
| **Shared sandbox:** agent, verifier, and lifecycle commands | —                         | `environment.env` | `DATABASE_URL`    |
| **Agent phase only**                                        | `--agent-env` (`--ae`)    | `agents[].env`    | `OPENAI_API_KEY`  |
| **Verifier phase only**                                     | `--verifier-env` (`--ve`) | `verifier.env`    | `REWARDKIT_MODEL` |

<Frame caption="Environment variable architecture for shared verifier">
  <img src="https://mintcdn.com/harborframework/XHi-ZTogIM2NSVlh/images/shared-sandbox-variables.png?fit=max&auto=format&n=XHi-ZTogIM2NSVlh&q=85&s=803471b2ac60d1db928eb879452e0c65" alt="Harbor process managing a shared sandbox with agent, verifier, and lifecycle command scopes" width="3400" height="888" data-path="images/shared-sandbox-variables.png" />
</Frame>

The agent, verifier, and lifecycle commands share one sandbox. Phase variables
are added only while their phase runs and override sandbox variables with the
same name.

Some [built-in agents](/core-concepts/agents/pre-integrated-agents) recognize
selected host variables automatically. For example, Codex reads
`OPENAI_API_KEY` from the Harbor process and makes it available during the Codex
agent phase. This behavior is agent-specific; unrelated host variables are not
forwarded.

<Accordion title="Common automatic agent credential forwarding">
  These host credentials are available only during the named agent's phase.
  Values passed with `--agent-env` take precedence.

  | Agent                                                                                                          | Recognized host credentials                                                                                                                             | Forwarded as                                                                  |
  | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
  | `codex`                                                                                                        | `OPENAI_API_KEY`                                                                                                                                        | `OPENAI_API_KEY`                                                              |
  | `claude-code`                                                                                                  | `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, or `CLAUDE_CODE_OAUTH_TOKEN`; for Bedrock, `AWS_BEARER_TOKEN_BEDROCK` or the standard AWS credential chain | `ANTHROPIC_API_KEY`, `CLAUDE_CODE_OAUTH_TOKEN`, or the original AWS variables |
  | `gemini-cli`                                                                                                   | `GEMINI_API_KEY`, `GOOGLE_API_KEY`, `GOOGLE_GENERATIVE_AI_API_KEY`, or `GOOGLE_APPLICATION_CREDENTIALS`                                                 | Google authentication variables                                               |
  | `antigravity-cli`, `antigravity-sdk`                                                                           | `GEMINI_API_KEY`; `antigravity-cli` also recognizes `GOOGLE_API_KEY`                                                                                    | `GEMINI_API_KEY`                                                              |
  | `copilot-cli`                                                                                                  | `COPILOT_GITHUB_TOKEN`, `GH_TOKEN`, or `GITHUB_TOKEN`                                                                                                   | `COPILOT_GITHUB_TOKEN`                                                        |
  | `cursor-cli`                                                                                                   | `CURSOR_API_KEY`                                                                                                                                        | `CURSOR_API_KEY`                                                              |
  | `fx`                                                                                                           | `AI_GATEWAY_API_KEY`, `VERCEL_AI_GATEWAY_API_KEY`, or `VERCEL_OIDC_TOKEN`                                                                               | Vercel AI Gateway authentication variables                                    |
  | `openhands`, `openhands-sdk`                                                                                   | `LLM_API_KEY`; `openhands` also recognizes the provider credential selected by `-m`                                                                     | `LLM_API_KEY`                                                                 |
  | `aider`, `goose`, `mcode`, `mimo`, `mini-swe-agent`, `opencode`, `pi`, `qwen-coder`, `swe-agent`, `trae-agent` | Credential for the provider selected by `-m`                                                                                                            | Integration-specific provider variables                                       |

  Provider-dependent agents use Harbor's [provider credential
  registry](https://github.com/harbor-framework/harbor/blob/main/src/harbor/agents/model_connection.py).
  ACP registry agents do not use this automatic forwarding; pass their credentials
  with `--agent-env`. Other integrations may recognize additional variables; check
  the [agent implementation](https://github.com/harbor-framework/harbor/tree/main/src/harbor/agents/installed).
</Accordion>