Agent Substrate

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

KindWhere it is storedHow it is used
Model keysThe 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 namesBound only to your actors
Values a program inside the actor must readOff by defaultA 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 credentialsdefenseclaw-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-*]
  • source is always an ate-secret://<provider-class>/<provider-name>/<path> reference, never a value. A per_person secret's source contains {person}, which becomes a key derived from the signed-in person; a shared one must not.
  • name is lower-case letters, digits, - and .. profiles lists profile names or globs and is required, as is at least one host.
  • placeholder is the environment variable the actor carries in place of the value.
  • npm registries. template build --config gives the kit's npm configuration a placeholder token for every exact host of a secret injected in the Authorization header (//HOST/:_authToken= the secret's placeholder). npm sends it only to that registry, and egress swaps it there, so npm install from 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), so template build copies 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_for is 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-token

list 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:

ReasonMeaning
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.com and *.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_TOKEN in 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 by CLAUDE_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 an env listing, the value is replaced with <redacted>.
  • git remotes. The kit's system git configuration rewrites ssh://git@, git+ssh://git@ and the git@github.com:, git@gitlab.com: and git@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: use https://git.example.com/org/repo or ssh://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 (verify checks its encryption, public access, expiry and region), and use delete to remove an agent's snapshots.