External Secret Sources for Hermes

Hermes can load provider credentials from external secret managers at process startup instead of storing every key in ~/.hermes/.env. The local file keeps only the bootstrap credential needed to reach the manager.

Official documentation: https://hermes-agent.nousresearch.com/docs/user-guide/secrets

Source composition

Bundled support includes Bitwarden Secrets Manager and 1Password. Multiple sources can be enabled together, with explicit ordering and deterministic precedence. Hermes labels injected credentials with their origin so setup and model-selection flows can explain where a detected value came from.

Third-party managers belong in secret-source plugins. The plugin fetches values through the documented contract, while Hermes owns timeouts, conflict handling, provenance, and protection of bootstrap tokens.

Secret-source checklist

Keep only the minimum bootstrap token locally.
Scope the manager token to the required project or vault.
Give sources an explicit order when more than one is enabled.
Map secret names to the exact Hermes environment variables.
Prevent one source from unexpectedly replacing another source’s values.
Restart the relevant Hermes process after rotation.
Confirm provenance in setup or model status output.
Retain an emergency recovery path that does not expose secrets in chat.

Pitfalls

Assuming external storage removes the need to protect the bootstrap token.
Enabling broad vault access for one provider key.
Creating ambiguous duplicate names across sources.
Expecting a rotated secret to appear in an already running process automatically.
Installing an unreviewed secret-source plugin with excessive permissions.

Verification steps

Configure one low-risk test secret in the external manager.
Start a fresh Hermes process and confirm the variable is detected with the correct origin label.
Verify the value is not copied into the ordinary local secret file.
Introduce a controlled conflict and confirm the documented source order wins.
Rotate the test value and restart Hermes.
Revoke the manager token and confirm startup fails clearly rather than silently using stale credentials.
Review manager access logs and Hermes redaction behavior.