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 automatically mirrors the values it needs to the target cloud's native secrets manager — granting the agent's runtime identity read access to only the secrets it declares.

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

deploy:
  cloud: aws
  secrets:
    - OPENAI_API_KEY
    - ZENDESK_API_TOKEN

At deploy time AgentBreeder reads OPENAI_API_KEY and ZENDESK_API_TOKEN from your workspace backend, mirrors each into AWS Secrets Manager under the deterministic name agentbreeder/<agent-name>/<secret-name>, and wires the running container's env to a Secrets Manager valueFrom reference. The value never lands on disk in the deploy bundle and never appears in CI logs.

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 | 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.

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 the dashboard's audit log.

Auto-mirror at deploy

v2.0 cloud coverage: auto-mirror ships for AWS ECS Fargate and GCP Cloud Run. Azure Container Apps, AWS App Runner, and Kubernetes auto-mirror are tracked for v2.x — for those targets today, use agentbreeder secret sync --target <cloud> ahead of deploy or set the values manually in the cloud console.

When you run agentbreeder deploy against AWS or GCP 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 (GCP) or secretsmanager:GetSecretValue (AWS) on only the secrets that agent uses.
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.

Dashboard

Navigate to Settings → Secrets (/settings/secrets) to see the workspace's secrets list with masked metadata, current backend, and a per-secret rotate action. The dashboard 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). The dashboard'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