Keep your secrets hidden from AI agents.

When AI agents help you set up services, secrets like API keys and tokens flow through LLM provider servers. agent-vault prevents this by acting as a secret-aware file I/O layer — agents see placeholders like <agent-vault:api-key>, never real values.

┌──────────────────────────────────────────────┐ │ Agent sees: │ │ api_key: <agent-vault:openai-key> │ │ bot_token: <agent-vault:tg-bot-token> │ │ port: 3000 │ ├──────────────────────────────────────────────┤ │ agent-vault │ │ read: real value → <agent-vault:key> │ │ write: <agent-vault:key> → real value │ ├──────────────────────────────────────────────┤ │ Actual file on disk: │ │ api_key: sk-proj-abc123... │ │ bot_token: 7821345:AAF... │ │ port: 3000 │ └──────────────────────────────────────────────┘ 

npm install -g @botiverse/agent-vault

# 1. Store a secret (interactive, masked input) agent-vault set my-api-key # 2. Write a config file using placeholders agent-vault write config.yaml --content 'api_key: <agent-vault:my-api-key> port: 8080' # 3. Read it back — secrets are redacted agent-vault read config.yaml # 1 api_key: <agent-vault:my-api-key> # 2 port: 8080 # 4. The actual file has real values cat config.yaml # api_key: sk-proj-abc123... # port: 8080

Secrets are stored in an encrypted local vault (~/.agent-vault/). When reading files, known secret values are replaced with <agent-vault:key> placeholders. When writing, placeholders are restored to real values. The agent never sees or transmits your secrets.

High-entropy strings not in the vault (like API keys added manually) are automatically detected and redacted as <agent-vault:UNVAULTED:sha256:XXXXXXXX>.

These commands never expose secret values. Both agents and humans can use them.

Read a file with all secrets replaced by <agent-vault:key> placeholders. Output format matches cat -n (line numbers, plain text).

agent-vault read .env # 1 TELEGRAM_BOT_TOKEN=<agent-vault:telegram-bot-token> # 2 OPENAI_API_KEY=<agent-vault:openai-key> # 3 PORT=3000

Write a file, replacing <agent-vault:key> placeholders with real secret values.

# Via --content flag agent-vault write config.yaml --content 'token: <agent-vault:my-token> port: 3000' # Via stdin / heredoc agent-vault write config.yaml <<'EOF' token: <agent-vault:my-token> port: 3000 EOF

Fails with a clear error if any referenced key is missing:

✗ Error: Secret "my-token" not found in vault To add it, the user should run: agent-vault set my-token 

Check if one or more keys exist in the vault.

agent-vault has my-key # prints true/false, exit code 0/1 agent-vault has a b c --json # {"a": true, "b": false, "c": true}

List all stored key names (never values).

agent-vault list # one key per line agent-vault list --json # {"keys": [{"key": "...", "desc": "..."}]}

These commands involve secret values or destructive operations. They require an interactive terminal (TTY) and refuse to run without one. Agents should never execute these — they should tell the user to run them.

Store a secret value. Prompts for masked input. Warns before overwriting an existing key.

agent-vault set telegram-bot-token # Enter value for "telegram-bot-token": •••••••• # ✓ Saved "telegram-bot-token" agent-vault set telegram-bot-token # already exists # ⚠ "telegram-bot-token" already exists (46 chars, set 2025-01-15T14:30:00.000Z) # Overwrite? [y/N] agent-vault set api-key --desc "OpenAI API key" agent-vault set api-key --from-env OPENAI_API_KEY echo "value" | agent-vault set api-key --stdin

View secret metadata, or the actual value with --reveal.

agent-vault get my-key # Key: my-key # Desc: My API key # Set at: 2025-01-15T14:30:00.000Z # Length: 46 chars agent-vault get my-key --reveal # sk-proj-abc123...

--reveal additionally checks that stdout is a TTY — you cannot pipe secret values.

Remove a secret from the vault. Asks for confirmation.

agent-vault rm old-key # Remove "old-key"? [y/N]

Bulk import secrets from a .env file. Shows a preview and asks for confirmation. Short/common values (like localhost, 3000) are automatically skipped.

agent-vault import .env # Found 5 entries: # TELEGRAM_BOT_TOKEN → telegram-bot-token # OPENAI_API_KEY → openai-key # PORT → (skip: too short) # Import 2 secrets? [Y/n]

Initialize the vault at ~/.agent-vault/. Automatically called on first set if no vault exists.

agent-vault init

Audit a file for vaulted and potentially unvaulted secrets.

agent-vault scan config.yaml # Vaulted (2): # line 1: matches "telegram-bot-token" # line 2: matches "openai-key" # Unvaulted suspects (0): # (none)

npx skills add botiverse/agent-vault

The skill teaches agents:

• Use agent-vault read instead of the Read tool for secret-bearing files
• Use agent-vault write instead of the Write tool
• Never execute set, get, rm, import — tell the user to run them
• Use <agent-vault:key-name> placeholders in all config content

User: "Help me set up a Telegram bot" Agent: Let me check if you have the bot token stored. → executes: agent-vault has telegram-bot-token → false Agent: I need your Telegram bot token. Please run this in your terminal: agent-vault set telegram-bot-token You can get the token from @BotFather on Telegram. User: (runs the command, enters token) User: "Done" Agent: → executes: agent-vault write config.yaml --content '...<agent-vault:telegram-bot-token>...' → ✓ Written config.yaml (1 secret restored) Agent: Config created. Your bot token is securely stored and I never saw it. 

All secrets are stored in a single global vault at ~/.agent-vault/:

~/.agent-vault/ ├── vault.json # AES-256-GCM encrypted secrets (per-value encryption) └── vault.key # 256-bit master encryption key (0600 permissions) 

Living in the home directory means secrets are shared across all projects and are never at risk of being committed to version control.

• Secret values never appear in safe command output — enforced by code, not convention
• TTY requirement on sensitive commands — prevents agents from calling set / get --reveal even through prompt injection
• High-entropy detection — unvaulted secrets in files are automatically redacted on read
• Vault outside project tree — lives in ~/.agent-vault/, never at risk of git commit
• Encrypted at rest — AES-256-GCM with per-value encryption
• 0600 permissions — vault files are owner-readable only

Apache-2.0