Managing Secrets

The problem

MCP servers and provider configs often need secret values such as API keys or tokens.

Those values should not live directly inside agentstack.yaml.

Current model

Today, the current canonical profile stores env variable names in MCP entries via env_refs, while the actual values live in the local AgentStack secrets store.

Store secret values

agentstack secrets set GITHUB_TOKEN ghp_xxxxxxxxxxxx
agentstack secrets set OPENAI_API_KEY sk-xxxxxxxxxxxx
agentstack secrets set DATABASE_URL postgresql://user:pass@host/db

Reference required env names from the profile

profile:
  mcp_servers:
    - id: github
      transport: stdio
      command: npx
      args:
        - -y
        - '@modelcontextprotocol/server-github'
      env_refs:
        - GITHUB_TOKEN
      enabled: true
    - id: database
      transport: stdio
      command: npx
      args:
        - -y
        - '@modelcontextprotocol/server-postgres'
      env_refs:
        - DATABASE_URL
      enabled: true

List stored secret names

agentstack secrets list

Only names are shown. Values are never printed.

Storage backends

Backend	Platform	Notes
`file`	all platforms	local file-backed store
`darwin-keychain`	macOS	system Keychain-backed store

agentstack secrets set GITHUB_TOKEN ghp_xxx --backend darwin-keychain

Resolution model

The current mental model should be:

the profile names required env vars
the secrets store keeps the values locally
provider materialization/runtime uses those values when needed

The safe thing to share is the profile structure and the env variable names it expects, not the secret values.

That means team docs should include:

which env vars are required
where to obtain them
which backend to use locally

Deleting secrets

agentstack secrets delete OLD_API_KEY

If a profile still expects that env ref, the related MCP or provider flow will be incomplete until you restore or replace the value.