Overview

Agent-Vault is a security layer that prevents AI agents from seeing or transmitting sensitive information to LLM provider servers. It replaces real secrets with placeholders like <agent-vault:key> during agent file I/O, so the agent can read and write configuration files containing API keys, tokens, and passwords without ever seeing their actual values.

This is complementary to #363 (file tool redaction gap). While #363 addresses the defensive/passive layer (masking secrets the agent stumbles upon), this issue proposes an active secret management workflow — the agent intentionally works with vaulted secrets using placeholder syntax, enabling it to write config files, set up services, and manage credentials safely.

The idea comes from evaluating botiverse/agent-vault (Apache-2.0, TypeScript, v0.4.0).

Research Findings

How Agent-Vault Works

Agent-vault acts as a bidirectional redaction layer between the agent and disk:

┌──────────┐    read (redacted)     ┌────────────┐    raw read     ┌──────┐
│   Agent   │◄──────────────────────│ agent-vault │◄───────────────│ Disk │
│  (LLM)   │    write (restored)   │   (CLI)     │    raw write   │      │
│           │──────────────────────►│             │───────────────►│      │
└──────────┘                       └────────────┘                 └──────┘

Agent sees:     api_key: <agent-vault:openai-key>
Disk contains:  api_key: sk-proj-abc123def456...

Safe Commands (agent-accessible, never expose secrets):

• agent-vault read <file> — Returns file content with secrets replaced by placeholders
• agent-vault write <file> --content '...' — Writes file, restoring placeholders to real values
• agent-vault has <key> — Check if a secret exists
• agent-vault list — List all stored key names

Sensitive Commands (TTY-guarded, human-only):

• agent-vault set <key> — Store a secret (masked input, requires interactive TTY)
• agent-vault get <key> — View metadata (--reveal for value, cannot be piped)
• agent-vault import <file> — Bulk import from .env files
• agent-vault scan <file> — Audit a file for unvaulted secrets

Key Technical Features

3-Layer Secret Detection:

1. Pattern Matching — 15+ known API key formats (OpenAI, Anthropic, GitHub, Slack, Stripe, AWS, Telegram, JWT, private keys)
2. Shannon Entropy Analysis — Catches unknown high-entropy secrets (threshold 3.0, min 12 chars)
3. Bigram False-Positive Prevention — ~110 common English bigrams; if ≥30% of character pairs match, the string is classified as "word-like" and skipped (prevents masking "moonshot" or "development")

UNVAULTED Detection: Unknown secrets are replaced with <agent-vault:UNVAULTED:sha256:XXXXXXXX> where XXXXXXXX is a hash prefix. On write-back, the original value is restored by matching against the existing file on disk.

Security:

• AES-256-GCM per-value encryption in ~/.agent-vault/vault.json
• Master key in ~/.agent-vault/vault.key with 0600 permissions
• TTY guards prevent agents from calling set/get --reveal even via prompt injection
• Storage is outside the project tree (prevents accidental Git commits)

Alternatives Considered

Agent-vault has the best fit for our use case because it enables productive secret handling (the agent can write config files with real secrets via placeholders) rather than just blocking access.

Current State in Hermes Agent

What we have:

• agent/redact.py — Regex-based redaction for logs and terminal output (passive, pattern-only)
• tools/approval.py — Dangerous command detection
• tools/file_operations.py — Write deny-list for sensitive paths (~/.ssh/*, ~/.aws/*, ~/.hermes/.env)
• tools/code_execution_tool.py — Strips API keys from child process environment

The gap: No mechanism for the agent to safely write config files that need real secrets. Currently:

1. Agent can't read the secret (it's in .env or masked)
2. Agent asks user to paste the secret → it enters the LLM context
3. Agent writes the secret to the config file → it's in the conversation history

With agent-vault, the flow becomes:

1. User runs agent-vault set my-api-key in their terminal (masked input)
2. Agent writes agent-vault write config.yaml --content 'key: <agent-vault:my-api-key>'
3. The real value is on disk but never entered the LLM context ✓

Implementation Plan

Skill vs. Tool Classification

This should be a skill because:

• The capability is expressed as CLI commands via terminal
• It wraps an external CLI tool (@botiverse/agent-vault, installable via npm/npx)
• No custom Python integration or API key management needed in the harness
• The agent's behavior is guided by instructions (when to use vault read/write vs. regular file ops)

Bundled or Skills Hub? This should be bundled — secret handling is a broadly useful security concern that benefits most users, especially those using Hermes for DevOps, service setup, or any task involving credentials.

What We'd Need

• agent-vault installed via npm install -g @botiverse/agent-vault or invoked via npx
• A skill that teaches the agent when and how to use agent-vault commands
• Integration with the existing read_file/write_file workflow (the skill should instruct the agent to prefer agent-vault read/write for files that may contain secrets)

Phased Rollout

Phase 1: Basic Skill (CLI wrapper)

• Create skill with instructions for using agent-vault read/write/has/list
• Trigger conditions: user mentions secrets, credentials, API keys, .env files, config setup
• Agent guidelines: prefer agent-vault read over read_file for config/env files
• If vault not initialized, instruct user to run agent-vault init and agent-vault set <key>
• Helper script to check if agent-vault is installed, install via npm if needed

Phase 2: Auto-Detection Integration

• Detect when read_file returns content with redacted placeholders (from Security: File Tool Output Redaction Gap — Secrets Exposed via read_file but Masked via Terminal #363)
• Suggest switching to agent-vault workflow for that file
• Auto-detect .env, .yaml, .json, .toml files with credential-like keys
• Proactive: when the agent is about to write a file with what looks like a secret, suggest vaulting it instead

Phase 3: Vault-Aware File Operations

• Optional config flag: vault_aware_file_ops: true
• When enabled, read_file automatically runs content through agent-vault read redaction
• write_file automatically restores placeholders before writing
• This merges the skill's approach directly into the tool layer (may move from skill to tool at this point)

Pros & Cons

Pros

• Solves the write problem: Agent can create config files with real secrets without ever seeing them
• Battle-tested tool: agent-vault has 328+ stars, tests, proper encryption, TTY guards
• Apache-2.0 license: Safe to depend on and recommend
• Low effort Phase 1: Skill wrapper is straightforward — mostly instructions + install check
• Defense in depth: Complements Security: File Tool Output Redaction Gap — Secrets Exposed via read_file but Masked via Terminal #363 (regex redaction) with a more robust approach
• User retains control: Only the user can add/remove secrets via TTY-guarded commands

Cons / Risks

• Node.js dependency: Requires npm/Node.js 18+, which may not be present on all systems
• Extra workflow step: Users must agent-vault set secrets before the agent can use them
• Tool switching complexity: Agent must decide when to use agent-vault read vs read_file — could cause confusion
• Vault key management: If ~/.agent-vault/vault.key is lost, all secrets are unrecoverable
• Young project: v0.4.0, relatively new (Feb 2026) — may have undiscovered issues
• Not Hermes-specific: The agent-vault skill format is designed for generic agents; our skill would need to adapt its instructions

Open Questions

• Should Phase 1 require npm install -g or use npx for zero-install? (npx adds ~3s startup overhead per call)
• Should the skill auto-detect when agent-vault is useful, or only activate when the user explicitly asks about secrets?
• For Phase 3: should vault-aware file ops be a config option or always-on when agent-vault is installed?
• Should we eventually build a Python-native equivalent to avoid the Node.js dependency? (The vault.ts core is ~200 lines of AES-256-GCM + entropy detection — portable to Python)
• How should this interact with the existing write deny-list? (Currently blocks writing to ~/.hermes/.env but doesn't offer an alternative for setting credentials)

References

• agent-vault repo — Source code (Apache-2.0)
• agent-vault SKILL.md — Their own agent skill template
• secretless-ai — Alternative: tool hook-based blocking
• CodeCloak paper — Academic: DRL-based code leakage mitigation
• Security: File Tool Output Redaction Gap — Secrets Exposed via read_file but Masked via Terminal #363 — Related: file tool output redaction gap (complementary)
• Address outbound threats #129 — Related: outbound threat mitigation