Secrets

Agent profiles give the child process opaque placeholders instead of real secret values. The Agent Proxy exchanges a placeholder only when the request matches the binding's configured destination policy.

Configure a secret source

Remote secret bindings use the [secrets] table to select a Stashbase project and environment:

[secrets]
project = "project"
environment = "environment"

[secrets.GH_TOKEN]
source_name = "GITHUB_TOKEN"
hosts = ["api.github.com"]

The binding name (GH_TOKEN) is the placeholder exposed to the child. source_name selects the Stashbase secret (GITHUB_TOKEN). Without source_name, the binding name is also used as the source name.

Local files and overrides

Set secrets.file to read configured source names from a dotenv, YAML, or JSON file. A file-only profile does not require a Stashbase API key:

[secrets]
file = ".env.local"

[secrets.GH_TOKEN]
hosts = ["api.github.com"]

When both a local file and a remote project/environment are configured, file values take precedence. Stashbase fetches only sources missing from the file. Never place secret values or API keys in an untrusted file.

Child variables and headers

Use env when a tool expects a different environment variable name. Use header for providers that do not accept Authorization: Bearer <placeholder>:

[secrets.TOOL_TOKEN]
env = "TOOL_API_KEY"
header = "x-api-key"
hosts = ["api.example.com"]

Some clients validate token shape before sending a request. placeholder can provide an opaque, format-compatible value; it never contains the real credential.

Next steps

• Credential rules for method- and path-level injection policies
• Personal Credentials for account-owned credentials
• Profile configuration for the complete profile reference