HeyRocky
Protect Docker Credentials with the Hermes Egress Proxy
Rocky keeps real credentials behind the host boundary while opaque tokens cross into the sandbox.

Protect Docker Credentials with the Hermes Egress Proxy

A Docker sandbox normally needs provider credentials to call outside APIs. Placing the real keys inside that sandbox weakens isolation: a compromised process or prompt-injected tool could read the environment and attempt to exfiltrate them. Hermes’ optional egress proxy changes that boundary. The sandbox receives opaque proxy tokens, while the real credentials remain in the host-side proxy process.

The feature is specifically for the Docker terminal backend. It does not protect host-process model calls, and the official documentation does not claim equivalent support for Modal, Daytona, SSH, or Singularity. Treat the proxy’s endpoint integrity and local certificate authority as part of the trusted host boundary.

How the boundary works

The managed iron-proxy process terminates outbound TLS on the host, checks the destination against its policy, replaces a sandbox token with the corresponding real credential, and forwards the request. Hermes mounts the proxy CA certificate into Docker and supplies standard proxy and CA-bundle variables so common HTTP runtimes use that route.

The sandbox still sees familiar provider variable names, but their values are opaque tokens. Those tokens are useful only through the configured trusted proxy boundary; they are not substitutes for protecting the proxy CA key, mappings, process, and listener.

Setup checklist

  • Confirm the workflow uses the Docker terminal backend.
  • Review the threat model and decide which outbound hosts are required.
  • Install the pinned, checksum-verified proxy binary with hermes egress install.
  • Run hermes egress setup to generate the CA and provider mappings.
  • Start the daemon with hermes egress start.
  • Inspect health and uncovered providers with hermes egress status.
  • Keep enforce_on_docker enabled unless an explicit migration requires fallback.
  • Test one harmless provider request from a fresh Docker sandbox.
  • Review the audit log without publishing tokens, credentials, paths, or host details.
hermes egress install
hermes egress setup
hermes egress start
hermes egress status

Security choices that matter

The default posture is fail-closed for Docker: when the proxy is enabled but unavailable, Hermes should refuse to start a sandbox rather than silently placing real credentials back inside it. The upstream deny list also blocks loopback, link-local, cloud-metadata, private, and other sensitive address ranges unless an operator explicitly opts out.

Only add required destinations to proxy.extra_allowed_hosts. Wildcards increase the trust surface and should be narrower than a whole vendor domain when practical. If credentials come from Bitwarden Secrets Manager, keep missing-value fallback disabled unless the migration plan explicitly accepts host-environment fallback.

Common pitfalls

  • Assuming the proxy protects every Hermes backend or host-process model call.
  • Setting enforce_on_docker: false and forgetting that real keys may return to the sandbox.
  • Binding listeners broadly instead of relying on the platform-specific safe bind policy.
  • Adding an overly broad wildcard to fix one blocked endpoint.
  • Copying the CA private key, mappings file, proxy tokens, or audit contents into support output.
  • Treating a running process as proof that HTTPS requests are actually routed and rewritten.
  • Confusing outbound hermes egress with the separate inbound OAuth-oriented hermes proxy command.

Verification steps

  1. Run hermes egress status and confirm the feature is enabled, configured, and running.
  2. Start the actual Docker backend and inspect only variable names—not values—to confirm proxy and CA-bundle wiring exists.
  3. Make an allowed provider request and confirm it succeeds.
  4. Attempt a harmless request to a deliberately unallowlisted test host and confirm policy blocks it.
  5. Stop the proxy and confirm a fail-closed Docker configuration refuses to launch rather than injecting real credentials.
  6. Restart the proxy, repeat the allowed request, and review the audit event for the expected destination without exposing sensitive fields.

Official documentation

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

Related pages