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.

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.

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.

Shared verifier (default)

The agent and verifier run in the same sandbox.

Environment variable scope for shared verifier

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

Environment variable architecture for shared verifier

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.

Separate verifier

A separate verifier runs in a second sandbox. Agent-phase variables do not reach it; only collected artifacts cross from the agent sandbox.

Environment variable scope for separate verifier

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

Environment variable architecture for separate verifier

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.

Verifier-phase variables override verifier-sandbox variables with the same name. Agent-phase variables follow the same rule in the agent sandbox.

Automatic agent credential forwarding

Some built-in 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.

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