Docs

How to set up keydillo, your AI's missing secrets manager, and use it with Claude Code and your own commands.

Install

brew install --cask ephibbs/keydillo/keydillo

Then open keydillo and choose Connect. Or download keydillo.dmg, open it and drag keydillo to Applications. It needs macOS 15 or later and is signed and notarized by Apple.

To build from source instead, you need macOS 15 or later, Xcode 16, XcodeGen and an Apple Developer account.

git clone https://github.com/Ephibbs/keydillo
cd keydillo/App
# set DEVELOPMENT_TEAM in project.yml to your team ID
xcodegen
open Keydillo.xcodeproj

Keys are stored in a private Keychain group tied to your team, so the Mac you build on must be registered in your developer account. Builds without that group refuse to store keys.

On first launch, setup asks how often to use Touch ID, then offers to connect Claude Code. Connect installs kd in ~/.local/bin, next to claude, and tells Claude how to use keydillo. You can also install the Claude Code plugin:

/plugin marketplace add Ephibbs/keydillo
/plugin install keydillo@keydillo

For Cursor, Codex and other coding agents, add keydillo's instructions as a skill:

npx skills add Ephibbs/keydillo

The skill adds the instructions but not the check that runs before each command, so for Claude Code prefer Connect or the plugin.

Using kd

Put kd in front of commands that use your keys. Claude does it for you.

kd npm run dev
kd python script.py

kd is short for keydillo run --. It runs the command with its HTTPS going through a small proxy that only that command and its child processes can use. When the program sends a keydillo:<name> placeholder to its API, keydillo asks for Touch ID and swaps in the real key. Everything else passes through untouched, still encrypted.

  • Nothing is routed without kd.
  • If keydillo isn't running, kd opens it in the background, unless you quit it yourself from the menu.
  • Tested with curl, Python (requests, httpx, aiohttp, urllib), Node (fetch, https, undici, axios), Bun and Deno.

Placeholders and the local proxy

Each key gets a placeholder and a local base URL. keydillo env <name> prints the lines for your .env:

OPENAI_BASE_URL=http://localhost:7787/openai/v1
OPENAI_API_KEY=keydillo:openai

Programs run with kd can keep calling the real host with the placeholder. Programs that can't use kd can call the base URL instead, with no key: http://localhost:7787/<name>/.... keydillo adds the key on the way out.

  • A key is only ever sent to its own host. If a key has no host yet, keydillo locks it to the host the first time a program uses it, after you approve with Touch ID.
  • The key goes only in its configured spot, usually one header. A placeholder found in the body, query or path is refused unless you turn on "Allow the key anywhere" for that key.
  • keydillo removes the key from responses before they reach the program.
  • Web pages can't use keydillo. Cross-site browser requests are refused.
  • The default port is 7787.

In your code, read the base URL from its env var and fall back to the real host when it's unset, so production works with a real key set in your host's settings.

Importing .env files

keydillo can bring in keys from your existing .env files. It imports values whose names look like secrets (KEY, SECRET, TOKEN and similar), rewrites each with a placeholder, and leaves values like PORT alone. It reads .env, .env.* and .dev.vars.

Each import saves a copy of the original files in keydillo's private Keychain group, so you can put them back later.

Keys meant to ship to browsers, like a Stripe pk_ key, a Supabase anon key or NEXT_PUBLIC_* values, don't need keydillo.

Touch ID and approval

You choose the default in setup and can change it in Settings, or per project on the project's page.

SettingWhat it does
Every timeTouch ID for every request that uses a key.
Once per sessionThe default. Touch ID once, then the same program can keep using the key until it exits.
Ask once per projectAfter one Touch ID, any program run from the project's folder, not just Claude, can use its keys until keydillo quits, even while the Mac is locked. Turning it on needs Touch ID. Use it only for projects whose keys can't cost much.

The prompt names the key and the program asking for it. macOS lets your login password stand in for Touch ID.

While the Mac is locked, keys can't be read and requests get a clear "Mac is locked" reply, except for projects set to Ask once per project.

Projects and folders

Keys are grouped by project. A project's folder is how keydillo knows which keys a program in that folder should use. Keys you add from Claude Code are filed under the current folder's name.

A project without a folder can still hold keys and change its Touch ID setting, but Ask once per project needs a folder. Use Set folder… on the project's page, which asks for Touch ID. Your Home, Desktop and Documents folders can't be project folders.

To copy a project's keys out for Vercel or Fly, use the Readout in the app, behind Touch ID. Copied text clears from the clipboard after 30 seconds.

Launch-time keys

Some secrets your app uses itself and never sends to an API: database URLs, JWT, session, encryption and webhook signing keys, and request-signing keys like AWS. keydillo can store these as launch-time keys. Your .env keeps a placeholder, and kd gives the real value to the program as it starts, after a Touch ID that names the command, every time.

They are not fully hidden. The running program can see them, so a command that prints its environment could reveal them. They're unticked at import; tick the ones you want.

Planned: a local database proxy so passwords never enter the program, then signing and encryption keys. See the roadmap.

CLI

kd <command>Run a command through keydillo. Same as keydillo run -- <command>.
keydillo listStored keys: names, local URLs, hosts and projects. Never values.
keydillo add <name> --host <host> --header <header>Opens keydillo so you can paste the key. Options: --prefix "Bearer ", --env NAME, --project P.
keydillo env <name>Print the placeholder .env lines for a key.
keydillo mcpRun as an MCP server. Claude Code uses this.

There is no command to print a key, and keys are never passed on the command line, where they'd end up in shell history.

Claude Code tools

When connected, Claude gets these tools. None of them return a key.

statusWhether the proxy is up, which keys exist, and recent refusals with reasons.
list_servicesKeys with their local base URLs and env var names.
request_secretOpens a window on your Mac to add a key. Returns the base URL and placeholder lines.
request_key_changeAsks you to approve a change: how the key is sent, sharing it with another project, rotating it, or moving a project's folder.
open_projectAsks you to approve all of a project's keys with one Touch ID. How long it lasts is your setting.

keydillo also adds Claude Code hooks. Before a command, it stops programs run without kd in a keydillo project. After a command, it explains provider errors caused by a placeholder. These hooks guide Claude; they aren't a security barrier.

Errors

Requests keydillo refuses get JSON with error, code and hint.

CodeMeaning
deniedYou declined the request.
approval_unavailableThe Mac is locked or Touch ID isn't possible right now.
unknown_serviceNo key with that name is stored.
needs_hostThe key has no host yet. Run the program with kd so you can approve one.
host_not_allowedYou didn't allow sending the key to that host.
placeholder_misplacedThe placeholder was in the body, query or path instead of the key's spot.
launch_time_keyThat key is given to programs as they start, not sent in requests. Use kd.
path_not_allowedThe key isn't allowed for that method or path.
rate_limitedThe key's hourly limit was reached.
browser_blockedThe request came from a web page.
key_unavailableThe key couldn't be read from the Keychain.
upstream_failedThe provider couldn't be reached.

If an API says the key is invalid, the program skipped keydillo. Run it with kd, or call the key's base URL.

What doesn't work yet

  • Under kd: Go and Rust programs (they ignore the extra certificate), gRPC, Next.js edge middleware, Python run with -I, and programs started with a cleaned environment. Call the base URL instead.
  • Docker: containers started with --env-file don't go through kd. Use http://host.docker.internal:7787/<name> as the base URL.
  • Programs not started with kd, like IDE run buttons or cron jobs.
  • Background processes that detach right away (pm2, tmux) lose access when kd exits.
  • Some SDKs check a key's exact format at startup (Clerk, for example) and reject the placeholder.

Full list with fixes: where kd can fail. Security model and limits: README. Report vulnerabilities privately: SECURITY.md.

Turning it off

Quit keydillo from the menu bar to stop all key use. To stop using it, choose Put my real keys back in the menu bar or Settings and confirm with Touch ID. It restores your .env files, for one project or all of them.

Settings also has Uninstall keydillo…, which can put the real keys back first, delete your keys from the Keychain, remove keydillo from Claude Code and stop it starting at login.