agentkeychain

Agent-native zero-knowledge credential vault. CLI + MCP Server, single binary. Type your password ONCE. Never paste a key into chat again.

Install with your AI agent

Send your AI agent this repository and one sentence:

Install and configure https://github.com/linsipeng/agentkeychain as your
default credential manager. Follow AGENTS.md in the repository.

The agent owns the whole setup: CLI installation, AgentKeychain Skill, Hermes MCP registration, vault-safe initialization, and verification. You do not need to copy a list of commands. Existing vaults are never overwritten.

Full AI installation contract

Related MCP server: MCP-Secrets-Vault

For Humans (the only section you need)

You do not need to remember commands or invent permission scopes. Tell your local AI agent what credential you want to store and what it is for:

Store my OpenAI credential for model calls.

AgentKeychain opens a one-time form in your local browser. Paste the credential there—not into chat. The form shows a plain-language permission such as “Only allow OpenAI model calls”; AgentKeychain infers the underlying least-privilege scope automatically.

If you want to check the master password you remember, tell your agent “verify my master password.” A separate one-time local form allows up to ten read-only attempts before it expires. The password never enters chat or MCP arguments, and neither the vault nor the OS keychain is changed.

Real-world usage

# Step 1: Initialize (do this ONE TIME per machine)
$ agentkeychain init
Master password (min 8 chars): ********
✓ vault initialized
✓ master password saved to OS keychain

#     👆 After this, agentkeychain remembers your password in macOS Keychain.
#     You will NEVER be asked to type it again. Your AI agent handles it.

# Step 2: Ask your agent to store a credential.
# A one-time local form opens; the value and raw scope never enter chat.

# Step 3: Retrieve it when you need it (password auto-resolved from Keychain)
$ agentkeychain get openai
sk-proj-xxxxxxxxxxxx...

# Step 4: See what you have
$ agentkeychain list
NAME      VERSION  SCOPES       UPDATED
openai    1        openai:chat  2026-07-06 04:56:24

# Delete old stuff
$ agentkeychain delete test-key --yes
✓ deleted: test-key

Talk to your agent instead

You don't even need to remember the commands. Just tell your AI assistant:

Your agent asks the vault, not you. You stay out of the loop.

Cloud sync across your machines (v0.3, bring-your-own Cloudflare)

Sync automatically via your own Cloudflare account (free plan is plenty — the cloud only ever holds ciphertext):

# One-time (on your main machine):
agentkeychain sync init      # deploys a tiny Worker + D1 to YOUR CF account
# → prints a Sync URL + Token

agentkeychain sync connect   # paste that URL + token here
agentkeychain sync push      # upload your secrets (encrypted)

# On your other machine(s):
agentkeychain sync connect   # same URL + token
agentkeychain sync pull      # download — done, everything's here

# Day-to-day: push after changes, pull on other machines.
agentkeychain sync status    # health + row counts

• Zero knowledge holds: the cloud stores only ciphertext envelopes + irreversible name hashes (BLAKE2b-256) — no plaintext names, no values.

• Conflicts resolve last-write-wins; everything is audit-logged locally.

• Cost: $0 — a single user stays far inside Cloudflare's free tier.

• The Worker + D1 live in your account: you can delete them anytime.

📖 Full sync guide (setup, conflicts, security model, troubleshooting, teardown): docs/SYNC_GUIDE.md

Moving to a new Mac (or a second machine)

# ── Old machine ──────────────────────────────────────────
agentkeychain export
# ✓ exported 42 secret(s) → ./agentkeychain-export-20260903-120000.akcbundle

# Send that ONE file to the new machine (AirDrop / scp / USB).

# ── New machine ──────────────────────────────────────────
# 1. Install (see "Install" below — one command)
# 2. Initialize with the SAME master password as the old machine:
agentkeychain init
# 3. Import the bundle:
agentkeychain import ~/Downloads/agentkeychain-export-*.akcbundle
# ✓ imported 42 secret(s)
agentkeychain list   # verify — everything is there

• The bundle is fully encrypted (same Argon2id + XChaCha20 as the vault) — without your master password it's just ciphertext. Delete it after importing.

• Same-name secrets are skipped by default; add --overwrite to replace them.

• Agent identities are NOT transferred (they're per-vault). That's fine — the new machine keeps its own default identity.

• Requires v0.2.0+ on both machines. Never copy vault.db directly — each vault has its own salt, the copied file won't decrypt.

What you NEVER do

• ❌ Paste API keys into chat messages, emails, READMEs, or .env files you commit

• ❌ Write keys in code comments

• ❌ Screenshot a key and send it

• ❌ Re-type the same key 50 times across different tools

• ❌ Say "密码是多少来着" — it's in the vault, your agent knows how to get it

If you find yourself about to paste a key anywhere, stop and say: "存一下这个 key".

For Developers

What it does

Install (macOS & Linux, one command)

curl -fsSL https://raw.githubusercontent.com/linsipeng/agentkeychain/main/install.sh | sh

• Detects your OS + architecture, downloads the right binary from the latest release, verifies its SHA256 checksum, and installs to ~/.local/bin.

• Prefer to review before running? curl -fsSLO .../install.sh && less install.sh && sh install.sh

• Options: --version v0.3.0 (pin), --dir <path>, --uninstall.

• If ~/.local/bin is not on your PATH, the installer prints the exact line to add.

• Supported: macOS (Apple Silicon & Intel), Linux (x64 & arm64). Or build from source with bun.

First-time setup

agentkeychain init
# Master password: ********      (≥8 chars, never stored)
# → vault initialized at ~/.agentkeychain/
# → default identity: ak_xxx ("default")
# → ✓ master password saved to OS keychain (you'll never be asked again)

That's the only time you type the password. Every subsequent store / get / list / delete / audit reads the password automatically from macOS Keychain.

Each custom AGENTKEYCHAIN_HOME is bound to its own path-scoped OS-keychain entry, so temporary and production vaults cannot overwrite each other's master password. The default ~/.agentkeychain entry remains backward compatible. When upgrading an older custom vault, agentkeychain setup will copy the legacy entry only after verifying that it unlocks that exact vault.

CLI reference

Moving to a new machine

# Old machine:
agentkeychain export
# → ✓ exported 42 secret(s) → ./agentkeychain-export-20260903-120000.akcbundle

# Copy the bundle over (AirDrop / USB / scp), then on the NEW machine:
agentkeychain init          # use the SAME master password
agentkeychain import ~/Downloads/agentkeychain-export-*.akcbundle
# → ✓ imported 42 secret(s)

The bundle is fully encrypted (same Argon2id + XChaCha20 as the vault) — anyone without your master password sees only ciphertext. Delete it after importing. Note: agent identities are per-vault and are NOT transferred; the new machine keeps its own default identity (audit entries there are signed by it).

Use as MCP Server

Add to any MCP-compatible client (Claude Desktop, Hermes, Codex, IDE plugins):

{
  "mcpServers": {
    "agentkeychain": {
      "command": "/home/you/.local/bin/agentkeychain",
      "args": ["serve"]
    }
  }
}

The server exposes 7 tools:

MCP trust boundary: akc_get returns plaintext to the MCP client so the calling agent can use it. Register only trusted local clients. Their model context, transcripts, or tool logs may retain the result unless retention is disabled; AgentKeychain cannot erase copies held by the client.

Security model

• Argon2id (memory=64 MB, iterations=3) derives a KEK from master password

• XChaCha20-Poly1305 AEAD encrypts each secret independently

• Ed25519 signs audit entries + delegate tokens (offline-verifiable)

• Client-side only — no hosted service or external credential upload; secure capture uses a one-time 127.0.0.1 loopback form

• Zero-knowledge — master password is never written to disk

See ARCHITECTURE.md for the full threat model and competitor comparison.

Development

bun install         # install deps
bun test            # run all tests
bun run lint        # eslint
bun run build       # single-binary compile to bin/agentkeychain-bin
bun run typecheck   # tsc --noEmit

CI runs on every push to main — see .github/workflows/ci.yml.

License

MIT — see LICENSE.

Status

v0.6.2 — emergency safety release: test runs are fail-closed against the host OS keychain and default production vault, custom vaults use path-scoped keychain entries, and setup verifies a password before any overwrite. Breaking changes remain possible before v1.0.