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.

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 .env files — 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

Code

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

bash

# 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

server.ts

# 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:

bash

# 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):

config.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.

Keyward README