Secrets

AgentBreeder treats secrets as a first-class workspace resource. Each developer (or team workspace) chooses one secrets backend, sets values once, and agentbreeder deploy mirrors the values it needs into the target cloud's native secrets manager — granting the agent's runtime identity read access to only the secrets it declares. Auto-mirror is shipped for GCP Cloud Run and Azure Container Apps today; AWS auto-mirror is on the roadmap (see Auto-mirror at deploy below).

You never embed a secret value in agent.yaml. You reference it by name:

deploy:
  cloud: gcp
  secrets:
    - OPENAI_API_KEY
    - ZENDESK_API_TOKEN

At deploy time, on GCP Cloud Run and Azure Container Apps (the targets where auto-mirror ships today), AgentBreeder reads OPENAI_API_KEY and ZENDESK_API_TOKEN from your workspace backend, mirrors each into the cloud's secret store (GCP Secret Manager / Azure Key Vault) under the deterministic name agentbreeder/<agent-name>/<secret-name>, and wires the running container's env to a secret reference. The value never lands on disk in the deploy bundle and never appears in CI logs. For AWS targets today, pre-create the secrets in AWS Secrets Manager and reference them by name in deploy.secrets: — see the auto-mirror availability notes below.

Workspace backends

A workspace is the unit that owns a set of secrets. The default workspace config lives at ~/.agentbreeder/workspace.yaml:

workspace: default
secrets:
  backend: keychain          # env | keychain | aws | gcp | azure | vault
  options:
    # region: us-east-1      # for aws
    # project_id: my-proj    # for gcp
    # mount: secret          # for vault

Note: in v2.0 the only workspace key the engine reads is secrets:. The full workspace primitive (agentbreeder workspace init, multi-cloud config, per-workspace gateway block) is tracked at #146 and lands in v2.x — until then, secrets are the supported field.

If the file is missing, AgentBreeder picks an install-mode-aware default:

Backend matrix

The keychain backend partitions secrets by workspace name — multiple workspaces on the same machine never read each other's values.

Warning: the env backend stores values in plaintext on the local machine (or container/Docker volume) — it is not encrypted and is intended for local development and CI only. For any production or shared deployment, use a managed backend (aws, gcp, vault) so secrets live encrypted at rest with access controls and audit. agentbreeder deploy mirrors your declared secrets into the target cloud's manager automatically, so you never ship a plaintext .env to production.

CLI

# Set a secret in the workspace backend (prompted securely; never echoed).
agentbreeder secret set OPENAI_API_KEY

# List secrets (names + masked metadata only — values are NEVER printed).
agentbreeder secret list

# Rotate a secret (paste the new value when prompted).
agentbreeder secret rotate OPENAI_API_KEY

# Mirror selected secrets to a cloud backend (the same operation that
# runs implicitly inside `agentbreeder deploy`).
agentbreeder secret sync --target aws
agentbreeder secret sync --target gcp --include OPENAI_API_KEY --dry-run

# One-time migration between backends (e.g. dev → prod).
agentbreeder secret migrate --from env --to aws

All mutating commands (set, rotate, delete, sync) emit audit events — secret.created, secret.rotated, secret.deleted, secret.mirrored — that appear in Studio's audit log.

Auto-mirror at deploy

Cloud coverage (v2.6.0): auto-mirror (creating cloud-provider secret-store entries automatically during deploy) is shipped for GCP Cloud Run and Azure Container Apps today. AWS (ECS Fargate, App Runner) and Kubernetes auto-mirror are on the roadmap — for those targets, pre-create your secrets in AWS Secrets Manager and reference them by name in deploy.secrets: in agent.yaml, or run agentbreeder secret sync --target <cloud> ahead of deploy. See the deploy-target status table for current per-target availability.

When you run agentbreeder deploy against GCP Cloud Run or Azure Container Apps and your agent.yaml declares deploy.secrets, the engine:

1. Reads each value from the workspace backend.
2. Writes it to the target cloud's secrets manager under agentbreeder/<agent-name>/<secret-name> (idempotent: re-deploys add a new version rather than creating a duplicate).
3. Grants the agent's runtime service account secretAccessor on only the secrets that agent uses. (When AWS auto-mirror lands, the equivalent secretsmanager:GetSecretValue grant will be issued on the runtime IAM role.)
4. Wires the container env so OPENAI_API_KEY resolves at runtime to the cloud-native value reference (no plaintext ever flows through the container image).
5. Records a secret.mirrored audit event per secret.

The mirror runs inside the existing deploy step — it does not change the sacred deploy pipeline contract. If a referenced secret is missing from the workspace backend, the deploy logs a warning and continues; the env var is simply absent from the running container.

Studio

Navigate to Settings → Secrets (/settings/secrets) to see the workspace's secrets list with masked metadata, current backend, and a per-secret rotate action. Studio never fetches a secret value — only metadata.

Per-agent auth tokens

Every deployed agent's runtime is gated by a bearer token (AGENT_AUTH_TOKEN). Studio's Invoke tab on /agents/{id} resolves this token server-side from the workspace secrets backend so the value never enters the browser. The convention is a deterministic name keyed by the agent:

agentbreeder/<agent-name>/auth-token

Set or rotate it the same way you manage any other workspace secret:

# Set the token (prompted securely; never echoed).
agentbreeder secret set <agent-name>/auth-token

# Rotate it (paste the new value when prompted).
agentbreeder secret rotate <agent-name>/auth-token

Resolution order inside POST /api/v1/agents/{id}/invoke:

1. The request body's optional auth_token field — explicit override, kept for power users / SDK callers / tests.
2. The workspace secrets backend at agentbreeder/<agent-name>/auth-token.
3. The legacy env var AGENT_<UPPER_SNAKE>_TOKEN on the API host (deprecated; kept for back-compat with installs that pre-date workspace secrets).

If none of the three resolve, the proxy forwards the request without an Authorization header and the runtime returns 401 — that surfaces a clear "set the secret" message to the caller without leaking 500s on missing secrets.

Related

• agent.yaml reference — deploy.secrets
• CLI reference — agentbreeder secret
• Authentication