Skip to main content
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.
Matrix showing which variables reach the Harbor process, agent phase, verifier phase, and lifecycle commands

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.
Harbor process managing a shared sandbox with agent, verifier, and lifecycle command scopes

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. 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.
These host credentials are available only during the named agent’s phase. Values passed with --agent-env take precedence.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.