tokenstash

Paste a key once. Approve each directory. Keep secrets out of status output.

A local credential broker for coding agents. When your agent needs an API key, it asks tokenstash instead of asking you to paste it into the chat. The key goes into your project's env file, and the agent gets back a status line instead of the key.

Download · Security · Changelog

Install

brew install kgarg2468/tokenstash/tokenstash
# or
npm install -g tokenstash
# or
uv tool install tokenstash

Then, once:

tokenstash init

init picks your OS keychain and adds tokenstash to the agents it finds: Claude Code, Codex, Cursor and Gemini CLI. macOS and Linux; Windows is not supported yet.

bun add -g tokenstash
pnpm add -g tokenstash
pipx install tokenstash
cargo install --locked --git https://github.com/kgarg2468/tokenstash tokenstash

How it works

When the agent needs a key, it runs tokenstash need OPENAI_API_KEY (or asks over MCP). There are three outcomes:

• You have the key and this folder is approved: it's written to .env.local and the agent carries on.
• You have the key but this folder hasn't been approved: you get a notification. Open it, see exactly which keys would go into which file, and approve once.
• You don't have the key yet: you get a notification and a link to a page tokenstash serves on localhost, with the provider's signup link and the steps. Paste the key there once; it's stored in your OS keychain, and every later project can get it from there.

• Approval is per folder, and you choose how wide. The first time a folder asks for keys you already have, you get three choices: Allow these (just the listed keys), Allow these + any non-sensitive key here (also future registry-known, non-sensitive keys), or Deny (remembered for 24 hours by default).
• Sensitive keys always ask. Live Stripe secret keys, AWS credentials, deploy and package-registry tokens, and any key tokenstash doesn't recognise get their own approval in each folder. The broad choice never covers them.
• Local secrets are generated, not asked for. AUTH_SECRET, JWT_SECRET, SESSION_SECRET and similar are created by tokenstash, one per folder.
• Keys can be re-checked with the provider. Keys whose provider supports an unattended check are re-checked before delivery when a check is due. A rejected key becomes a "replace this key" request; if the provider can't be reached, the key is delivered unchecked.

Where your key goes

The value goes from the page you paste it on, to your OS keychain, to the project's .env.local (mode 0600, and added to .gitignore). need and the MCP tool report back with an exit code and a line like ✓ OPENAI_API_KEY injected → .env.local, without the value, so delivering a key doesn't put it into the chat, a summary, or the conversation history. scripts/leak-test.sh runs the real binary with a canary key on every commit and fails if the canary appears on any of the surfaces it checks.

Your app loads .env.local the way it already would: frameworks such as Next.js read it on their own; for anything else, use your runtime's dotenv support, or start the program with tokenstash run --.

It's not a sandbox. An agent with a shell in an approved folder can read .env.local, just as it could without tokenstash, and anything you type into a request's note or answer field goes back to the agent as text. What goes away is the casual leak: the key pasted into chat or echoed back in a summary. The details are under Security details below and in SECURITY.md.

Using it

After tokenstash init, the agents it set up are instructed to ask tokenstash for keys. You can also run it yourself:

tokenstash need OPENAI_API_KEY RESEND_API_KEY   # write the keys you have; ask for the rest
tokenstash run -- npm run dev                   # load .env.local, and ask for a key the program says is missing
tokenstash open                                 # the inbox: everything waiting on you
tokenstash doctor                               # check the setup

Automatic, or only when you say so

By default the agent asks tokenstash on its own: init registers the MCP server and installs a skill that tells the agent to request a key whenever code needs one. If you would rather nothing happen until you ask:

tokenstash init --mode explicit

This takes the MCP server and everything the agent reads unprompted back out, and installs one command that only you can invoke: /tokenstash OPENAI_API_KEY in Claude Code and Cursor, /prompts:tokenstash OPENAI_API_KEY in Codex, /tokenstash OPENAI_API_KEY in Gemini CLI. Typed bare, it requests whatever the current task needs, and it covers the rest of that task: a key the work turns out to need later goes through it too. The command runs tokenstash need under the same rules, so the value still goes to .env.local and never into the chat. In a session where you don't type it, nothing tells the agent about tokenstash, so it will ask you for keys the way it always did. The one exception is a project where you ran tokenstash init --project: its AGENTS.md section stays, rewritten to say that keys are requested only when you invoke the command and never pasted in chat. tokenstash init --mode auto switches back, doctor shows the mode, and init --undo removes either.

Uninstall

1. Take tokenstash out of your agents: tokenstash init --undo. It puts back the agent config files init changed, from the copies it saved at the time, and deletes the files it created. An edit you made to one of those files since init (another MCP server added to Cursor, say) is lost with it, so check them first.
2. Optionally, remove your stored keys and data: expand the section below. Do this after step 1, since the data directory holds the copies init --undo restores from.
3. Remove the program: brew uninstall tokenstash, or npm uninstall -g tokenstash, uv tool uninstall tokenstash, pipx uninstall tokenstash.

More

License

MIT