HERMES AGENT MANUAL

Secrets & Credential Security

Where Hermes keeps API keys, how to pull them from an external secret manager, and how the optional egress proxy keeps them out of sandboxes.

Where Credentials Live

Provider API keys are stored in your profile's .env file under ~/.hermes/ — not hardcoded into scripts or committed to repositories. Hermes loads that file at process startup. Check which provider keys are configured with hermes status, and keep the file permissions tight (chmod 600 ~/.hermes/.env).

[SECURITY BOUNDARY]

There is no single "vault" command that brokers short-lived key leases. Instead, Hermes offers three real, configurable surfaces for credential security: external secret managers (hermes secrets), the optional sandbox egress firewall (hermes egress), and supply-chain auditing (hermes security). All are covered below.

External Secret Managers

Pull API keys from Bitwarden Secrets Manager or 1Password at process startup instead of keeping every provider key in ~/.hermes/.env:

terminal

$ hermes secrets --help
usage: hermes secrets [-h] {bitwarden,bw,onepassword,op,1password} ...

Pull API keys from an external secret manager at process startup instead of
storing them in ~/.hermes/.env. Supports Bitwarden Secrets Manager and 1Password.

$ hermes secrets bitwarden setup   # wizard: install bws, store access token, pick project
$ hermes secrets bitwarden status  # show config + token validation
$ hermes secrets bitwarden sync --apply  # pull secrets into the shell environment

Sandbox Credential Isolation (egress proxy)

For remote terminal sandboxes (Docker, SSH, Modal), hermes egress manages an optional TLS-intercepting firewall (iron-proxy). The sandbox holds opaque proxy tokens, never the real keys; iron-proxy swaps the token for the real credential at the network boundary before an outbound request leaves the sandbox. It is disabled by default:

terminal

$ hermes egress setup   # wizard: install binary + CA + mint tokens + write config
$ hermes egress start    # start the managed proxy daemon
$ hermes egress status   # proxy state and token mappings

[SECURITY BOUNDARY]

The token-swap guarantee is bounded: it holds while the sandbox trusts the local CA and traffic reaches the real iron-proxy. If the proxy boundary itself is compromised (stolen CA private key or a hijacked proxy endpoint), the guarantee no longer holds — treat any "nothing can leak" marketing claim with suspicion. Egress protects provider env vars only; it does not inspect arbitrary files mounted into a sandbox.

Supply-Chain Audit

Scan the Hermes virtualenv, plugin dependencies, and pinned MCP servers against OSV.dev advisories:

terminal

$ hermes security audit
On-demand vulnerability scan against OSV.dev. Covers the Hermes venv
(installed PyPI dists), Python deps declared by plugins under
~/.hermes/plugins/, and pinned npx/uvx MCP servers in config.yaml.

[NOTE]

Command output above is taken from hermes --help receipts on Hermes Agent v0.20.0. Full guides: the official Security docs and the Egress proxy docs at hermes-agent.nousresearch.com/docs.