🔐 cvault

A local, encrypted, multi-tenant password manager for Claude Code. Claude can use your credentials (run commands, write .env files, call APIs) without the values ever entering the chat, and you get a fast terminal UI to browse, copy and edit them.

tenant (client / workspace)
 └─ environment (optional)      develop · staging · prod …
     └─ project                 ← linked to a directory on disk
         └─ service             (postgres, stripe, admin-panel, …)
             └─ item            secret · credential (multi-field) · file
                                 ├─ role + default   ("log in as admin")
                                 └─ versions v1, v2, … (never deleted)

path: tenant/env/project/service/key     e.g. rezilens/staging/digrc-api/admin-panel/systemadmin

For Claude (MCP server)

• Uses secrets without seeing them: output is scrubbed to ***

• Sealed mode: you type or receive values in a native macOS dialog or on the clipboard

• Knows the current project's credentials at session start (hook)

• Picks the right credential by role, or falls back to the default

For you (CLI + interactive UI)

• cvault: arrow-key explorer with tables, search, copy, edit

• Every change is a new version; roll back any time

• Archive instead of delete, restorable at any level

• Full audit log of every access

Contents

• Quick start

• How Claude uses it

• Interactive explorer

• CLI reference

• MCP tools

• Concepts: refs & environments · roles & defaults · versioning · archive · export & import · directory linking

• Security model

• Development

Related MCP server: SecureCode

Quick start

git clone <this repo> ~/mcp/vault-mcp && cd ~/mcp/vault-mcp
npm install && npm run build
npm link                       # puts `cvault` on your PATH

# 1. store a random master password in the macOS Keychain and create the vault
security add-generic-password -a "$USER" -s vault-mcp -w "$(openssl rand -base64 33)"
export VAULT_MASTER_PASSWORD_CMD='security find-generic-password -s vault-mcp -w'   # add to ~/.zshrc
cvault init

# 2. register the MCP server with Claude Code (user scope = every project)
claude mcp add cvault -s user \
  -e VAULT_MASTER_PASSWORD_CMD='security find-generic-password -s vault-mcp -w' \
  -- "$(which node)" ~/mcp/vault-mcp/dist/index.js

# 3. (recommended) SessionStart hook, so Claude knows each project's credentials
#    add to ~/.claude/settings.json → hooks.SessionStart:
#    { "hooks": [{ "type": "command", "timeout": 10,
#                  "command": "node ~/mcp/vault-mcp/dist/cli.js hook session-start" }] }

# 4. add your first project, linked to its directory
cvault project add acme/api --bind ~/work/acme-api
cvault set-cred acme/staging/api/admin-panel/superadmin -u root --role admin --default   # password prompted, hidden

The vault lives in ~/.vault-mcp/ (override with VAULT_HOME). The master password never leaves the Keychain.

How Claude uses it

Start Claude inside a linked directory and the session hook tells it which items exist (names only, never values):

CVAULT: this working directory is bound to vault project "acme/api"
Available items (names only, no values):
- admin-panel/superadmin (credential; role: admin; DEFAULT; fields: username, password, url)
- admin-panel/auditor    (credential; role: viewer; fields: username, password)
- stripe/api_key         (secret; "Stripe live key")

Then just ask:

Interactive explorer

Run cvault with no arguments (or cvault ui). cvault --help lists the scriptable commands.

 cvault  5 items in 1 project · ~/.vault-mcp
 home › acme › api
──────────────────────────────────────────────── Esc back/cancel · Ctrl+C quit ──
? Pick an item
  SERVICE     │ KEY        │ TYPE       │ ROLE   │ DEFAULT │ FIELDS / FILE           │ VER │ DESCRIPTION
  ────────────┼────────────┼────────────┼────────┼─────────┼─────────────────────────┼─────┼────────────────
❯ admin-panel │ auditor    │ credential │ viewer │ -       │ username, password      │ v1  │ Read-only
  admin-panel │ superadmin │ credential │ admin  │ yes     │ username, password, url │ v2  │ Full access
  ssh         │ deploy-key │ file       │ -      │ -       │ deploy.pem (412 B)      │ v1  │ CI deploy key
  stripe      │ api_key    │ secret     │ -      │ -       │ -                       │ v3  │ Stripe live key
 ── Actions ──────────────────────
  + New item…
  Services…

• Navigate: opens at the project linked to your current directory; search across all items by ref, role or description.

• Copy any secret or credential field. The clipboard auto-clears after 30s, even if you've already quit.

• Export: an encrypted bundle, .env or JSON for a project or the whole vault.

• View all fields, version history and the audit log as tables.

• Edit values and fields, add or remove fields, replace files. Each change saves a new version.

• Labels: role, default and description, without creating a new version.

• Manage: create tenants, projects, services and items; link directories; toggle Claude reveal; archive and restore; roll back; export a project or the whole vault.

• Keys: ↑↓ move · ⏎ select · Esc back / cancel the current action · Ctrl+C quit.

• Responsive: tables drop low-priority columns on narrow terminals.

CLI reference

MCP tools

Concepts

Refs & environments

tenant/[env/]project/service/key[@version][#field]

• The environment is optional. The same service name can exist once per environment (staging/admin-panel, develop/admin-panel), each with its own items, versions and allowed hosts.

• A directory link can carry a default environment: cvault project bind acme/api --env staging. Then admin-panel/root means staging.

• Listing and export scopes accept acme/staging (everything in staging), acme/staging/api or acme/api (all environments).

• cvault service-move acme/api/staging-panel acme/staging/api/panel moves an existing service into an environment (items, versions and hosts move with it).

• Credentials default to the password field.

Missing credentials

When a task needs a login that isn't in the vault, the session hook, server instructions and "not found" errors all point Claude at request_credential. It opens native dialogs:

1. Path: pre-filled with Claude's suggestion and editable. Paths are corrected automatically, with no second dialog. Project and environment typed in the wrong order (rezilens/digrc-api-service/develop/admin-panel/systemadmin) become rezilens/develop/digrc-api-service/admin-panel/systemadmin; extra levels fold into the service name; messy characters are cleaned. It only asks again when the intent can't be worked out.

2. Fields: username (visible), password (hidden), plus any extra fields Claude asks for. Masked fields (password, token, secret, key, pin, otp) are asked twice, and a mismatch asks again, so a typo can't be saved silently. For an existing item, leaving a field empty keeps its current value, and a new version is saved.

If a login is rejected, Claude is told to stop after one attempt (accounts often lock after a few), never to try another environment's credential, and to offer request_credential on the same path to re-enter it.

Claude only receives the resulting ref.

Enforced rules (code, not instructions)

The server enforces these itself, so Claude can't skip them:

Roles & defaults

Give credentials a role (admin, viewer, tester, …) and mark one per service as the default. "Log in as viewer" picks the viewer item; with no role named, Claude uses the default and only asks when neither applies.

Versioning

Every write creates version N+1. Old versions stay encrypted (and old files are kept as <uid>.vN.bin). @N reads any version; rollback copies an old version forward as a new version, so history is never rewritten.

Archive, never delete

Archive a tenant, project, service or single item. It's hidden and unusable but fully restorable. Archiving a tenant hides everything under it.

Export & import

cvault export acme/api                         # → cvault-acme-api.cvault (asks for a passphrase)
cvault import-bundle cvault-acme-api.cvault    # on the other machine
cvault import-bundle backup.cvault --into acme-staging/api   # remap tenant/project
cvault export acme/api/stripe -f env --yes --stdout          # STRIPE keys as KEY=value

.env names are built from the path below the export scope: exporting a project gives STRIPE_API_KEY and ADMIN_PANEL_SUPERADMIN_PASSWORD, while exporting one service gives API_KEY and SUPERADMIN_PASSWORD. Name clashes are an error, never a silent overwrite. Plaintext exports need confirmation (--yes in scripts), are written with mode 600, and are refused inside a git repo unless the file is gitignored. For scripts, set the bundle passphrase with CVAULT_BUNDLE_PASSPHRASE. Export is deliberately not an MCP tool, so Claude can't dump the vault. In the explorer: Export… on the home page and on each project page.

Directory linking

cvault project bind links a directory (and its subdirectories; the most specific link wins) to a project. This drives short refs, the explorer's start page and the SessionStart hook.

Security model

• Crypto: master password → scrypt (N=2¹⁷) → key-encryption key, which wraps a random 256-bit data key. Every value and file is encrypted with AES-256-GCM, with the item's UUID as additional authenticated data. Metadata (names, roles, bindings) is stored unencrypted, so the session hook needs no password.

• Master password comes from the macOS Keychain via VAULT_MASTER_PASSWORD_CMD, and is removed from the server's environment at startup so child processes never inherit it.

• Claude never sees values by default. Injected secrets are scrubbed (raw, base64 and URL-encoded) from command and HTTP output. reveal_secret is off per project, and only the CLI can turn it on.

• Sealed mode: values travel through native macOS dialogs or the clipboard, never through tool arguments or results. They're passed to osascript via env, not argv.

• Guardrails: .env and file writes into a git repo are refused unless the file is gitignored, and files are written with mode 0600.

• Audit log of every use, reveal, copy and edit. It never records values.

Limit: scrubbing keeps secrets out of the conversation and transcripts. It is not a sandbox, so a command can still misuse an injected secret on purpose. Review commands that come from untrusted content.

Development

npm run build        # tsc → dist/
npm test             # vitest (crypto, versioning, archive, roles, export/import, injection, scrubbing)
npx @modelcontextprotocol/inspector node dist/index.js

src/
  index.ts    MCP server (tools, sealed mode, reveal gate)
  cli.ts      cvault CLI + SessionStart hook
  ui.ts       interactive explorer
  store.ts    vault: hierarchy, versioned items, archive, roles, audit
  crypto.ts   scrypt + AES-256-GCM
  inject.ts   run / .env / file / http injection + scrubbing
  sealed.ts   macOS dialogs + clipboard with auto-clear
  export.ts   encrypted bundles, .env / JSON export, bundle import
  enforce.ts  server-side rules: auto-prompt, allowed hosts, use budget, 401 lock
  policy.ts   host matching / extraction, budget constants
  table.ts    table rendering
  db.ts       SQLite schema + migrations

License

MIT © 2026 shahroz Dhillon