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

Source	Applies to	Precedence
Process environment	All AGH commands and daemon startup.	Base environment.
`<workspace>/.env`	Config loads that include a workspace root.	Loaded before `$AGH_HOME` is resolved. Does not override variables already set by the process loader.
`config.toml`	Runtime config values.	Used for AGH config. There is no `AGH_CONFIG` or `AGH_LOG_LEVEL` override today.
Managed session env injection	Agent subprocesses.	Starts from daemon environment, sets AGH session variables, sets `AGH_BIN`, and prepends the daemon binary directory to `PATH`.
Hook subprocess env	Hook subprocesses.	Starts from an allowlist of parent env vars, then applies hook `env` overrides.

Core Variables AGH Reads

Variable	Type	Default	Valid values	Description
`AGH_HOME`	path	`~/.agh`	Non-empty path.	Overrides the global AGH home directory. If a workspace `.env` sets it, that value can affect config loading for that workspace before home paths are resolved.
`HOME`	path	OS user home	Existing user home path.	Used to resolve the user AgentSkills directory at `$HOME/.agents/skills` when that source is enabled.
`AGH_DEV_VERIFY_BOUNDARIES`	boolean string	unset	`1`, `true`, or `yes` enable boundary verification.	Development-only daemon boundary import verification toggle.
`GITHUB_TOKEN`	token string	unset	Non-empty token.	Used by the GitHub registry client for private repositories and higher rate limits.

Provider config binds launch-time credentials through credential_slots. Each slot 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.

Variable	Default provider	Default	Valid values	Description
`ANTHROPIC_API_KEY`	`claude`, `pi`	unset	Provider-specific token.	Anthropic-compatible API key target.
`OPENAI_API_KEY`	`codex`	unset	Provider-specific token.	OpenAI API key target.
`GEMINI_API_KEY`	`gemini`	unset	Provider-specific token.	Gemini API key target.
`BLACKBOX_API_KEY`	`blackbox`	unset	Provider-specific token.	BLACKBOX AI key target.
`KIMI_API_KEY`	`kimi-cli`, `moonshot`	unset	Provider-specific token.	Kimi CLI and Moonshot/Kimi API key target.
`QODER_PERSONAL_ACCESS_TOKEN`	`qoder`	unset	Provider-specific token.	Qoder CLI personal access token target.
`OPENROUTER_API_KEY`	`openrouter`	unset	Provider-specific token.	OpenRouter API key target for the Pi harness.
`ZAI_API_KEY`	`zai`	unset	Provider-specific token.	z.ai API key target for the Pi harness.
`AI_GATEWAY_API_KEY`	`vercel-ai-gateway`	unset	Provider-specific token.	Vercel AI Gateway API key target for the Pi harness.
`XAI_API_KEY`	`xai`	unset	Provider-specific token.	xAI API key target for the Pi harness.
`MINIMAX_API_KEY`	`minimax`	unset	Provider-specific token.	MiniMax API key target for the Pi harness.
`MISTRAL_API_KEY`	`mistral`	unset	Provider-specific token.	Mistral API key target for the Pi harness.
`GROQ_API_KEY`	`groq`	unset	Provider-specific token.	Groq API key target for the Pi harness.

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.

Variable named by `env:` ref	Type	Default	Valid values	Description
`AGH_DEPLOY_WEBHOOK_SECRET` example	string	none	Must exist and be non-empty when the ref is resolved.	Secret used to validate config-defined automation webhooks.

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 inherit the daemon environment. AGH then applies these changes:

Variable	Type	Default	Valid values	Description
`AGH_SESSION_ID`	string	set for every managed session	Session ID.	Injected into the agent process and read by `agh whoami`.
`AGH_AGENT`	string	resolved agent name	Agent name.	Injected for agent identity metadata.
`AGH_AGENT_NAME`	string	resolved agent name	Agent name.	Injected for agent identity metadata.
`AGH_PROVIDER`	string	resolved provider id	Provider id.	Injected for provider-aware tools and diagnostics.
`AGH_PROVIDER_HARNESS`	string	resolved provider harness	`acp`, `pi_acp`.	Injected for provider-aware tools and diagnostics.
`AGH_MODEL`	string	resolved model	Provider model string.	Injected for provider-aware tools and diagnostics.
`PI_CODING_AGENT_DIR`	path	set only for `pi_acp` providers	Session-local directory.	Points Pi at the isolated `settings.json` and `models.json` materialized by AGH.
`AGH_SESSION_CHANNEL`	string	unset unless the session has a network channel	Network channel name.	Injected for channel sessions. Stale values are removed for non-channel sessions.
`AGH_PEER_ID`	string	unset unless the session has a network channel	`<agent-name>.<session-id>`	Injected for channel sessions. Stale values are removed for non-channel sessions.
`AGH_BIN`	absolute path	current AGH executable	Existing executable path.	Injected into ACP provider subprocesses so agents can call the same AGH binary.
`PATH`	path list	inherited	Path list for the operating system.	The directory containing `AGH_BIN` is prepended and duplicate entries are removed.

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.

Variable	Type	Default	Valid values	Description
`COMSPEC`	string	inherited if set	Any string.	Windows command processor environment.
`HOME`	path	inherited if set	Path.	User home.
`LANG`	string	inherited if set	Locale string.	Locale.
`LC_ALL`	string	inherited if set	Locale string.	Locale override.
`LC_CTYPE`	string	inherited if set	Locale string.	Character classification locale.
`LOGNAME`	string	inherited if set	User name.	Login name.
`PATH`	path list	inherited if set	Path list.	Executable lookup path for hook commands.
`PATHEXT`	string	inherited if set	Windows extension list.	Windows executable extension lookup.
`SHELL`	path	inherited if set	Shell path.	User shell.
`SYSTEMROOT`	path	inherited if set	Windows system root.	Windows system root.
`TEMP`	path	inherited if set	Path.	Temporary directory.
`TERM`	string	inherited if set	Terminal type.	Terminal metadata.
`TMP`	path	inherited if set	Path.	Temporary directory.
`TMPDIR`	path	inherited if set	Path.	Temporary directory.
`USER`	string	inherited if set	User name.	User account.
`USERPROFILE`	path	inherited if set	Windows profile path.	Windows user profile.

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.

Variable	Provider	Default	Valid values	Description
`AGH_BRIDGE_DISCORD_LISTEN_ADDR`	Discord	provider config value	Host and port string.	Default Discord webhook listener address.
`AGH_BRIDGE_DISCORD_API_BASE_URL`	Discord	Discord API default	URL.	Discord API base URL override.
`AGH_BRIDGE_GITHUB_LISTEN_ADDR`	GitHub	provider config value	Host and port string.	Default GitHub webhook listener address.
`AGH_BRIDGE_GITHUB_API_BASE_URL`	GitHub	GitHub API default	URL.	GitHub API base URL override.
`AGH_BRIDGE_GCHAT_LISTEN_ADDR`	Google Chat	provider config value	Host and port string.	Default Google Chat webhook listener address.
`AGH_BRIDGE_GCHAT_API_BASE_URL`	Google Chat	Google Chat API default	URL.	Google Chat API base URL override.
`AGH_BRIDGE_GCHAT_AUTH_URL`	Google Chat	Google OAuth token URL	URL.	Google Chat auth endpoint override.
`AGH_BRIDGE_GCHAT_DIRECT_CERTS_URL`	Google Chat	Google direct-message cert URL	URL.	Direct-message certificate URL override.
`AGH_BRIDGE_GCHAT_PUBSUB_CERTS_URL`	Google Chat	Google Pub/Sub cert URL	URL.	Pub/Sub certificate URL override.
`AGH_BRIDGE_LINEAR_LISTEN_ADDR`	Linear	provider config value	Host and port string.	Default Linear webhook listener address.
`AGH_BRIDGE_LINEAR_API_BASE_URL`	Linear	Linear API default	URL.	Linear API base URL override.
`AGH_BRIDGE_LINEAR_TOKEN_URL`	Linear	Linear OAuth token URL	URL.	Linear OAuth token endpoint override.
`AGH_BRIDGE_SLACK_LISTEN_ADDR`	Slack	provider config value	Host and port string.	Default Slack webhook listener address.
`AGH_BRIDGE_SLACK_API_BASE_URL`	Slack	Slack API default	URL.	Slack API base URL override.
`AGH_BRIDGE_TEAMS_LISTEN_ADDR`	Teams	provider config value	Host and port string.	Default Teams webhook listener address.
`AGH_BRIDGE_TEAMS_OPENID_METADATA_URL`	Teams	Microsoft OpenID metadata URL	URL.	Teams OpenID metadata endpoint override.
`AGH_BRIDGE_TEAMS_TOKEN_URL`	Teams	Microsoft OAuth token URL	URL.	Teams OAuth token endpoint override.
`AGH_BRIDGE_TELEGRAM_LISTEN_ADDR`	Telegram	provider config value	Host and port string.	Default Telegram webhook listener address.
`AGH_BRIDGE_TELEGRAM_API_BASE_URL`	Telegram	Telegram API default	URL.	Telegram API base URL override.
`AGH_BRIDGE_WHATSAPP_LISTEN_ADDR`	WhatsApp	provider config value	Host and port string.	Default WhatsApp webhook listener address.
`AGH_BRIDGE_WHATSAPP_API_BASE_URL`	WhatsApp	WhatsApp API default	URL.	WhatsApp API base URL override.

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.

Variable	Status	Use instead
`AGH_CONFIG`	Not read.	Put global config at `$AGH_HOME/config.toml` and workspace config at `<workspace>/.agh/config.toml`.
`AGH_LOG_LEVEL`	Not read.	Set `[log].level` in `config.toml`.
`VITE_AGH_API_URL`	Not read by AGH runtime code.	It is listed as a Turbo build cache input, not a daemon config variable.

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.