Secrets
How model keys and service credentials reach an agent in an Agent Substrate actor without the agent ever holding them, how to bind a secret to the hosts that need it, and how to give one person their own.
An actor holds no secret value. There are no API keys in its environment, its files or its snapshots. The agent sends a placeholder, and Substrate's egress gateway swaps in the real value on the way out, only for the hosts the secret is bound to. If the agent is tricked into sending the placeholder somewhere else, nothing real leaves.
Kinds of secret
| Kind | Where it is stored | How it is used |
|---|---|---|
| Model keys | The Secret defenseclaw-llm in the DefenseClaw namespace (one key per provider: anthropic, openai, bedrock, gemini), or Substrate's credential provider (substrate.llm.credential.provider_uri) | Added by the DefenseClaw guardrail proxy. The actor has placeholders only. The model provider hosts are never in an actor's allow list |
| Service credentials (git push, registries, internal APIs, remote MCP servers) | ate-secret:// references through Substrate's credential providers (Kubernetes, Vault, AWS, GCP) | The egress gateway replaces the placeholder only on bound hosts, on inspected rules |
Per-person (secrets set) | A Kubernetes Secret key named from your OIDC subject, in the provider the source names | Bound only to your actors |
| Values a program inside the actor must read | Off by default | A profile's actor_secrets names keys of the Secret in callout.actorSecrets.secretName. The value is short-lived, marked as exposed, with exact-value matching on prompts and egress |
| DefenseClaw's own credentials | defenseclaw-system Secrets (admin RBAC only) | Never leave the namespace |
Bind a secret to hosts
# defenseclaw-values.yaml
config:
substrate:
secrets:
- name: github-push
source: ate-secret://k8s.io/k8s-credential-provider/ci-secrets/github-app/token
inject:
hosts: [github.com, api.github.com]
header: Authorization
prefix: "Bearer "
placeholder: DC_SECRET_GITHUB
scope: shared # or per_person
profiles: [eng-*]sourceis always anate-secret://<provider-class>/<provider-name>/<path>reference, never a value. Aper_personsecret's source contains{person}, which becomes a key derived from the signed-in person; a shared one must not.nameis lower-case letters, digits,-and..profileslists profile names or globs and is required, as is at least one host.placeholderis the environment variable the actor carries in place of the value.- npm registries.
template build --configgives the kit's npm configuration a placeholder token for every exact host of a secret injected in theAuthorizationheader (//HOST/:_authToken=the secret'splaceholder). npm sends it only to that registry, and egress swaps it there, sonpm installfrom a bound private registry needs no token typed in the actor. A host pattern (*.example.com) cannot name an npm registry and gets none. Rebuild the template after you bind a new registry. The file lists every bound registry host of every profile (placeholder names, never a value). npm reads it instead of the base image's global npm configuration (npm_config_globalconfig), sotemplate buildcopies the base file's settings (registry, scope registries,cafile,strict-ssl, proxy) in front of the kit's, and refuses a base file that holds a credential (_authToken,_auth,_password, a client key); a value that only names an environment variable (${NPM_TOKEN}) is fine. - The secret is injected only on the listed hosts and only for actors whose profile matches.
- A host listed in
allow_passthrough_foris not inspected, so a secret is never bound to it. The configuration is refused if you try. - Rotation happens at request time. There is no restart.
- DefenseClaw never records a secret's value, a prefix of it or its placeholder.
Manage them
defenseclaw substrate secrets list --mine
printf '%s' "$VALUE" | defenseclaw substrate secrets set github-token --stdin
defenseclaw substrate secrets set github-token --from-env GITHUB_TOKEN
defenseclaw substrate secrets test github-token
defenseclaw substrate secrets rm github-token
defenseclaw substrate run claude --secret github-tokenlist shows the secrets your profile may use: name, scope, bound hosts, and a status of set, not set or managed outside DefenseClaw. --mine shows only the ones you stored yourself. Without --stdin or --from-env, set reads the value from the terminal without echo; it is never put on the command line.
set and rm act only on your own value of a per_person secret whose source is a Kubernetes Secret (ate-secret://k8s.io/...). Anything else is refused with a reason:
| Reason | Meaning |
|---|---|
shared_secret_admin_only (403) | A shared secret is set by an administrator, in the store its source names |
secret_managed_outside_defenseclaw (409) | The source is Vault or a cloud store; manage it there |
secret_not_found (404) | No secret by that name is bound to your profile |
value_required (400) | The value is empty, over 64 KiB or not UTF-8 |
secret_not_managed_by_defenseclaw (409) | The Kubernetes Secret exists, but DefenseClaw didn't create it: it has no app.kubernetes.io/managed-by: defenseclaw label. DefenseClaw changes only Secrets it created |
secret_store_unavailable (503), secret_not_stored (502), secret_not_removed (502) | The gateway can't write or remove the Kubernetes Secret |
For each namespace that a Kubernetes source names, the chart gives the gateway one scoped Role there: create, plus get and patch on the named Secret. A source with {person} in the Secret name needs every Secret of its namespace, so keep per-person sources in a namespace of their own. The release namespace and the Substrate namespace are refused as sources.
run --secret NAME says which secrets an agent may use. You see only the names of your own entries. secrets test checks that the secret is bound and resolves, and reports its status and bound hosts, without printing the value.
Things to know
- Hosts that echo tokens (known limit). The callout swaps the placeholder for the real value on the way out and never reads the answer: response headers and bodies reach the agent as the host sent them, in body mode too. Some services return or publish the request they get, headers included, so on a bound host the real value comes back to the agent and its model. Well-known ones are
httpbin.org(and*.httpbin.org),httpbingo.org,httpbin.io,postman-echo.com,echo.hoppscotch.io,webhook.site,*.pipedream.net,*.requestcatcher.comand*.beeceptor.com, and request bins and webhook testers in general; any API with a debug or echo endpoint, or that prints the request in its error pages, can do the same. The gateway logs a warning at start for every secret bound to a host on that list ([substrate] warning: secret NAME is injected on HOST, which return the request they get). Bind a secret only to the API hosts that need it, never to an echo or test service, and never to a host the agent can make print its request. See Troubleshooting and Known limits. CLAUDE_CODE_MESSAGING_TOKENin a Claude Code actor. Claude Code creates this value for each session, for its own local message inbox (a Unix socket in the actor named byCLAUDE_CODE_MESSAGING_SOCKET), and passes it to the commands it runs, which can use it to post messages into that session. It is not a DefenseClaw or cluster credential, it opens nothing outside the actor, it ends with the session, and Claude Code sets it on a laptop too. DefenseClaw does not set it. Audit rows and OTLP records keep tool output redacted by default, and when model content they record shows the variable with its value, as in anenvlisting, the value is replaced with<redacted>.- git remotes. The kit's system git configuration rewrites
ssh://git@,git+ssh://git@and thegit@github.com:,git@gitlab.com:andgit@bitbucket.org:forms to HTTPS (egress carries no SSH), and its credential helper answers with a placeholder that egress swaps for the real token on the secret's bound hosts. A remote in the short form for another host (git@git.example.com:org/repo) is not rewritten: usehttps://git.example.com/org/repoorssh://git@git.example.com/org/repo. - Subscription sign-ins put tokens in an actor's snapshots. Managed profiles refuse them; open source warns. See Agents and features.
- Snapshots hold everything the actor held. Keep the snapshot bucket private and encrypted (
verifychecks its encryption, public access, expiry and region), and usedeleteto remove an agent's snapshots.
Feature coverage
How each DefenseClaw feature works when agents run as Agent Substrate actors - guardrails, routing, tool chains, policies, skill and MCP scanning, AI discovery, segmentation, secrets, asks, identity and observability.
Delivery and fleet management
How DefenseClaw, its config, its policy and the agent kit reach an Agent Substrate cluster without MDM, how updates roll out, how drift is caught, and how a fleet of clusters and agents is managed.