Environment Variables

AGH reads a small core set of environment variables, injects session identity into managed agent subprocesses, and lets some extension providers use process-level overrides.

Precedence

Core Variables AGH Reads

Provider credential variables

Provider config binds launch-time credentials only when a provider uses auth_mode = "bound_secret". Each credential_slots entry names a target environment variable and resolves its value from either env:NAME or an encrypted AGH secret ref such as vault:providers/openrouter/api-key. AGH injects only the bound value into the provider subprocess.

Direct ACP providers such as Claude Code, OpenClaw, Hermes, Codex, Gemini CLI, OpenCode, Kimi CLI, Qoder, and similar CLIs use auth_mode = "native_cli" by default. The direct pi provider also uses Pi's /login and auth file by default. Wrapped API-key providers such as OpenRouter, z.ai, Moonshot/Kimi, Vercel AI Gateway, xAI, MiniMax, Mistral, and Groq default to auth_mode = "bound_secret": AGH exposes them directly, launches Pi under the hood, and injects the configured provider key.

AGH_VAULT_KEY can override the daemon-local Vault encryption key. When it is unset, AGH creates $AGH_HOME/vault.key with 0600 permissions the first time it needs to encrypt or decrypt a vault-backed secret.

Use Vault for AGH-managed encrypted values that should be written through CLI, HTTP, UDS, or web surfaces. Use env:NAME when the service manager or shell that starts the daemon should remain the source of truth for the secret value.

Automation Webhook Secrets

Config-defined webhook triggers require [[automation.triggers]].webhook_secret_ref. Use env:NAME for operator-managed environment variables or vault:automation/... for AGH-managed encrypted secrets.

Example:

[[automation.triggers]]
scope = "global"
name = "deploy-webhook"
agent = "release"
prompt = "Handle deploy webhook {{ .Kind }}."
event = "webhook"
endpoint_slug = "deploy"
webhook_secret_ref = "env:AGH_DEPLOY_WEBHOOK_SECRET"

export AGH_DEPLOY_WEBHOOK_SECRET="replace-with-secret"

Variables AGH Injects Into Agent Sessions

Managed ACP agent subprocesses start from the provider's env_policy. filtered inherits the daemon environment after removing secret-shaped variables; isolated keeps only a fixed operational allowlist. AGH then applies these changes:

Hook Subprocess Environment

Hook subprocesses do not inherit the full daemon environment. They inherit an allowlist and then apply explicit hook env values from config, AGENT.md, or SKILL.md.

Explicit hook env values override inherited values with the same key.

Bridge Provider Variables

Bridge providers are extension runtimes, not config.toml sections. These environment variables act as process-level defaults or test hooks for provider binaries.

Bridge adapter harness variables are read by bridge binaries for integration and lifecycle marker paths:

AGH_BRIDGE_ADAPTER_HANDSHAKE_PATH
AGH_BRIDGE_ADAPTER_OWNERSHIP_PATH
AGH_BRIDGE_ADAPTER_STATE_PATH
AGH_BRIDGE_ADAPTER_DELIVERY_PATH
AGH_BRIDGE_ADAPTER_INGEST_PATH
AGH_BRIDGE_ADAPTER_STARTS_PATH
AGH_BRIDGE_ADAPTER_SHUTDOWN_PATH
AGH_BRIDGE_ADAPTER_CRASH_ONCE_PATH

Not Supported As Environment Overrides

These names are common guesses or appear in older task notes, but current AGH code does not read them as runtime configuration variables.

Related Pages

• config.toml documents config fields that replace env overrides.
• File Locations documents $AGH_HOME and workspace paths.
• Bridge Overview explains bridge instances and provider runtime behavior.