Managing API Keys in Hermes Safely

API keys are the real currency of an agentic workflow: Hermes needs them to reach model providers, search backends, and external services, but a key leaked into logs, a prompt, or a shared config file is a credential compromised. Managing API keys safely in Hermes means keeping them out of plaintext config, out of the model's context, and out of reach of the wrong processes — while still letting the agent use them where they belong.

Hermes' approach to keys is part of a broader secrets story documented across the Configuration, Secrets, Managed Scope, and Egress pages. The guiding principle is simple: keys belong in secret stores and environment, never in the conversational context or in repos.

Where Keys Live: Configuration and Secrets

Core configuration lives in config.yaml, which defines providers, models, API keys, and more. The safe pattern is to keep keys out of the file itself and hold them in environment variables or via the secrets system:

• .env and environment variables — keys defined as environment values are read by Hermes at runtime rather than hardcoded into files that might be version-controlled or shared.
• The secrets system — Hermes offers dedicated secret sources, including Bitwarden Secrets Manager, 1Password, and a command helper secret source. Each source fetches secrets on demand, so keys don't have to persist on disk at all, and the agent retrieves them through the secret manager rather than through a config dump.
• Managed scope — an administrator-pinned, user-immutable directory holds system-level config and secrets. Because it is managed, regular users cannot alter it, which protects production keys from being edited away or exfiltrated through a compromised user session.

Keeping keys out of the model's context matters for the same reason passwords are redacted: an autonomous agent that can read files and echo tool results should not become a channel that leaks credentials back into logs, session databases, or chat.

The Dashboard and CLI

Managing keys is a first-class operation. The Hermes Web Dashboard is a browser-based administration panel for managing not just configuration and API keys, but also MCP servers, messaging pairing, webhooks, the gateway, memory, credentials, sessions, logs, analytics, cron jobs, and skills. It is the single surface for inspecting and rotating keys across a deployment.

The configuration system ties into providers: you configure a provider and its associated key, and the key is referenced at runtime. Environment variable references like OPENAI_API_KEY are the standard mechanism, and the doc references a complete list of all environment variables Hermes Agent uses.

Rotation and Resilience: Credential Pools

For production reliability, Hermes builds rotation and failover into credentials. Credential pools let you pool multiple API keys or OAuth tokens per provider for automatic rotation and rate-limit recovery: when one key is exhausted or rate-limited, Hermes can rotate to the next in the pool. This is both a reliability feature and a security one — keys are shared across a pool rather than a single exposed key bearing all the traffic, and rotation happens automatically.

Egress Control

Keys are only as safe as the outbound requests that carry them. Hermes supports an egress proxy and a dedicated credential-injection proxy (iron-proxy) that act as a firewall for outbound traffic. Beyond restricting which hosts the agent can reach, the credential-injection proxy allows credentials — including API keys — to be injected at approved egress points under management, keeping keys out of the model's context while still authenticating the right requests. For a production deployment, pairing scoped keys with egress control means a leaked key is not enough on its own to make calls.

Safe Defaults, Usable Flexibility

The pattern gives you both safety and flexibility: keys live in .env and secret managers rather than plaintext; managed scope keeps administrator-pinned keys immutable; credential pools add rotation and recovery; and egress proxies firewall where keys can be used. Start from the safe default — environment-provided keys, no keys in the model's context, no keys in repos — and layer on secret sources and pools as your deployment grows.

Key Takeaways

• Keep API keys in environment variables, .env, and the secrets system — never hardcoded into config or repos.
• Bitwarden Secrets Manager, 1Password, and command helper sources fetch keys on demand, so they don't persist on disk.
• Managed scope pins administrator-level secrets that regular users cannot alter.
• Credential pools pool multiple keys per provider for automatic rotation and rate-limit recovery.
• The Web Dashboard centralizes key management; egress proxies control where keys can actually be used.