keyward

<p align="center"> <img src="docs/images/cover.png" alt="keyward — a secret broker for AI agents" width="100%"> </p>

<h1 align="center">keyward</h1>

<p align="center"> <strong>Store your API keys once. Let any AI tool request them with your approval — without ever seeing the value.</strong> </p>

<p align="center"> <a href="https://github.com/arturayupov/keyward/actions"><img src="https://github.com/arturayupov/keyward/actions/workflows/ci.yml/badge.svg" alt="CI"></a> <img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT"> <img src="https://img.shields.io/badge/MCP-compatible-5E6AD2" alt="MCP compatible"> <img src="https://img.shields.io/badge/macOS%20%7C%20Windows%20%7C%20Linux-informational" alt="cross platform"> </p>

---

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-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_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

	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