First Safe Agent bootstrap
bootstrap previews env imports, imports approved credentials, summarizes policy posture, and prints next commands without exposing secret values.
v0.20.0 • Hermes Secret Source Plugin • startup credentials
From .env to safe agent access.
Bootstrap a messy plaintext env file into an encrypted local vault, explain every access decision, route approvals through an audit trail, bind env handoffs to leases, and prove recovery before the incident. Less key sprawl, fewer auth lies, fewer agent mistakes.
- Bootstrap .env safely
- Policy-scoped access
- Ephemeral env injection
- MCP provider readiness
Current Release
0.20.0
Mapped startup secrets through `hermes_vault`, with protected bootstrap passphrases, redacted errors, and MCP still handling in-loop access.
Operator Loop
Prove recovery
Maintenance reports refresh + health, while recovery proof lives in backup verification and restore drills.
Storage Engine
SQLite + PBKDF2
Credentials stay local and encrypted under your master passphrase.
Local State Path
~/.hermes/hermes-vault-data
Redirection supported via the
HERMES_VAULT_HOME variable.
First Safe Agent Flow
The safe path is now one guided loop.
Preview a plaintext env file, import only the approved entries, generate the agent contract, and broker short-lived access without dumping raw secrets into the agent context.
Bootstrap Preview & Import Simulator
project-directory/.env (Source File)
# Local Environment Variables
DATABASE_URL=postgresql://localhost:5432/main
OPENAI_API_KEY="<plaintext demo key>"
GITHUB_TOKEN="<plaintext demo token>"
PORT=4175
local-hermes-vault (SQLite DB)
Vault is locked & empty. Run a scan.
Model Context Protocol (MCP) Tool Lifecycle
Stage 01
Agent Tool Call
Autonomous agent requests env variables via the get_ephemeral_env tool.
Stage 02
Policy Check
Vault verifies the calling agent ID against permissions in policy.yaml.
Stage 03
Transient Injection
Key is safely materialized in agent environment for a TTL-bounded duration.
IdleWhat it does
A concrete boundary between plaintext secrets and agent work.
Hermes Vault now gives operators a single onboarding rail: redacted env preview, encrypted local storage, policy doctor checks, skill contract generation, and MCP tools that keep raw secrets out of the chat loop.
Least-Privilege Policy
policy doctor checks policy.yaml rules for agent capabilities, policy drift, and wildcard credential access.
Ephemeral environments
Brokers transient key injection into environment variables with a strict Time-to-Live (TTL) countdown constraint.
Headless OAuth paths
Use oauth login --headless or MCP oauth_device_login for device-code first login where providers support it.
MCP Server protocol
Exposes tools like verify_credential and get_ephemeral_env to Claude Desktop, Cursor, and LLM hosts.
Local console dashboard
dashboard serves a secure browser layout from packaged assets, keeping secret payloads out of the DOM.
Reality check
Local security is local security.
No cloud sync. No central server audits. Destructive vault actions, raw key updates, and policy edits are locked to the local CLI, keeping browser dashboards strictly read-only and metadata-focused.
Multi-profile isolation
Allows absolute vault database and policy configuration separation using the --profile argument.
Token-guarded console
The console dashboard binds to 127.0.0.1 and generates a process-local token required for all API calls.
Recovery drills
Verify backup age, check backups, and run non-mutating restore drills using the backup-verify utility.
Console Dashboard
Visual visibility without secret exposure.
The redesigned local console renders health statistics, onboarding previews, credential inventory, policy posture, recovery drills, leases, and audit activity on localhost, keeping raw key payloads fully redacted.
The published screenshot set below reflects the v0.18.0 console baseline and preserves the local-only, token-guarded boundary. The v0.20.0 release keeps this archive until a fresh capture set lands.
Hermes Secret Source plugin
Mapped startup credentials, not another in-loop agent API.
Hermes Vault now materializes explicit hv:// refs at startup. MCP remains the in-loop agent control plane, while Secret Source is only for bootstrap credentials.
Mapped only
Use ENV_VAR=hv://service or ENV_VAR=hv://service?alias=name. No bulk export, no refresh, no write-back.
Non-interactive fetch
The plugin shells out through Hermes run_secret_cli() to hermes-vault secret-source fetch with stdin closed.
Protected bootstrap
HERMES_VAULT_PASSPHRASE stays available to startup, empty secrets are omitted, and partial successes stay warnings.
Sample config
secrets:
sources: [hermes_vault]
hermes_vault:
enabled: true
binary: hermes-vault
agent: hermes
ttl_seconds: 900
timeout_seconds: 30
home: ~/.hermes/hermes-vault-data
policy: ~/.hermes/hermes-vault-data/policy.yaml
env:
OPENAI_API_KEY: hv://openai
GITHUB_TOKEN: hv://github?alias=workMigration path
Move mapped startup credentials out of ~/.hermes/.env and into the plugin config. Leave only bootstrap vars like the passphrase in the startup environment.
Discovery timing
The first Hermes process that installs or discovers the plugin may not use it until the next Hermes process starts because plugin discovery happens after startup env loading.
Security posture
Non-interactive fetch, protected bootstrap passphrase, no empty overrides, no bulk export, and redacted errors on partial or denied startup attempts.
Operator installation
Safe installations, editable development setups.
Hermes Vault requires Python 3.11+. Install it, bootstrap your first env file, then let agents request scoped access through policy and recovery checks.
Production Install
uv tool install git+https://github.com/asimons81/hermes-vault.git@v0.20.0
hermes-vault bootstrap --from-env .env --agent hermes --dry-run
hermes-vault bootstrap --from-env .env --agent hermes
hermes-vault policy explain hermes openai --action get_env
hermes-vault request access openai --agent hermes --purpose "release check" --ttl 600
hermes-vault lease checkout openai --agent hermes --purpose "release check" --ttl 600Installation Scope
Installs the CLI inside an isolated tool context and starts with a non-mutating bootstrap preview on the latest release.
Safe bootstrap
The bootstrap report is redacted, policy-aware, and explicit about skipped env names and next steps.
Contributor Workflow
git clone https://github.com/asimons81/hermes-vault.git
cd hermes-vault
uv sync --extra dev
uv run pytest tests/ -qLocal Development
Creates a synchronized editable environment with developer hooks and unit tests configured.
Testing Invariants
Never write real passphrases, databases, or provider token payloads into logs or test assets.
Release & status history
Proven CLI commands and production releases.
Hermes Vault has an active release trail. The local changelog tracks security fixes, command line updates, dashboard improvements, and recovery proof.
Current Release
v0.20.0
Hermes Secret Source Plugin: mapped startup env materialization, protected bootstrap passphrases, non-interactive fetches, redacted errors, and MCP kept for in-loop access.
Operator Workflow Convergence with dry-run dashboard onboarding preview, recovery diff drills, searchable credential/lease/audit views, MCP vault://status, and fixes for lease metrics, key validation, and OAuth login state isolation.
Lease Assurance with health visibility, scheduled cleanup, policy drift detection, backup lease diffing, and full lease lifecycle coverage.
Agent Access Lifecycle with lease issue/renew/revoke workflows, policy pack templates, and dashboard/MCP surfacing for access metadata.
EvoLink provider support with canonical service ID mapping and provider-specific verification.
Agent OAuth freshness: broker auto-refreshes near-expiry OAuth tokens before env handoff. OAuth refresh metadata, 30s refresh cooldown, and policy-gated via the rotate service action.
Native Windows support with HERMES_VAULT_DPAPI=1 master-key wrapping, a new _platform.py abstraction layer, and full docs/windows.md install, OAuth, backup, and Task Scheduler guides.
Credential lifecycle and recovery with maintain, policy doctor, backup-verify, and restore --dry-run.
OAuth readiness with oauth doctor, live health --verify-live, and MCP oauth_provider_status.
First Safe Agent bootstrap, oauth login --headless, and MCP device-login parity.
Explicit OAuth device-code login for headless shell sessions.
Unattended OAuth auto-refresh engines and generic custom verifiers.
Multi-vault profile support, file-based verifier plugins, tags and notes.
Hermes Vault Console local browser dashboard with safe action boundaries.
Policy doctor auditing tool, backup-verify drills, and Systemd integration helpers.