keyvault

<p align="center"> <h1 align="center">🔐 KeyVault</h1> <p align="center"> Lightweight secrets manager for LLM Agents.<br/> 轻量级 LLM Agent 密钥管理工具。 </p> <p align="center"> <a href="#-quickstart">English</a> · <a href="#-快速开始">中文</a> </p> </p>

---

KeyVault manages API keys for AI agents, CLI tools, and automation scripts — replacing scattered .env files with a single encrypted vault.

KeyVault 为 AI 智能体、CLI 工具和自动化脚本提供统一的密钥管理，替代散落各处的 .env 文件。

Quick start doc: QUICKSTART.md

Why KeyVault? / 为什么用 KeyVault？

| Problem | Solution | |---------|----------| | .env files scattered across projects | One encrypted vault at ~/.keyvault/ | | AI agents can't discover which keys exist | MCP Server exposes secrets_list / secrets_get | | No encryption — keys stored as plaintext | Fernet (AES-128-CBC + HMAC-SHA256) | | Manual export KEY=val before running scripts | keyvault inject -- python script.py |

✨ Features

• 🔒 Encrypted — AES encryption at rest, master key in OS keyring (when available) or protected on disk (chmod 600)
• ⌨️ CLI — set / get / list / delete / import / export / inject
• 🤖 MCP Server — AI agents (Claude, Gemini) manage keys via MCP protocol
• 🐍 Python SDK — from keyvault import get_secret with os.environ fallback
• 📁 Scoped — Global keys + per-project overrides
• 📥 .env Compatible — Import / export .env files

---

🚀 Quickstart

Install

pip install keyvault-ai

# With MCP support:
pip install keyvault-ai[mcp]

30-Second Fast Path

# 1) install
pip install keyvault-ai

# 2) save one key (hidden prompt)
keyvault set OPENAI_API_KEY

# 3) run your app with only this key injected
keyvault inject --no-global --key OPENAI_API_KEY -- python app.py

Security Confidence Checklist

# confirm permissions / backend
keyvault info

# move master key to OS keyring and remove local key file
keyvault harden --delete-file

# use project-scoped + least-privilege injection
keyvault set OPENAI_API_KEY --project myapp
keyvault inject --project myapp --no-global --key OPENAI_API_KEY -- python app.py

CLI

# Store a key
keyvault set OPENAI_API_KEY sk-xxxxxxxxxxxxx

# Store with project scope (overrides global for that project)
keyvault set OPENAI_API_KEY sk-yyy --project my-video

# Retrieve
keyvault get OPENAI_API_KEY
keyvault get OPENAI_API_KEY --unmask    # show full value

# List all
keyvault list --all

# Import from existing .env
keyvault import .env

# Intelligently scan .env* and import high-confidence secret-like keys
keyvault scan-env --project myapp --dry-run
keyvault scan-env --project myapp --apply

# Export
keyvault export --output .env

# (stdout export is supported, but be careful with file permissions)
# keyvault export > .env && chmod 600 .env

# Run any command with secrets injected as env vars
keyvault inject -- python my_script.py

# Inject only specific keys (recommended)
keyvault inject --key OPENAI_API_KEY -- python my_script.py

# Vault info
keyvault info

# Harden master key storage (move into OS keyring)
keyvault harden --delete-file

Python SDK

from keyvault import get_secret, set_secret, list_secrets

# Automatically checks vault → falls back to os.environ
api_key = get_secret("OPENAI_API_KEY")

# Save a key programmatically
set_secret("DEEPSEEK_API_KEY", "sk-xxx", description="DeepSeek v3")

MCP Server (for AI Agents)

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "keyvault": {
      "command": "python",
      "args": ["-m", "keyvault.mcp_server"]
    }
  }
}

Available tools: secrets_list · secrets_get · secrets_set · secrets_delete

📚 Complete Usage (Detailed)

CLI Command Reference

| Command | Syntax | Notes | |---|---|---| | Set secret | keyvault set KEY [VALUE] [--project PROJECT] [--desc TEXT] [--stdin] | If VALUE is omitted, KeyVault prompts securely (hidden input). | | Get secret | keyvault get KEY [--project PROJECT] [--unmask] | Default output is masked; --unmask prints full value. | | List secrets | keyvault list [--project PROJECT] [--all] | Metadata-only list (does not print plaintext secret values). | | Delete secret | keyvault delete KEY [--project PROJECT] [--force] | --force skips confirmation. | | Import .env | keyvault import FILEPATH [--project PROJECT] | Bulk import KEY=VALUE lines into vault. | | Smart scan .env* | keyvault scan-env [--project PROJECT] [--file FILE ...] [--root DIR] [--recursive] [--all] [--apply/--dry-run] [--force] | Intelligently detect and import high-confidence secret-like keys from env files. | | Export .env | keyvault export [--project PROJECT] [--output FILE] | --output writes owner-only file (0600). | | Inject env | keyvault inject [--project PROJECT] [--global/--no-global] [--key KEY ...] -- CMD [ARGS...] | Prefer --no-global + repeated --key for least privilege. | | Show info | keyvault info | Shows paths, permissions, key backend, and existence checks. | | Harden key storage | keyvault harden [--delete-file] [--force] | Migrates master key into OS keyring; optionally removes master.key. |

Input Validation Rules

• KEY must be env-style: [A-Za-z_][A-Za-z0-9_]*
• PROJECT must match: [A-Za-z0-9][A-Za-z0-9._-]{0,63}
• Invalid values are rejected before write/read operations.

Common Workflows

1. First-time setup (safe default)

# 1) Save secret via hidden prompt
keyvault set OPENAI_API_KEY

# 2) Verify status and key backend
keyvault info

# 3) If you have legacy file-based key, migrate to keyring
keyvault harden --delete-file

2. Global + project override

# Global default
keyvault set OPENAI_API_KEY sk-global

# Project override
keyvault set OPENAI_API_KEY sk-myapp --project myapp

# Resolve from project scope first
keyvault get OPENAI_API_KEY --project myapp --unmask

3. Safe command injection (least privilege)

# Only inject exactly one key, and skip global scope
keyvault inject --project myapp --no-global --key OPENAI_API_KEY -- python app.py

4. Export and import securely

# Export to owner-only file
keyvault export --project myapp --output .env.myapp

# Import existing dotenv into project scope
keyvault import .env --project myapp

5. Smart scan existing env files (security-first)

# Preview only
keyvault scan-env --project myapp --dry-run

# Import selected candidates
keyvault scan-env --project myapp --apply

Python SDK Reference

| Function | Signature | Behavior | |---|---|---| | Get | get_secret(key, project=None, fallback_env=True) -> str | None | Resolution order: project -> global -> os.environ (optional). | | Set | set_secret(key, value, project=None, description=None) -> None | Creates/updates secret. | | List | list_secrets(project=None) -> list[Secret] | Returns decrypted Secret objects. | | Delete | delete_secret(key, project=None) -> bool | Returns True if record was deleted. |

from keyvault import get_secret, set_secret, list_secrets, delete_secret

set_secret("OPENAI_API_KEY", "sk-xxx", project="myapp", description="OpenAI prod")
token = get_secret("OPENAI_API_KEY", project="myapp", fallback_env=False)
items = list_secrets(project="myapp")
deleted = delete_secret("OPENAI_API_KEY", project="myapp")

Environment Variables

Runtime and storage

| Variable | Default | Purpose | |---|---|---| | KEYVAULT_DIR | unset | Override vault directory path (~/.keyvault fallback). | | KEYVAULT_HOME | unset | Alternative override for vault directory. | | KEYVAULT_MASTER_KEY_BACKEND | auto | Master key backend: auto / keyring / file. | | KEYVAULT_KEYRING_SERVICE | keyvault-ai | Keyring service namespace. | | KEYVAULT_KEYRING_USERNAME | master-key | Keyring account key name. | | KEYVAULT_ALLOW_UNSAFE_MASTER_KEY_REGEN | 0 | Allow forced master-key regeneration when data exists (unsafe, may orphan old secrets). |

MCP policy (all optional)

| Variable | Default | Effect | |---|---|---| | KEYVAULT_MCP_ALLOW_LIST | 0 | Enable/disable secrets_list. | | KEYVAULT_MCP_ALLOW_GET | 0 | Enable secrets_get. | | KEYVAULT_MCP_ALLOW_SET | 0 | Enable secrets_set. | | KEYVAULT_MCP_ALLOW_DELETE | 0 | Enable secrets_delete. | | KEYVAULT_MCP_ALLOW_GLOBAL | 0 | Allow global scope; otherwise project is required. | | KEYVAULT_MCP_ALLOW_ALL_SCOPES | 0 | Allow secrets_list(all_scopes=true). | | KEYVAULT_MCP_ALLOW_ALL_KEYS | 0 | Allow arbitrary key names for get/set/delete. | | KEYVAULT_MCP_ALLOWED_KEYS | unset | Comma-separated key allowlist, e.g. OPENAI_API_KEY,DEEPSEEK_API_KEY. | | KEYVAULT_MCP_INCLUDE_DESCRIPTIONS | 0 | Include secret descriptions in list output. |

Hardened MCP example

export KEYVAULT_MCP_ALLOW_LIST=1
export KEYVAULT_MCP_ALLOW_GET=1
export KEYVAULT_MCP_ALLOW_GLOBAL=0
export KEYVAULT_MCP_ALLOWED_KEYS=OPENAI_API_KEY
python -m keyvault.mcp_server

---

🛡️ Security

| Layer | Detail | |-------|--------| | Encryption | Fernet (AES-128-CBC + HMAC-SHA256) | | Master Key | OS keyring (default if available) or ~/.keyvault/master.key (chmod 600) | | Database | ~/.keyvault/vault.db (values + metadata encrypted) | | Vault Dir | ~/.keyvault/ (chmod 700) or KEYVAULT_DIR / KEYVAULT_HOME override |

⚠️ KeyVault is designed for local development use. For production secrets, use Hashicorp Vault, AWS Secrets Manager, etc.

Known limitations: - Global secrets are accessible across all projects. For MCP, project scope is required by default; avoid enabling global scope unless needed. - Secret metadata is encrypted at rest, but anyone who can access your master key (same user account / keychain access / master.key) can decrypt it. - The MCP Server has no authentication. Use MCP policy env vars to restrict access (defaults are restrictive), and only run it locally. - KEYVAULT_MCP_ALLOW_GET=1 to enable secrets_get - KEYVAULT_MCP_ALLOWED_KEYS=OPENAI_API_KEY,... or KEYVAULT_MCP_ALLOW_ALL_KEYS=1 - KEYVAULT_MCP_ALLOW_GLOBAL=1 to allow global scope (otherwise project scope is required) - If vault data exists but the original master key is unavailable, KeyVault now fails closed (won't silently regenerate a new key). You can override with KEYVAULT_ALLOW_UNSAFE_MASTER_KEY_REGEN=1 (unsafe).

Tip: control master key storage with KEYVAULT_MASTER_KEY_BACKEND=auto|keyring|file (default: auto). Use keyvault info to confirm.

---

快速开始

安装

pip install keyvault-ai

# 含 MCP Server：
pip install keyvault-ai[mcp]

30 秒最快方案

# 1) 安装
pip install keyvault-ai

# 2) 写入 1 个密钥（隐藏输入）
keyvault set OPENAI_API_KEY

# 3) 只注入该密钥运行程序
keyvault inject --no-global --key OPENAI_API_KEY -- python app.py

安全感检查清单

# 检查权限/后端状态
keyvault info

# 将主密钥迁移到系统 Keyring，并删除本地 key 文件
keyvault harden --delete-file

# 使用项目作用域 + 最小权限注入
keyvault set OPENAI_API_KEY --project myapp
keyvault inject --project myapp --no-global --key OPENAI_API_KEY -- python app.py

CLI 命令

# 保存密钥
keyvault set OPENAI_API_KEY sk-xxxxxxxxxxxxx

# 按项目隔离（覆盖该项目的全局配置）
keyvault set OPENAI_API_KEY sk-yyy --project my-video

# 查看密钥
keyvault get OPENAI_API_KEY
keyvault get OPENAI_API_KEY --unmask    # 显示完整值

# 列出所有
keyvault list --all

# 从 .env 导入
keyvault import .env

# 智能扫描 .env* 并自动导入高置信度疑似密钥
keyvault scan-env --project myapp --dry-run
keyvault scan-env --project myapp --apply

# 导出为 .env
keyvault export --output .env

# （也支持输出到 stdout，但请注意文件权限）
# keyvault export > .env && chmod 600 .env

# 注入所有密钥后执行命令
keyvault inject -- python my_script.py

# 仅注入指定 key（推荐）
keyvault inject --key OPENAI_API_KEY -- python my_script.py

Python SDK

from keyvault import get_secret, set_secret

# 自动查 vault → 降级到 os.environ
api_key = get_secret("OPENAI_API_KEY")

# 编程设置密钥
set_secret("DEEPSEEK_API_KEY", "sk-xxx", description="DeepSeek v3")

MCP Server（给 AI Agent 用）

在 claude_desktop_config.json 中添加：

{
  "mcpServers": {
    "keyvault": {
      "command": "python",
      "args": ["-m", "keyvault.mcp_server"]
    }
  }
}

可用工具：secrets_list · secrets_get · secrets_set · secrets_delete

📚 完整用法（详细）

CLI 命令总览

| 命令 | 语法 | 说明 | |---|---|---| | 写入密钥 | keyvault set KEY [VALUE] [--project PROJECT] [--desc TEXT] [--stdin] | 不传 VALUE 会进入隐藏输入；--stdin 适合管道。 | | 读取密钥 | keyvault get KEY [--project PROJECT] [--unmask] | 默认脱敏显示，--unmask 显示完整值。 | | 列表 | keyvault list [--project PROJECT] [--all] | 仅显示元数据，不输出明文值。 | | 删除 | keyvault delete KEY [--project PROJECT] [--force] | --force 跳过确认。 | | 导入 | keyvault import FILEPATH [--project PROJECT] | 从 .env 批量导入。 | | 智能扫描导入 | keyvault scan-env [--project PROJECT] [--file FILE ...] [--root DIR] [--recursive] [--all] [--apply/--dry-run] [--force] | 智能识别 .env* 中高置信度疑似密钥并导入。 | | 导出 | keyvault export [--project PROJECT] [--output FILE] | --output 会按 0600 权限写文件。 | | 注入执行 | keyvault inject [--project PROJECT] [--global/--no-global] [--key KEY ...] -- CMD [ARGS...] | 建议 --no-global + --key 最小权限注入。 | | 查看状态 | keyvault info | 查看路径、权限、密钥后端。 | | 强化密钥存储 | keyvault harden [--delete-file] [--force] | 迁移 master key 到系统 Keyring。 |

常用流程

# 1) 首次配置：隐藏输入写入 key
keyvault set OPENAI_API_KEY

# 2) 项目隔离：同名 key 在项目内覆盖全局
keyvault set OPENAI_API_KEY sk-global
keyvault set OPENAI_API_KEY sk-myapp --project myapp
keyvault get OPENAI_API_KEY --project myapp --unmask

# 3) 最小权限注入（推荐）
keyvault inject --project myapp --no-global --key OPENAI_API_KEY -- python app.py

# 4) 文件导出（安全权限）
keyvault export --project myapp --output .env.myapp

Python SDK（详细）

| 函数 | 签名 | 行为 | |---|---|---| | get_secret | get_secret(key, project=None, fallback_env=True) | 查找顺序：项目 -> 全局 -> os.environ（可关闭回退）。 | | set_secret | set_secret(key, value, project=None, description=None) | 新建或更新密钥。 | | list_secrets | list_secrets(project=None) | 返回解密后的 Secret 列表。 | | delete_secret | delete_secret(key, project=None) | 删除成功返回 True。 |

关键环境变量

• 存储相关：KEYVAULT_DIR、KEYVAULT_HOME、KEYVAULT_MASTER_KEY_BACKEND、KEYVAULT_KEYRING_SERVICE、KEYVAULT_KEYRING_USERNAME、KEYVAULT_ALLOW_UNSAFE_MASTER_KEY_REGEN
• MCP 策略相关：KEYVAULT_MCP_ALLOW_LIST、KEYVAULT_MCP_ALLOW_GET、KEYVAULT_MCP_ALLOW_SET、KEYVAULT_MCP_ALLOW_DELETE、KEYVAULT_MCP_ALLOW_GLOBAL、KEYVAULT_MCP_ALLOW_ALL_SCOPES、KEYVAULT_MCP_ALLOW_ALL_KEYS、KEYVAULT_MCP_ALLOWED_KEYS、KEYVAULT_MCP_INCLUDE_DESCRIPTIONS

# MCP 推荐最小权限示例
export KEYVAULT_MCP_ALLOW_LIST=1
export KEYVAULT_MCP_ALLOW_GET=1
export KEYVAULT_MCP_ALLOW_GLOBAL=0
export KEYVAULT_MCP_ALLOWED_KEYS=OPENAI_API_KEY
python -m keyvault.mcp_server

安全设计

• 所有密钥值使用 Fernet (AES-128-CBC) 加密后存储
• Master Key 默认存入系统 Keyring（可用时），或落盘 ~/.keyvault/master.key（权限 600）
• 数据库存储在 ~/.keyvault/vault.db，值和元数据均为密文

MCP Server 默认策略更严格：secrets_list / secrets_get / secrets_set / secrets_delete 默认关闭；按需通过环境变量开启，并建议使用 KEYVAULT_MCP_ALLOWED_KEYS 做 key 白名单。

若检测到 vault 里已有数据但 master key 丢失/不可用，系统会拒绝自动重建新 key（fail-closed）。仅在确认旧数据可丢弃时，才设置 KEYVAULT_ALLOW_UNSAFE_MASTER_KEY_REGEN=1。

⚠️ KeyVault 仅适用于本地开发环境。生产环境请使用 HashiCorp Vault、AWS Secrets Manager 等。

---

📄 License

MIT