> ## 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>

<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/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` | `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/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.
  </Tab>

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

    <Frame caption="Environment variable scope for separate verifier">
      <img src="https://mintcdn.com/harborframework/PxOk-gLJgMnxNtMy/images/separate-verifier-environment-variable-reach.png?fit=max&auto=format&n=PxOk-gLJgMnxNtMy&q=85&s=da3f9bc79c00d4d974fe1b00da04d5b8" 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/harborframework/PxOk-gLJgMnxNtMy/images/separate-verifier-sandbox-variables.png?fit=max&auto=format&n=PxOk-gLJgMnxNtMy&q=85&s=534a6821e7445bb80f092871ecd8f392" 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](/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 |
  | `muse-code` | `META_API_KEY` | `META_API_KEY` |
  | `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>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.