Environment Variables

Compozy 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 Compozy 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 Compozy secret ref such as vault:providers/openrouter/api-key. Compozy 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": Compozy exposes them directly, launches Pi under the hood, and injects the configured provider key.

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

Use Vault for Compozy-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 Compozy-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:COMPOZY_DEPLOY_WEBHOOK_SECRET"

export COMPOZY_DEPLOY_WEBHOOK_SECRET="replace-with-secret"

Variables Compozy 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. Compozy 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:

COMPOZY_BRIDGE_ADAPTER_HANDSHAKE_PATH
COMPOZY_BRIDGE_ADAPTER_OWNERSHIP_PATH
COMPOZY_BRIDGE_ADAPTER_STATE_PATH
COMPOZY_BRIDGE_ADAPTER_DELIVERY_PATH
COMPOZY_BRIDGE_ADAPTER_INGEST_PATH
COMPOZY_BRIDGE_ADAPTER_STARTS_PATH
COMPOZY_BRIDGE_ADAPTER_SHUTDOWN_PATH
COMPOZY_BRIDGE_ADAPTER_CRASH_ONCE_PATH

Not Supported As Environment Overrides

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

Related Pages

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