Skip to main content
Glama

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)

  • ⌨️ CLIset / get / list / delete / import / export / inject

  • 🤖 MCP Server — AI agents (Claude, Gemini) manage keys via MCP protocol

  • 🐍 Python SDKfrom keyvault import get_secret with os.environ fallback

  • 📁 Scoped — Global keys + per-project overrides

  • 📥 .env Compatible — Import / export .env files


Related MCP server: Agentic Vault

🚀 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`

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_DIRKEYVAULT_HOMEKEYVAULT_MASTER_KEY_BACKENDKEYVAULT_KEYRING_SERVICEKEYVAULT_KEYRING_USERNAMEKEYVAULT_ALLOW_UNSAFE_MASTER_KEY_REGEN

  • MCP 策略相关:KEYVAULT_MCP_ALLOW_LISTKEYVAULT_MCP_ALLOW_GETKEYVAULT_MCP_ALLOW_SETKEYVAULT_MCP_ALLOW_DELETEKEYVAULT_MCP_ALLOW_GLOBALKEYVAULT_MCP_ALLOW_ALL_SCOPESKEYVAULT_MCP_ALLOW_ALL_KEYSKEYVAULT_MCP_ALLOWED_KEYSKEYVAULT_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

A
license - permissive license
-
quality - not tested
D
maintenance

Maintenance

Maintainers
Response time
Release cycle
Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/ylz201/keyvault'

If you have feedback or need assistance with the MCP directory API, please join our Discord server