Hermes Vault

Hermes Vault is a local-first credential broker and encrypted vault for Hermes agents. It scans for risky plaintext secrets, stores credentials locally, verifies them before re-auth claims, and generates skill contracts that keep agents on the same workflow.

What It Does

• Scans Hermes-relevant files for plaintext secrets, duplicates, and insecure permissions
• Encrypts credentials in a local SQLite-backed vault
• Brokers access with per-agent policy and ephemeral environment materialization
• Verifies credentials before any re-auth recommendation
• Generates SKILL.md files for Hermes agents and sub-agents

Install

Released CLI installs are safest with an isolated tool manager:

uv tool install git+https://github.com/asimons81/hermes-vault.git@vX.Y.Z
pipx install git+https://github.com/asimons81/hermes-vault.git@vX.Y.Z

For local development, use uv or editable pip:

uv sync --extra dev

Or with pip:

python3 -m pip install -e .[dev]

Hermes Vault targets Python 3.11+.

Update

Check for the latest tagged release without changing the environment:

hermes-vault update --check

Apply a guarded update:

hermes-vault update

hermes-vault update currently auto-updates only for pipx and uv tool installs. Editable/dev installs, generic pip installs, and unknown environments receive an explicit manual command instead of an automatic mutation.

Quick Start

export HERMES_VAULT_PASSPHRASE='choose-a-strong-local-passphrase'
hermes-vault --help
hermes-vault scan --path ~/.hermes
hermes-vault import --from-env ~/.hermes/.env
hermes-vault verify --all
hermes-vault generate-skill --all-agents

Default runtime state lives in ~/.hermes/hermes-vault-data.

MCP Server

Hermes Vault exposes the broker as an MCP (Model Context Protocol) server so that compatible hosts can request credentials programmatically.

hermes-vault mcp

Configure your MCP host (Claude Desktop, Cursor, etc.) to run:

{
  "mcpServers": {
    "hermes-vault": {
      "command": "hermes-vault",
      "args": ["mcp"],
      "env": {
        "HERMES_VAULT_PASSPHRASE": "your-passphrase"
      }
    }
  }
}

All MCP tool calls require an agent_id. The same policy.yaml that gates CLI access also gates MCP access.

MCP Tools

Tool	Description	Policy Gate
list_services	List credentials visible to the agent	capability:list_credentials
get_credential_metadata	Fetch credential metadata (no secrets)	can_read(service)
get_ephemeral_env	Materialise ephemeral env vars	can_env(service)
verify_credential	Verify a credential against its provider	can_verify(service)
rotate_credential	Rotate a credential to a new secret	can_rotate(service)
scan_for_secrets	Scan filesystem for plaintext secrets	capability:scan_secrets

Raw secrets are never transmitted over MCP. The default access pattern is get_ephemeral_env.

Common Commands

hermes-vault scan
hermes-vault update --check
hermes-vault import --from-env ~/.hermes/.env
hermes-vault add openai --alias primary
hermes-vault list
hermes-vault verify openai
hermes-vault broker env openai --agent dwight --ttl 900
hermes-vault audit --agent dwight --since 7d
hermes-vault status
hermes-vault status --stale 7d
hermes-vault status --invalid
hermes-vault set-expiry openai --alias primary --days 90
hermes-vault clear-expiry openai --alias primary
hermes-vault verify --all --format table
hermes-vault verify --all --report ~/.hermes/hermes-vault-data/reports/verify-latest.json

What's New in 0.4.0 — Credential Observability

Audit query CLI

hermes-vault audit with --agent, --service, --action, --decision, --since/--until (relative or ISO date), --format table|json, --limit.

Credential status CLI

hermes-vault status with --stale Nd, --invalid, --expiring Nd, --format table|json. Credentials with no last_verified_at are always stale.

Expiry metadata commands

hermes-vault set-expiry (--days N or --date YYYY-MM-DD) and hermes-vault clear-expiry. Both write audit entries. Expiry round-trips through backup and restore.

Verification report output

hermes-vault verify --all now accepts --format table and --report PATH. Default JSON-to-stdout behavior is unchanged.

Security invariants preserved

No secrets in audit, status, or verification output. No background processes. No auto-rotation. No cloud sync.

What's New in 0.2.0

Canonical Service IDs

All service names are normalized to canonical IDs automatically. open_ai, open-ai → openai; gmail, google_docs → google; gh → github. See docs/operator-guide.md for the full alias table.

Deterministic Credential Selectors

Commands that target a credential accept three forms:

• credential ID (UUID) — always exact
• service + --alias — always exact
• service only — works only when exactly one credential exists for that service

If you have multiple credentials for the same service (e.g. github with aliases work and personal), the CLI fails with an Ambiguous error and asks for --alias or the credential ID.

Commands that use selectors: verify, rotate, delete, show-metadata.

Policy v2

Policy now supports per-service action permissions:

agents:
  dwight:
    services:
      openai:
        actions: [get_credential, get_env, verify, metadata]
        max_ttl_seconds: 900
      github:
        actions: [get_env, verify, metadata]
    max_ttl_seconds: 900

Legacy flat-list format (services: [openai, github]) still works and grants all actions.

Agent Capabilities

Non-service-scoped actions are gated by agent-level capabilities:

Capability	Controls
list_credentials	broker list
scan_secrets	scan
export_backup	backup
import_credentials	import

If capabilities is omitted from an agent's policy, all capabilities are implicitly granted (backward compatible).

Centralized Mutation Paths

All write/destructive operations (add, rotate, delete, metadata) flow through VaultMutations — a centralized, policy-checked, audited mutation layer. The operator CLI path skips policy checks but still produces audit entries.

Configuration

export HERMES_VAULT_HOME=~/.hermes/hermes-vault-data
export HERMES_VAULT_POLICY=~/.hermes/hermes-vault-data/policy.yaml
export HERMES_VAULT_NO_BANNER=1

If you need a starting policy, copy policy.example.yaml into the runtime home and edit the agent allowlists there.

Notes

• The master key is derived at runtime from HERMES_VAULT_PASSPHRASE
• A separate local salt file is stored beside the vault database
• If the database exists but the salt is missing, Hermes Vault fails closed instead of silently re-keying the vault
• Generated skills are review artifacts unless you explicitly install them

More Detail

See docs/architecture.md, docs/threat-model.md, docs/credential-lifecycle.md, docs/operator-guide.md, docs/migration-0.1-to-0.2.md, and docs/update-workflow.md.