> ## Documentation Index
> Fetch the complete documentation index at: https://docs.iearena.org/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>

<Tabs>
  <Tab title="Shared verifier (default)">
    The agent and verifier run in the same sandbox.

    <Frame caption="Environment variable scope for shared verifier">
      <img src="https://mintcdn.com/kobe/OSe7L7bEu6_nxCal/images/environment-variable-reach.png?fit=max&auto=format&n=OSe7L7bEu6_nxCal&q=85&s=9c91dc46eb96047dec7fd04f053c22ad" 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`     | `task.toml`         | Example           |
    | ----------------------------------------------------------- | ------------------------- | ----------------- | ------------------- | ----------------- |
    | **Harbor process** and environment provider                 | `export`, `--env-file`    | —                 | —                   | `DAYTONA_API_KEY` |
    | **Shared sandbox:** agent, verifier, and lifecycle commands | —                         | `environment.env` | `[environment.env]` | `DATABASE_URL`    |
    | **Agent phase only**                                        | `--agent-env` (`--ae`)    | `agents[].env`    | —                   | `OPENAI_API_KEY`  |
    | **Verifier phase only**                                     | `--verifier-env` (`--ve`) | `verifier.env`    | `[verifier.env]`    | `REWARDKIT_MODEL` |

    <Frame caption="Environment variable architecture for shared verifier">
      <img src="https://mintcdn.com/kobe/OSe7L7bEu6_nxCal/images/shared-sandbox-variables.png?fit=max&auto=format&n=OSe7L7bEu6_nxCal&q=85&s=043b7f44f135892aa93dc0641363b9a6" 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.
  </Tab>

  <Tab title="Separate verifier">
    A [separate verifier](/core-concepts/tasks/separate-verifier) runs in a
    second sandbox. Agent-phase variables do not reach it; only
    [collected artifacts](/core-concepts/jobs/artifact-collection) cross from
    the agent sandbox.

    <Frame caption="Environment variable scope for separate verifier">
      <img src="https://mintcdn.com/kobe/hMo3JvbD1t0mu61m/images/separate-verifier-environment-variable-reach.png?fit=max&auto=format&n=hMo3JvbD1t0mu61m&q=85&s=c8168b7e788770c0973c5ea5eb682867" alt="Matrix showing which variables reach the Harbor process, agent sandbox, verifier sandbox, phases, and lifecycle commands" width="3480" height="808" data-path="images/separate-verifier-environment-variable-reach.png" />
    </Frame>

    `verifier.environment.env` sets baseline variables for the verifier sandbox,
    including its lifecycle commands. `verifier.env` adds variables only during
    the verifier phase.

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

    <Frame caption="Environment variable architecture for separate verifier">
      <img src="https://mintcdn.com/kobe/hMo3JvbD1t0mu61m/images/separate-verifier-sandbox-variables.png?fit=max&auto=format&n=hMo3JvbD1t0mu61m&q=85&s=6ff698b4dc15bffcecc077fdac83fc78" alt="Harbor process managing separate agent and verifier sandboxes with their phase and lifecycle command scopes" width="3480" height="1424" data-path="images/separate-verifier-sandbox-variables.png" />
    </Frame>

    <Note>
      If separate mode is enabled without `[verifier.environment]`, Harbor
      copies the top-level `[environment]`. Its `[environment.env]` variables
      therefore become the verifier sandbox baseline as well.
    </Note>

    Verifier-phase variables override verifier-sandbox variables with the same
    name. Agent-phase variables follow the same rule in the agent sandbox.
  </Tab>
</Tabs>

## Automatic agent credential forwarding

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>