keyward is an open-source, local, encrypted secret broker for AI coding agents. Instead of pasting API keys into chat (where they leak into context and transcripts) or re-entering the same key in every new session, project, and IDE, you keep your keys in one encrypted vault. When Claude Code, Cursor, Gemini CLI, or any MCP-capable tool needs a key, it requests it by name, you approve that single request in a native OS prompt, and keyward injects only that key into your project. The model never receives the value.
The problem
- Leaking keys into AI chat — paste a key into a prompt and it lands in context, transcripts, and logs.
- Re-entry tax — you type the same key again in every new session, project, IDE, and machine.
- Scattered
.envfiles — no single source of truth; you forget which key lives where. - Zero control — an agent can read or grab every secret at once instead of the one it needs.
- Tool lock-in friction — switch IDE or model and you redo all key setup.
How it works
AI tool ──request_key("STRIPE_KEY", project)──▶ keyward ──native approval──▶ you
│ approved
◀── "injected STRIPE_KEY → ./.env" ─────────┘ (value never shown to the model)
- Vault — an age-encrypted file (
~/.keyward/vault.age,0600). The master key lives in the OS keystore (macOS Keychain / Windows Credential Manager / Linux libsecret), never on disk in plaintext. - Two faces — an MCP server (
list_keys,request_key) for AI tools, and akeywardCLI for everything else. - Out-of-band approval — the approval dialog is fired by keyward itself, not rendered in the agent's stream, so the agent cannot auto-approve. Choose Approve once, Approve for session, or Deny.
- Value-free by construction —
list_keysreturns names only;request_keyreturns a confirmation; the audit log records the decision but never the value.
Install
# Homebrew (macOS / Linux)
brew install arturayupov/tap/keyward
# Scoop (Windows)
scoop bucket add arturayupov https://github.com/arturayupov/scoop-bucket
scoop install keyward
# Go
go install github.com/arturayupov/keyward/cmd/keyward@latest
Pre-built binaries (macOS/Windows/Linux, amd64+arm64) are also attached to each release. See INSTALL.md for per-OS notes (incl. Linux libsecret) and TROUBLESHOOTING.md if something doesn't work.
Quickstart
# 1. create the encrypted vault (master key goes into your OS keystore)
keyward init
# 2. import keys you already have scattered in .env files
keyward import ~/projects
# 3. point your AI tool at keyward's MCP server (see below), then just ask:
# "use my STRIPE_KEY for this project" → approve the prompt → done
Use it as an MCP server
keyward is a standard stdio MCP server, registered the same way as the official MCP servers. Two steps:
1. Install the binary (once) — go install above, or Homebrew/Scoop (soon),
or a release binary.
2. Register it with your AI tool:
# Claude Code — one command:
claude mcp add keyward -- keyward serve-mcp
Or add it to the config by hand (~/.claude.json, or a project .mcp.json):
{ "mcpServers": { "keyward": { "command": "keyward", "args": ["serve-mcp"] } } }
Cursor, Windsurf, Cline, and other MCP clients use the same command/args
shape in their MCP settings. Restart the tool and ask it to use a key by name.
Why not "paste a repo URL"? No MCP client auto-installs a server from a GitHub link — by design, clients won't run arbitrary remote code. keyward is also intentionally local (it needs your OS keystore and writes to your local files), so it isn't a remote/hosted URL server. The two steps above are the standard, secure install path. Full walkthrough in USAGE.md.
CLI reference
| Command | Description |
|---|---|
keyward init | Create the encrypted vault and master key |
keyward import [root] | Import secrets from .env files under root, grouped by project |
keyward add NAME --ns NS | Add/update one secret, value read from stdin (for non-.env creds) |
keyward ls [--ns NS] | List key names and namespaces (never values) |
keyward inject NAME --ns NS --into PATH | Inject one key into a target env file (prompts for approval) |
keyward serve-mcp | Run the MCP server over stdio |
Security model
- The secret value is never returned to the AI agent —
request_keyinjects it into a target file and returns only a confirmation. - The value is never written to the audit log (
~/.keyward/audit.jsonlrecords tool, key, namespace, target, decision — no value) and never printed byls/inject. - Approval is out-of-band: a native OS dialog the agent cannot click. All dialog backends fail closed — any error or cancellation is a Deny.
- The vault is encrypted at rest with
age; the master key lives in the OS keystore.
These invariants are enforced by automated tests. Details and threat model in SECURITY.md.
How it compares
| keyward | envchain | pass / sops | 1Password CLI | |
|---|---|---|---|---|
| Encrypted local store | ✅ | ✅ (Keychain) | ✅ | ✅ (cloud) |
| Agent requests a key by name | ✅ | ❌ | ❌ | ❌ |
| Per-request human approval | ✅ | ❌ | ❌ | ❌ |
| Value never reaches the model | ✅ | n/a | n/a | n/a |
| MCP server for AI tools | ✅ | ❌ | ❌ | ❌ |
| Open source | ✅ (MIT) | ✅ | ✅ | ❌ |
The encrypted-storage problem is solved; keyward adds the missing agent-facing, approval-gated broker on top. See docs/comparisons for honest long-form comparisons (including when each alternative is the better choice).
Roadmap
Full detail in ROADMAP.md. Highlights:
- v0.2 — signed/notarized binaries (no keystore prompt), Homebrew/Scoop, biometric approval (Touch ID / Windows Hello), Windows ACL hardening.
- v1.0 — tray/menubar app, per-key policy & allowlists, rotation reminders,
target: "env"injection. - v2.0 — encrypted multi-device sync (user-owned backend), team mode.
Contributing
Contributions welcome — see CONTRIBUTING.md. Found a security issue? See SECURITY.md for responsible disclosure.
License
MIT © 2026 Artur Ayupov