AgentKeyBox

AgentKeyBox is a local-first credential wallet for AI coding agents.

Store API keys in your macOS Keychain, organize them by project, and approve access requests from Claude Code or Codex through MCP.

The product goal is to let agents complete approved tasks using sensitive data while keeping raw values out of the agent/model's readable context. Today's alpha supports developer credentials with the execution limits described below. The working tree also includes an unreleased, experimental credit-card/recovery-code path: locally configured HTTPS field submission with per-use approval and fixed results. A second unreleased path adds website-login items and an app-owned browser for traditional same-origin HTML sign-in, constrained page text, and individually approved links. A restricted traditional recovery-code form can continue after a second approval, with its code saved as issued before private submission. JavaScript sign-in, SSO, TOTP and browser checkout remain unsupported; isolated ad-hoc native MCP/CLI recovery success has passed; the signed build has passed public-demo login/read/close with the data-protection Keychain; signed card/recovery-code submission, browser recovery continuation, GitHub recovery and other unaccepted workflows still require validation; see controlled browser use, the integration contract, product requirements, and roadmap.

AI asks. You approve.

AgentKeyBox is an experimental macOS utility for vibe coders, indie developers, and AI-first builders who do not want API keys scattered across .env files, notes, downloads, shell history, or chat windows.

▶ Watch here (24 seconds): project setup, key approval, and encrypted backups

https://github.com/user-attachments/assets/9486ce5d-6f2d-4965-8226-f6cb88d1a5ad

Install

You need: macOS 14 (Sonoma) or later on any Mac (Apple silicon or Intel), and Claude Code or Codex. Touch ID is optional; without it, macOS asks for your login password instead.

Download AgentKeyBox-<version>-macOS.zip from the latest release.
Double-click the zip, then open AgentKeyBox. macOS asks whether to open an app downloaded from the internet; choose Open. The app is signed with a Developer ID and notarized by Apple.
If a banner says AgentKeyBox isn't in your Applications folder yet, click Move to Applications. It moves itself there and reopens.
Drag your project folder onto the window (or click Choose Folder…). AgentKeyBox shows the keys it found in .env files and key files (.p8, .pem, service-account JSON), with real secrets already checked. Click Set Up: the keys move into your Keychain, your files stay where they are, unignored .env files can be added to .gitignore, and Claude Code / Codex are connected if installed.
Start a new Claude Code or Codex session in that project. When the agent needs a key, AgentKeyBox asks you; click Allow Once and touch Touch ID.

The interface follows your macOS language (English or Traditional Chinese). Change it in Settings › Language.

You don't need to keep AgentKeyBox open: it opens when you log in, and if it is closed, Claude Code, Codex, and akb open it in the menu bar when they need a key. Both are on by default and can be turned off in Settings › Startup.

Keep a backup of your keys. AgentKeyBox's copy lives in this Mac's Keychain only: it is not synced to iCloud and Migration Assistant does not move it to a new Mac. Setup therefore leaves your .env and key files in place. To keep coding agents from reading them anyway, setup adds rules to the project's AGENTS.md and CLAUDE.md and Claude Code Read deny rules to .claude/settings.local.json (on by default). It never loosens rules you wrote: it skips its exceptions for templates such as .env.example when one of your rules covers them, and does not add back an exception you removed. Claude Code enforces those rules for its file tools and common shell commands; for other agents they are instructions. Instructions only work when the agent starts in the project folder, and an agent may still follow a direct request to read the file. To remove the plaintext, export an encrypted backup (Settings › Backup) and choose Remove Keys from Files… in the project's menu.

Back up, and remove keys from your files

Settings › Backup › Export Backup… writes all your projects and keys to a password-protected .dmg (an AES-256 encrypted macOS disk image). Store the file and the password somewhere safe; Import… restores them on another Mac.
You can open a backup without AgentKeyBox: double-click the .dmg, enter the password, and you get a folder per project with its .env and key files (.p8, .pem, .json), plus a README listing them. Finder hides .env, so each folder also has env.txt with the same contents; rename it to .env when you copy it into a project. Eject the disk before importing it. See docs/BACKUP_FORMAT.md.
After a backup, right-click a project › Remove Keys from Files… empties those keys in its .env files and moves its key files to the Trash, so no coding agent can read them. Only values identical to what AgentKeyBox stored are removed; a name that also holds a different value anywhere in the file is left alone. Your app then gets its keys from AgentKeyBox: start it with akb run -- npm run dev (or your own command).

To check the download, compare shasum -a 256 AgentKeyBox-<version>-macOS.zip with the .sha256 file published next to it.

Update

Download the new version, open it, and click Move to Applications. The older copy goes to the Trash. Your projects, keys, and agent connections are kept: keys live in your Keychain, and agents use a helper at a fixed path that each version refreshes when it starts.

Uninstall

In AgentKeyBox, right-click each project and choose Remove Project…. This deletes its keys from your Keychain. Delete any Global keys the same way (right-click a key › Delete…). Deleting only the app would leave the keys in your Keychain.

Disconnect your coding agents:

claude mcp remove --scope user agentkeybox
codex mcp remove agentkeybox

Quit AgentKeyBox (menu bar icon › Quit AgentKeyBox) and move it from Applications to the Trash.

Remove its local settings and helper:

rm -rf ~/Library/Application\ Support/AgentKeyBox
defaults delete dev.agentkeybox.app

What it does

Claude Code / Codex
        ↓ MCP
agentkeybox-mcp
        ↓ authenticated local broker
AgentKeyBox.app
        ↓ native approval
macOS Keychain
        ↓
approved local process
        ↓ redacted result
AI agent

The MCP helper never receives the raw credential. AgentKeyBox reads the value from Keychain only after approval and injects it into the approved process.

This is still not a hard sandbox: a command you approve can deliberately transmit or transform a credential. The approval UI therefore shows the command and highlights high-risk shells, interpreters, and network tools.

Current alpha scope

macOS 14+
Swift + SwiftUI
macOS Keychain secret storage
local-only; no account and no backend
Claude Code integration
OpenAI Codex integration
project-scoped credentials
API keys and tokens
.env import
.p8, .pem, and JSON credential import
provider presets for common developer services
native Allow / Deny approval flow
Touch ID (or login password) confirmation for interactive approvals; opted-in session grants reuse the approved context
protected temporary-file delivery for file credentials
command timeout and output-size limits
raw/common-encoding output redaction
broker authentication, freshness checks, and replay protection
akb doctor and one-command agent setup
provider bundles: an App Store Connect key with its Key ID and Issuer ID, a Supabase key with its project URL, shown as one card
"don't ask again during this session" for the same agent session, project, key, and listed HTTP host or exact command, for up to eight hours; HTTP methods/paths/bodies are not separately scoped
English and Traditional Chinese interface

Build from source

swift build
swift test
./Scripts/mcp-smoke-test.sh
./Scripts/cli-smoke-test.sh
./Scripts/security-static-check.sh

On a Mac:

./Scripts/install-dev-macos.sh
open "$HOME/Applications/AgentKeyBox.app"
~/.local/bin/akb doctor
~/.local/bin/akb connect all

For a team-signed build that keeps secrets in the data protection keychain behind Touch ID (one prompt per approval, no keychain password dialogs after rebuilds), provide a signing identity and a macOS provisioning profile for dev.agentkeybox.app:

AGENTKEYBOX_CODESIGN_IDENTITY="Apple Development: Your Name (XXXXXXXXXX)" \
AGENTKEYBOX_PROVISIONING_PROFILE=/path/to/AgentKeyBox.provisionprofile \
./Scripts/build-release-macos.sh

You can also run the SwiftPM development executable directly:

./Scripts/run-dev-macos.sh

CLI

akb doctor [--json]
akb status [--json]
akb connect claude
akb connect codex
akb connect all
akb run [--only VAR1,VAR2] -- <command> [args…]
akb helper-path

akb doctor checks the MCP helper, local broker initialization, and Claude Code / Codex configuration.

`akb run` — replace your `.env` file

akb run -- npm run dev

After one Touch ID approval in AgentKeyBox, akb replaces itself with your command, with every text secret of the current project folder in its environment (or only --only names). The command keeps your terminal, so dev servers, prompts, and Ctrl-C work normally, and there is no timeout. Because the secrets are handed to your process, AgentKeyBox cannot redact its output; the approval prompt says so and shows the exact command. File credentials (.p8, .pem, JSON) are skipped.

MCP tools

`list_credentials`

Returns only non-secret metadata visible to the current project, including each credential's environment variable name and allowed hosts.

`http_request` — preferred for provider APIs

AgentKeyBox sends one HTTPS request itself, after approval, and returns the status and redacted body. The agent puts {{secret}} where the credential belongs:

{
  "credential_id": "UUID",
  "method": "GET",
  "url": "https://api.stripe.com/v1/balance",
  "headers": { "Authorization": "Bearer {{secret}}" },
  "purpose": "Check the Stripe test balance"
}

Request validation and execution rules:

https only; no credentials in the URL
{{secret}} only in header values, never in the URL or body
the host is checked against the credential's list (presets prefill it, e.g. api.stripe.com, *.supabase.co); an unlisted host shows a warning and defaults to Deny, but can be explicitly allowed and optionally remembered; credentials without a list are labeled unrestricted
redirects are not followed, so the credential header is never replayed elsewhere
30-second timeout, 128 KiB response limit, secret redacted from the response

Unlike run_with_secret, no local process or shell is involved, so common API calls no longer need a high-risk shell command.

`request_credential`

When list_credentials does not show what the project needs, the agent calls request_credential with the variable name (e.g. STRIPE_SECRET_KEY). AgentKeyBox opens a prompt with a link to the provider's dashboard where the user pastes the key. It is saved in the Keychain for the current project (adding the project folder if needed), and the agent receives only the new credential_id.

`run_with_secret`

Requests approval for one process execution.

Example conceptual input:

{
  "credential_id": "UUID",
  "env_var": "STRIPE_SECRET_KEY",
  "command": "/usr/bin/curl",
  "args": ["https://example.com"],
  "purpose": "Test the Stripe integration",
  "delivery": "environment"
}

delivery can be:

environment — inject UTF-8 secret text directly into the named environment variable.
tempFile — write the credential to a protected 0600 temporary file, inject that file path into the environment variable, and delete the file after execution. This is useful for .p8, .pem, and JSON credentials.

Connect Claude Code

The app includes a Connect Claude Code action. Equivalent command:

claude mcp add --scope user \
  --env AGENTKEYBOX_AGENT_ID=claude-code \
  --env "AGENTKEYBOX_AGENT_NAME=Claude Code" \
  --transport stdio \
  agentkeybox -- "$HOME/Library/Application Support/AgentKeyBox/bin/agentkeybox-mcp"

Verify with:

claude mcp get agentkeybox

The helper at that fixed path is copied from the app each time AgentKeyBox starts, so the connection survives moving or updating the app; a connected agent that still points elsewhere is re-registered automatically.

Claude Code supplies CLAUDE_PROJECT_DIR to local stdio MCP servers; AgentKeyBox uses it to scope project credentials.

Connect Codex

The app includes a Connect Codex action. Equivalent command:

codex mcp add agentkeybox \
  --env AGENTKEYBOX_AGENT_ID=codex \
  --env AGENTKEYBOX_AGENT_NAME=Codex \
  -- "$HOME/Library/Application Support/AgentKeyBox/bin/agentkeybox-mcp"

Verify with:

codex mcp get agentkeybox --json

Codex starts the MCP helper in the session's working directory, which AgentKeyBox uses as the project path unless AGENTKEYBOX_PROJECT_PATH is supplied. Verified with Codex 0.160.

Connect other coding agents

AgentKeyBox is a standard MCP server that runs over stdio. Claude Code and Codex are connected with one click; any other agent that runs on your Mac and supports local (stdio) MCP servers can be added by hand in that agent's MCP settings:

Command: ~/Library/Application Support/AgentKeyBox/bin/agentkeybox-mcp (write out the full path if the agent does not expand ~)
Environment variables:
- AGENTKEYBOX_AGENT_ID — a short ID, e.g. gemini-cli
- AGENTKEYBOX_AGENT_NAME — the name shown in approval prompts, e.g. Gemini CLI. In the unreleased build, an unrecognized client defaults to "Local Agent" (Codex environments can be detected separately). These labels do not authenticate the vendor.
- AGENTKEYBOX_PROJECT_PATH — the project folder, for agents that do not start MCP servers in the project folder. Otherwise AgentKeyBox uses the folder the helper starts in; outside your projects, the agent sees only Global keys.

Many agents use a JSON shape like the one below; check your agent's documentation for the exact file and key names.

{
  "mcpServers": {
    "agentkeybox": {
      "command": "/Users/you/Library/Application Support/AgentKeyBox/bin/agentkeybox-mcp",
      "env": {
        "AGENTKEYBOX_AGENT_ID": "my-agent",
        "AGENTKEYBOX_AGENT_NAME": "My Agent"
      }
    }
  }
}

Gemini CLI, GitHub Copilot in VS Code, Cursor, Windsurf, and Cline support local MCP servers and should work this way, but AgentKeyBox has not been tested with them yet.

The helper talks to AgentKeyBox on the same Mac. A cloud-only agent cannot connect directly to its stdio transport. The unreleased akb browser CLI gives an agent that can run commands on the same Mac a controlled entry point, with native approval and local authentication. It does not sign in the agent's own cloud browser. See the command reference.

Provider presets

The current catalog includes:

OpenAI
Anthropic
Stripe
Supabase
GitHub
Google / Gemini
Firebase
Apple App Store Connect
Vercel
Resend
Cloudflare

Presets are convenience metadata only; they do not send credentials to those providers.

Security model

AgentKeyBox currently protects against common accidental leakage patterns:

raw secret values are stored in Keychain, not metadata files
metadata and broker-token files are owner-only where supported
broker requests require a random per-install token
broker requests carry an ID and timestamp and are rejected if stale or replayed
one generic command approval expires after two minutes if unanswered
approved commands time out after 60 seconds by default
only a small allowlist of inherited environment variables is passed to approved child processes
output is truncated and common direct secret representations are redacted
project path matching avoids simple path-prefix confusion

AgentKeyBox does not claim to defend against malware or a malicious process already running as the same macOS user. See SECURITY.md and docs/ARCHITECTURE.md.

Repository layout

Sources/
├── AgentKeyBoxApp/       SwiftUI macOS app and approval UI
├── AgentKeyBoxCore/      models, Keychain, broker, security, adapters
├── AgentKeyBoxMCP/       stdio MCP server used by coding agents
└── AgentKeyBoxCLI/       akb doctor/connect CLI

Tests/
└── AgentKeyBoxCoreTests/

Scripts/
├── run-dev-macos.sh
├── install-dev-macos.sh
├── uninstall-dev-macos.sh
├── build-release-macos.sh
├── notarize-release-macos.sh
├── check-all.sh
├── mcp-smoke-test.sh
├── cli-smoke-test.sh
└── security-static-check.sh

Repository checks

Before a commit or alpha build, run:

make check

This runs formatter lint when available, a warnings-as-errors build, unit tests, MCP and CLI smoke tests, static secret/logging checks, and shell syntax validation.

See docs/SESSION_STATUS.md for the exact boundary between what is already verified and what still requires a real Mac.

Status

Experimental alpha. Verified on a real Mac: Keychain storage behind Touch ID, the approval prompt, session approvals, Developer ID signing and notarization, and installing from a download. Also verified end to end with real Claude Code and Codex sessions.

The product hypothesis is simple:

Can AI credential access feel as obvious as a normal macOS permission prompt?

Agent roadmap

P0: Claude Code, Codex
P1: Cursor, Google Antigravity / Gemini CLI lineage
P2: GitHub Copilot, Cline, Roo Code, Windsurf

AgentKeyBox integrates with the agent host, not a specific underlying model. Claude, GPT, Gemini, or Grok may run inside different coding environments.

Contributing

See CONTRIBUTING.md. Security reports should follow SECURITY.md rather than public issues.

License

Apache License 2.0. See LICENSE.

Product design direction

The interface is project-centric and import-first: drop a project folder, confirm once, and approve requests in plain language. Technical details stay behind progressive disclosure so users do not need to understand secrets-management infrastructure.

See docs/UI_DIRECTION.md for the design direction.

Brand direction

The current visual identity uses the Key in a Box + Agent concept: the box represents controlled local storage, the key represents developer credentials, and the agent represents AI coding agents that must request access.

See docs/BRAND.md for the visual rationale, color tokens, icon geometry, UI translation rules, and future asset requirements. The selected raster reference lives at assets/brand/agentkeybox-app-icon.png.