Secrets

Named bundles of credentials, stored in macOS Keychain, injected into a single child process at run time.

The rule

Use agents secrets exec when you can and the --secrets flag on agents run when you cannot. Do not export credentials into the shell. The shell is shared with every tool you run afterwards.

Bad: export into the shell

export OPENAI_API_KEY=$(agents secrets get openai)
agents run codex "draft the migration"
# OPENAI_API_KEY is now visible to every subsequent process in this shell.

Any binary you launch in the same shell — an editor plugin, a build script, a curl one-liner — inherits the key. The key also lands in shell history if the command is edited or recalled with history.

Good: scope to one process

agents secrets exec openai -- agents run codex "draft the migration"

The bundle is resolved from Keychain, the env is set on the child process only, and the child exits with the env. Nothing leaks back to the parent shell. The same shape works for any command:

agents secrets exec stripe-prod -- bun run scripts/refund.ts
agents secrets exec hetzner.com -- crabbox run -- bun test

Create a bundle

agents secrets create stripe-prod
agents secrets add stripe-prod STRIPE_API_KEY --type api-key --expires 2027-01-15
agents secrets add stripe-prod STRIPE_WEBHOOK_SECRET --type api-key
agents secrets list

add prompts for the value and writes it to Keychain. Bundle definitions live in Keychain too — nothing about secrets touches disk in plaintext. The EXPIRING column on list flags any secret due in the next 30 days.

Rotate a secret

agents secrets rotate stripe-prod STRIPE_API_KEY --note "rotated after suspected leak"

rotate replaces the value and preserves metadata; add refuses to overwrite an existing key.

Touch ID

On macOS, Keychain access for secret bundles is gated by Touch ID when biometry is available. The prompt fires once per bundle per shell session, not per command.

Instructing an agent

When you write rules for an agent that will run shell commands on your behalf, make the policy explicit in AGENTS.md:

Run credential-needing commands via 'agents secrets exec <bundle> -- <command>'.
Do not 'export' secrets into the shell. Do not write secrets to .env files.
If a bundle is missing, stop and ask which bundle to use.

See browser profiles for attaching a bundle to a browser profile so agents can sign into sites without seeing the credentials.