keyward

[keyward — a secret broker for AI agents]

keyward

Store your API keys once. Let any AI tool request them with your approval — without ever seeing the value.

[CI] [MIT] [MCP compatible] [cross platform]

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

1. Leaking keys into AI chat — paste a key into a prompt and it lands in context, transcripts, and logs.
2. Re-entry tax — you type the same key again in every new session, project, IDE, and machine.
3. Scattered .env files — no single source of truth; you forget which key lives where.
4. Zero control — an agent can read or grab every secret at once instead of the one it needs.
5. 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 a keyward CLI 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_keys returns names only; request_key returns 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-bucketscoop install keyward
# Gogo 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 fileskeyward 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

Security model

• The secret value is never returned to the AI agent — request_key injects it into a target file and returns only a confirmation.
• The value is never written to the audit log (~/.keyward/audit.jsonl records tool, key, namespace, target, decision — no value) and never printed by ls/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

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