Configure and Audit Hermes Egress Policy

An egress proxy is only as useful as its policy. Hermes provides safe defaults, but operators still decide which providers may be reached, where real credentials come from, and whether a failed proxy blocks the Docker sandbox. Make those decisions as a reviewed policy rather than accumulating exceptions until requests happen to work.

Start with destinations, not credentials

Inventory the external services the sandbox genuinely needs. Record the exact API host for each provider or MCP service and the workflow that depends on it. The bundled defaults cover common model providers; proxy.extra_allowed_hosts is for deliberate additions. A domain wildcard may be convenient, but it grants every matching host access to the proxy path.

Keep the upstream deny list unless a hermetic test proves a specific need. Its purpose is to prevent the proxy from becoming a path to loopback services, private networks, link-local metadata endpoints, and other addresses that should not be reachable through user-controlled URLs.

Policy checklist

Name every required outbound service and owner.
Use exact hostnames where practical.
Document why each wildcard is necessary.
Preserve the default upstream deny ranges.
Keep the Docker fail-closed setting enabled.
Select either host environment or Bitwarden as the real-credential source.
Keep environment fallback off for a strict Bitwarden posture.
Rotate opaque proxy tokens when their boundary or audience changes.
Protect the proxy state directory and audit log as sensitive host data.
Re-run setup and restart after policy changes so the in-memory daemon receives them.

Credential-source choices

With credential_source: env, the daemon reads real values from the host environment, including the Hermes environment file used during setup and startup. With credential_source: bitwarden, the daemon refreshes mapped values from Bitwarden Secrets Manager when it starts. The latter can improve centralized rotation, but only when the BWS access configuration and project mapping are maintained.

allow_env_fallback: false is the safer strict setting for Bitwarden. If a mapped value is missing, startup fails instead of quietly using an old host value. Enable fallback only as a time-bounded migration decision with an owner and removal date.

Audit without leaking

The audit log should prove that a token was matched, a destination was allowed or denied, and a transform occurred. It should not be copied wholesale into tickets or public posts. Build a redacted review that reports timestamps, result classes, and expected hostnames while excluding tokens, authorization headers, account details, private paths, and unrelated environment values.

Common pitfalls

Using *.example.com when only api.example.com is required.
Removing deny ranges to fix an application that is calling a private or metadata address.
Rotating real credentials but not restarting a daemon that loaded old host values.
Enabling Bitwarden mode while leaving silent environment fallback in place indefinitely.
Assuming a provider’s documented API hostname covers every auxiliary upload or OAuth hostname.
Sharing raw audit logs during troubleshooting.
Editing generated proxy files directly and allowing setup to overwrite undocumented changes later.

Verification steps

Export a redacted list of configured allowed hosts and compare it with the approved inventory.
Run hermes egress status and resolve every uncovered-provider warning.
Test one approved host per workflow with a harmless request.
Test one unapproved public host and one reserved-address fixture; both should be denied.
Restart the daemon and repeat a request to prove policy survives process lifecycle.
Rotate a test mapping in a controlled environment and confirm the old opaque token no longer authorizes the route when rotation is expected.
Review audit-file ownership and permissions on the host without printing its sensitive contents.

Official documentation

https://hermes-agent.nousresearch.com/docs/user-guide/egress/iron-proxy