Secrets Manager overview
The Secrets Manager is where you keep credentials — API keys, tokens, connection strings — so they never live in your code or your shell history. This page explains the write-only design, how values reach your workloads, and how it compares to AWS, GCP, and Azure.
Why a secrets manager
Your agent probably needs an API key for some outside service. Hardcoding it in agent.py means it ends up in git, in build logs, and in every copy of the code. The Secrets Manager gives each credential a name, stores the value encrypted in a dedicated store (OpenBao, an open-source vault), and delivers it to exactly the workloads you choose.
The write-only design
The core promise: you can put values in, but almost nothing shows them back out.
- Every write creates a new version; nothing is ever overwritten. Rotating a key is just writing again.
- Listing secrets shows names and version numbers — never values.
- Fetching a secret's details shows its history and which agents use it — never values.
- The only call that returns a stored value is an explicit
:reveal, restricted to project admins, and every reveal is written to the audit log with your identity, the version, and the time. If the audit entry cannot be recorded, the reveal is refused. No log, no value.
The API says this itself when you store a value:
"the value is stored. Nothing - this API included - will show it back to you except an explicit, audited reveal."
Where secrets go
Two delivery paths:
- Bindings (recommended): a binding is a rule — "secret
openai-api-keyarrives as environment variableOPENAI_API_KEYon agentresearch-buddy." Bindings take effect when you apply them, which rolls a new revision of the agent. See Use secrets in workloads. - Call-time reads: a running workload can mint a short-lived, read-only token and fetch a value directly from the store — in Python, one line:
secret("openai-api-key"). The value is never parked in the environment at all.
There is also an older, simpler path — writing values straight onto one agent (platformctl secrets set). It works, but it has no versions and no sharing; details in Use secrets in workloads.
When to use which surface
| You want to... | Use |
|---|---|
| Store a credential once, use it on several agents, rotate it later | Project secrets + bindings |
| Prove who saw a value and when | Project secrets (reveals are audited) |
| Fetch a value only at the moment of use, never storing a copy in the environment | secret() at call time |
| Set one quick value on one agent, no ceremony | Direct per-agent values |
How it compares
| Cloud | Their product | Their pricing | What's different here |
|---|---|---|---|
| AWS | AWS Secrets Manager | $0.40 per secret per month + $0.05 per 10k API calls; automatic rotation via Lambda | No per-secret or per-call fee in alpha. Rotation is manual here: write a new version, then re-apply — there is no rotation automation yet. |
| GCP | Secret Manager | $0.03 per 10k access operations; replication policies | Same versioned, project-scoped model. We have no multi-region replication — this platform runs in one place. |
| Azure | Azure Key Vault | ~$0.03 per 10k operations; soft-delete and purge protection by default | No vault object to create before your first secret. But also no soft-delete: deleting a secret destroys every version, permanently. |
Honest trade-offs: all three competitors offer automatic rotation hooks, IAM integration, hardware security module options, replication, and SLAs that we do not have in alpha. What we do differently: reveals are admin-only and fail closed on audit, bind-versus-deliver is explicit (you always know what an agent is actually running with), and there is nothing to pay.
When you apply bindings, the platform reads the bound values and writes them into the agent's Kubernetes Secret as plain environment variables — agent pods cannot yet authenticate to the store themselves for env delivery. Call-time reads with secret() do go straight to the store. This is an honest MVP limitation, and it is also how env-var delivery works on the big clouds.
In this section
- Manage secrets — create, list, inspect, rotate, reveal, delete.
- Use secrets in workloads — bindings, apply, call-time reads, and the per-agent path.
Related: Agent secrets and environment · Secrets API reference · Audit log