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.

If you are talking to ChatGPT Remote from a phone, KeepKeys can also open a one-time page inside your private Tailscale network. Paste the key there and it goes straight to the connected computer's native vault. KeepKeys does not use Tailscale Funnel or a Neorome server.

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, or a one-time tailnet-only phone page
Agent API	Research and store metadata, list metadata, remove, and approval-gated Run
Plaintext retrieval	No tool or helper action
Authorization	Native Allow once or exact-command automatic approval, with revocation
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 helper; optional private Tailscale transport; no KeepKeys account, cloud service, 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, eight integrations

Client	Package surface	Immutable install
Codex	Codex plugin + Neorome marketplace	codex plugin marketplace add neorome/keepkeys --ref b204980946bf3e305b8682850a00365335d2aae4 codex plugin add keepkeys@neorome
Grok Build / Grok Code	native Grok plugin	grok plugin install 'neorome/keepkeys@b204980946bf3e305b8682850a00365335d2aae4#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/neorome/keepkeys --ref b204980946bf3e305b8682850a00365335d2aae4
Cursor	Cursor plugin + local plugin link	see Install
Agent Skills clients	standard skills/keepkeys/SKILL.md	reviewed checkout or skills-only archive

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

• keepkeys_store
• keepkeys_store_from_phone
• keepkeys_list
• keepkeys_rotate
• keepkeys_revoke
• keepkeys_remove
• keepkeys_run
• keepkeys_status
• keepkeys_doctor

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

What the user experiences

Store:

1. The agent gathers any missing non-secret context, uses search tools to find and verify 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.

Store from a phone:

1. The agent prepares and validates the same non-secret metadata.
2. KeepKeys starts a ten-minute, one-use HTTPS page on an unguessable Tailscale Serve path.
3. The user opens the link on a phone in the same tailnet, reviews the metadata and any replacement warning, pastes the key, and presses Paste & Store.
4. The page sends the value through the private tailnet to the connected computer, where the native helper writes it to the operating-system vault. KeepKeys stops the owned Serve process and confirms exact route removal before the browser can show Stored. The localhost listener then closes. Desktop Store, phone Store, and Remove share one per-name coordinator, so removal cannot race a write and stores cannot silently race past the replacement warning. If the vault write succeeds but Serve cleanup fails, the page says the key was stored and reports the cleanup failure. If Linux storage and rollback both fail—or Windows Credential Manager cannot complete its paired-record rollback—the page says the final vault state is uncertain and tells the user to inspect and remove the name before retrying. A helper that ends without a valid commit receipt is uncertain for the same reason. If lock cleanup also fails, the page reports both problems.

The detached portal does not survive a cancelled launcher until the launcher acknowledges the ready link and the portal confirms that it processed that acknowledgment after rechecking Serve. KeepKeys also watches the foreground Serve process after readiness, including both sides of that handshake; an unexpected exit closes the portal instead of leaving a dead link advertised until expiry.

Phone intake requires Tailscale 1.52 or newer, MagicDNS, tailnet HTTPS, and a phone signed into the same tailnet. See the install guide. Before starting its owned route, KeepKeys reads tailscale serve status --json and selects private HTTPS 443 when unused or 8443 when 443 is occupied. Invalid status or both occupied ports fail closed without changing unrelated Serve configuration; KeepKeys never uses Funnel.

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, Always allow this exact command, or Cancel. Automatic approval binds the purpose, canonical executable, executable fingerprint, arguments, working directory, and script entrypoint fingerprint when present.
4. Only after approval does KeepKeys load the value and run the direct child.

Rotate reuses the reviewed metadata, opens the same native Paste & Store flow, and clears old exact-command rules after the replacement succeeds. Revoke opens a native confirmation and removes only automatic-approval rules. 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;
• keep the optional phone page inside the user's tailnet, bind it to one Tailscale identity and browser cookie, serialize same-name commits, and close it after one authenticated submission attempt or at the advertised ten-minute expiry, withholding browser success until both Serve-process and exact-route verification pass;
• 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;
• clear a phone's clipboard or clipboard history after phone intake;
• make a Tailscale account, device, ACL, or signed-in host trustworthy;
• silently synchronize vault values across devices; phone intake is a deliberate one-use transfer and never background replication;
• 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
• Favicon and small-mark assets

Neorome open source

KeepKeys is a Neorome 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.