Extension Secret Bindings

This page helps you provide credentials to an extension without putting plaintext in its manifest, command history, logs, or API responses. A binding connects one declared environment name to a Vault reference for exactly one extension instance: the global published instance or one workspace dev overlay.

Declare the names

List required names in the manifest. CompozyOS reports names through requires_env, missing_env, and bound_env_keys; it never returns the values.

[extension]
name = "incident-review"
version = "1.0.0"
min_compozy_version = "0.3.0-beta.1"
requires_env = ["PAGER_TOKEN", "REGION"]

Bindings do not make install active and missing values do not block enable. They affect subprocess launch only when the current manifest still declares the name.

Set a value from hidden input

For an interactive terminal, omit --value-stdin and enter the value at the hidden prompt:

compozy extension secrets set incident-review --env PAGER_TOKEN

For automation, send the value on stdin. Never place it in argv:

printf '%s' "$PAGER_TOKEN" | \
  compozy extension secrets set incident-review --env PAGER_TOKEN --value-stdin -o json

Use --workspace <workspace> to target a workspace dev overlay. Without it, the command targets the global published instance.

Bind an existing Vault ref

An existing reference must use the extension Vault namespace and match the target instance:

compozy extension secrets bind incident-review \
  --env PAGER_TOKEN \
  --vault-ref vault:extensions/global/incident-review/env/PAGER_TOKEN

Global refs use vault:extensions/global/...; workspace refs use vault:extensions/ws/<workspace>/.... CompozyOS rejects a missing ref, a namespace mismatch, or a ref owned by another instance.

Bind a remote MCP header

For a remote MCP server declared by the extension, bind the same write-only value to one request header:

compozy extension secrets bind incident-review \
  --env PAGER_TOKEN \
  --vault-ref vault:extensions/global/incident-review/env/PAGER_TOKEN \
  --remote-header deployment-api:Authorization

The server must exist in resources.mcp_servers, use the native http transport, and accept the named header under the remote-header policy. For Agent Plugins packages, a type: "streamable-http" server is normalized to that transport during ingestion. Sensitive header values declared in a portable package are skipped; this operator binding is the credential path.

Inspect presence and remove bindings

compozy extension secrets list incident-review -o json
compozy extension secrets unset incident-review --env PAGER_TOKEN -o json

List responses contain declared names, bound names, stale status, and optional remote server/header names. They never contain Vault refs or secret values. Unset removes the binding and deletes an unreferenced managed extension_env Vault value; it does not delete a shared or differently owned ref.

Bindings survive updates under the same managed identity. When an update removes a name from requires_env, the stale binding remains visible for cleanup but is not injected into the process.

Related

• Install and operate extensions
• Extension manifest
• Agent Plugins interoperability
• Extension secrets CLI
• Vault configuration