You paste once. Your key stays out of chat and tool payloads.

KeepKeys is the open-source, local secret-use broker for coding agents. It opens a native paste-and-store window, stores the value in the operating system's credential vault, and gives the agent one narrow capability: run a specific command with one named secret after you review the exact request.

There is no get, show, copy, reveal, or export tool. Friendly names, environment-variable names, descriptions, providers, and official documentation links remain reusable for future tasks; the plaintext value does not.

Why KeepKeys exists

An .env file gives every process that can read the file a reusable credential. A general password-manager CLI commonly has a reveal path. A cloud agent vault adds an account, network boundary, and service operator.

KeepKeys is deliberately narrower:

Property	KeepKeys
At-rest storage	macOS Keychain, Windows Credential Manager, or Linux Secret Service
Secret entry	Explicit native Paste & Store, never chat or terminal
Agent API	Research and store metadata, list metadata, remove, and approval-gated Run
Plaintext retrieval	No tool or helper action
Authorization	One native Allow once decision per command
Process scope	Empty child environment plus one approved variable
Executable identity	Canonical path and SHA-256, rechecked after approval
Interpreter identity	Detected script entrypoint gets a second SHA-256
Output	Concurrent 1 MiB bounds and common-representation redaction
Service model	Local, offline, no KeepKeys account, cloud, daemon, or telemetry

The distinction is simple: KeepKeys provides approval-gated use without adding a reveal operation to the agent protocol.

Native on all three desktop platforms

Operating system	Secure store	Native human gate
macOS 13+	Security.framework Keychain; device-only and non-synchronizing	AppKit explicit clipboard paste, replacement, removal, and command approval
Windows 10/11	paired metadata/value records in Windows Credential Manager	branded WPF explicit clipboard paste, replacement, removal, and command approval
desktop Linux	paired metadata/value items in freedesktop Secret Service	branded Tk explicit clipboard paste, replacement, removal, and command approval

Listing and the approval screen read only metadata. The protected value is loaded after Allow once, metadata is checked again, and executable hashes are rechecked immediately before launch.

Linux fails closed without a compatible Secret Service and graphical session. It never falls back to a plaintext keyring, terminal password prompt, or file.

One core contract, seven integrations

Client	Package surface	Immutable install
Codex	Codex plugin + BarnLabs marketplace	codex plugin marketplace add barnlabs/keepkeys --ref e5276925d390704fccdf4aaeba47280464762a1c codex plugin add keepkeys@barnlabs
Grok Build / Grok Code	native Grok plugin	grok plugin install 'barnlabs/keepkeys@e5276925d390704fccdf4aaeba47280464762a1c#plugins/keepkeys' --trust
Claude Code	Claude plugin + pinned catalog	see Install
Oh My Pi	OMP/Claude-compatible pinned catalog	see Install
Hermes	repository-root Hermes plugin	see Install
Gemini CLI	Gemini extension + Agent Skill	gemini extensions install https://github.com/barnlabs/keepkeys --ref e5276925d390704fccdf4aaeba47280464762a1c
Agent Skills clients	standard skills/keepkeys/SKILL.md	reviewed checkout or skills-only archive

All integrations expose the same six tools and dispatch to the same platform-native boundary:

• keepkeys_store
• keepkeys_list
• keepkeys_remove
• keepkeys_run
• keepkeys_status
• keepkeys_doctor

Claude Code and Oh My Pi use the immutable catalog at commit c6e8c89c8dd38a7fecfdf6726a19f878aa80d1dd; that catalog pins the functional plugin source at e5276925d390704fccdf4aaeba47280464762a1c. See INSTALL.md for copy-paste commands and platform prerequisites.

What the user experiences

Store:

1. The agent gathers any missing non-secret context, researches official credential documentation, and chooses the name, environment variable, description, provider, and one to three official HTTPS documentation links.
2. KeepKeys validates that metadata before opening and displays it read-only.
3. The user copies the key from the provider and presses Paste & Store.
4. Only that click lets the native helper read the clipboard. It immediately clears the current clipboard, then the operating-system vault stores the value without returning it through the agent protocol.

Run:

1. The agent proposes an absolute executable, fixed argument list, purpose, and optional working directory.
2. KeepKeys displays the risk class, stored metadata, executable path, SHA-256, arguments, directory, environment scope, and detected script fingerprint.
3. The user chooses Allow once or Cancel.
4. Only after approval does KeepKeys load the value and run the direct child.

Remove always opens a native destructive-action confirmation and deletes the complete named record. Uninstalling a client does not silently delete credentials.

The security promise—and its edge

KeepKeys does:

• keep plaintext out of model prompts, tool inputs/results, plugin metadata, argv, persistent environment, and plaintext files;
• read the system clipboard only after Paste & Store and clear its current contents immediately after capture;
• pin native helper sources and fail closed on integrity mismatch;
• block common shells, environment dumpers, and Windows dynamic script hosts;
• classify common network clients and interpreters visibly;
• compare metadata and executable identity again after approval;
• bound both output streams and omit a whole stream after overflow;
• run native-vault doctor tests with generated temporary values only.

KeepKeys does not:

• make an approved executable safe;
• confine a credential after delivery to that process or its descendants;
• detect arbitrary encryption, splitting, file writes, IPC, or network egress;
• prevent same-user software, a coding host with unrestricted local-command execution, or operating-system clipboard history from observing a value while it is on the shared clipboard;
• protect against malware, a compromised signed-in account, administrator/root, debuggers, keyloggers, or modified local plugin code;
• promise forensic erasure inside operating-system-managed storage;
• claim to be unbreakable.

Read the complete threat model, privacy and data handling, and security policy before using KeepKeys for high-impact credentials.

Development and proof

macOS or Linux:

./scripts/bootstrap
./scripts/check
./scripts/test
./scripts/doctor

Windows:

.\scripts\bootstrap.ps1
.\scripts\check.ps1
.\scripts\test.ps1
.\scripts\doctor.ps1

CI runs the shared contract on macOS, Windows, and Ubuntu with Node.js 18 and 22. Separate jobs perform generated-value round trips through macOS Keychain, Windows Credential Manager, and a disposable GNOME Keyring session. GitHub Actions are pinned to exact upstream commits.

The repository has no runtime package dependencies. macOS compiles the reviewed Swift helper with Apple Command Line Tools; Windows uses built-in Windows PowerShell/.NET; Linux uses Python's standard library plus the desktop's Secret Service tools and Tk.

Check the stable channel only when you choose:

./scripts/check-update

The checker reports the stable version and immutable source/catalog commits. It does not install code, touch the native vault, or run in the background. See Updating KeepKeys.

Project documents

• Install, verify, upgrade, and remove
• Product and interface design
• Production acceptance checklist
• Independent code review
• Architecture
• Compatibility matrix
• Threat model
• Privacy and data handling
• Deliberate updates
• Release runbook
• Security reporting
• Roadmap
• Contributing
• Governance
• Brand guidelines

BarnLabs open source

KeepKeys is a BarnLabs open-source initiative, licensed under Apache-2.0. The Keykeeper—an old steward carrying a real ring of keys—represents the product's job: hold authority carefully, explain exactly where it is going, and hand over only the one key needed for the approved task.

Security reports belong in a private GitHub Security Advisory. Product ideas and reproducible bugs are welcome through the repository templates.