Skip to content
vavio

Where should I put a secret my Hermes Agent needs?

Put it in the store Hermes Agent keeps for that kind of secret — never in a chat message, your project instructions (AGENTS.md, SOUL.md) or memory. A model-provider key or a messaging bot token goes in ~/.hermes/.env; a key a specific tool, skill or MCP server needs goes in that component’s own config; a website login, card or two-factor code goes in the encrypted credential vault. Each store is read by the process that needs it, and Hermes keeps the value out of the model’s context, out of the saved transcript, and out of logs by default. Anything you paste into the conversation or a context file becomes part of what the model is sent and what Hermes stores — the opposite of a secret.

This guide follows Hermes v0.23.1, commit 3b42157, checked on 13 November 2026. We reviewed the official source and documentation; we did not run a secret-handling trial on a Vavio computer for this article.

Which store for which secret?

Secret Where it lives Set it with Does the model see it?
Model provider API key (OpenRouter, Anthropic, …) ~/.hermes/.env, or the credential pool in auth.json an env var, or hermes auth add <provider> No — the runtime attaches it to the provider request
Model provider OAuth login (Claude, Codex, xAI, Nous) ~/.hermes/auth.json hermes auth add <provider> --type oauth No
Messaging bot token (Telegram, Discord, Slack) ~/.hermes/.env e.g. TELEGRAM_BOT_TOKEN=… No — the gateway reads it at startup
Key an MCP server needs that server’s env: block in config.yaml edit mcp_servers.<name>.env No — passed only to that subprocess
Key a skill needs ~/.hermes/.env, declared by the skill set the var the skill lists Only inside that skill’s tool runs
OAuth token file a skill needs under ~/.hermes/ the skill’s setup; required_credential_files Mounted to the tool, not printed
Website login, payment card, 2FA seed encrypted vault under ~/.hermes/vault/ a masked prompt, or hermes vault add No — filled straight into the page
A secret you already keep in a password manager stays in Bitwarden / 1Password / a vault a secret-source reference No — resolved into an env var at startup

The rest of this guide explains each row and the one rule they share: the value lives in a store, and only a reference or metadata is ever written where the model can reach it.

A model key or provider login

A key such as OPENROUTER_API_KEY or ANTHROPIC_API_KEY set in ~/.hermes/.env, or in your shell, is auto-discovered on startup and used to call the model. You never put it in a message. For more than one key, or for OAuth logins, use hermes auth add <provider>; Hermes stores pool state in auth.json and rotates keys when one hits a rate or billing limit. A key borrowed from the environment or an external manager is kept as a reference — its source, a label and a non-reversible fingerprint — not as the raw value, so auth.json often holds no secret at all. The model never receives the key in its prompt; the provider runtime adds it to the outbound request.

A messaging bot token

A Telegram, Discord or Slack bot token belongs in ~/.hermes/.env (for example TELEGRAM_BOT_TOKEN), beside the allowlist of who may talk to the bot (TELEGRAM_ALLOWED_USERS=…). The gateway reads these at startup. Pasting a bot token into the chat so the agent can “set it up” does the opposite of what you want: it lands in the conversation the model is sent and in the stored session.

A key a tool, skill or MCP server needs

This is the case the title’s “a secret my Hermes needs” most often means — a weather API, a GitHub token, a Google login for a tool the agent runs.

  • MCP servers receive a filtered environment. Only a short safe list — PATH, HOME, USER, LANG, LC_ALL, TERM, SHELL, TMPDIR and XDG_* — plus the variables you put in that server’s own env: block (and any a secret source you configured supplies) are passed to the subprocess; every other provider key, token or secret Hermes holds is stripped. So a GitHub MCP server’s token goes in mcp_servers.github.env, and an unrelated model key does not leak to it.
  • Skills declare the variables they need (required_environment_variables in the skill’s SKILL.md). You set the value in ~/.hermes/.env; Hermes forwards it to that skill’s commands only while the skill is loaded, and nowhere else. A skill that needs an OAuth token file (Google Workspace, for example) declares required_credential_files, and Hermes mounts the file read-only where the tool runs.

In every case the secret reaches the component that needs it, not the conversation.

A website login, card or 2FA code

When the agent signs into a site, pays, or enters a verification code, that secret belongs in the credential vault, not a message. You save a login once — in a masked prompt the first time the agent hits a sign-in page, or with hermes vault add — and it is encrypted under ~/.hermes/vault/, bound to that site’s origin, and filled straight into the page. Per the upstream guarantee, the password “never enters the model’s context through Hermes: not in tool results, logs, the session database, or the CLI arguments of any process,” and a saved value only fills on the exact origin it was saved for. Card fills ask you each time; a headless session (cron, webhook, the API) cannot confirm and is refused, so an injected instruction on a checkout page can ask but cannot spend. If you already use 1Password or Bitwarden and its CLI is signed in, Hermes picks those logins up automatically — nothing to re-enter.

Keep it in the password manager you already use

You do not have to copy a secret into Hermes at all. A secret source resolves a value from Bitwarden, 1Password or a custom helper into an environment variable at startup — after ~/.hermes/.env loads, before Hermes reads credentials — so the raw secret stays in your manager and only a reference lives on the Hermes computer. For extra model keys this also works by numbering environment variables (OPENROUTER_API_KEY_2, _3, …) that your manager injects; each becomes a pool entry without ever being written to auth.json.

Why not the chat, project instructions or memory?

Because all three are context, and context is exactly what gets sent to the model and stored:

  • A chat message becomes a turn in the conversation. It is saved in the session database (~/.hermes/state.db) and sent to your model provider on that turn and, as history, on later ones.
  • Project instructions (AGENTS.md, SOUL.md) and memory files are loaded into the system prompt. A secret there is sent to the provider on every request and sits in a file in plain text. Hermes even scans context files for prompt-injection and for attempts to read .env or credentials before loading them — but a secret you paste in yourself is not an attack it can catch; it is just an exposed secret.

Hermes reinforces the boundary from the other side. Its file tools refuse to read .env, .env.local, .envrc, auth.json, the vault directory and other credential stores, returning an error and pointing at .env.example instead — so asking the agent “what’s my API key?” does not read it back. Code the agent runs with execute_code gets an environment with KEY/TOKEN/SECRET/PASSWORD/AUTH-named variables stripped out. The local terminal, which runs as your user, strips Hermes’s own provider, gateway and bot credentials by name, so the agent cannot echo a provider key through env — though, being your operator shell, it can still read other variables you set there yourself. And known secret shapes (sk-…, ghp_…, bearer tokens, KEY= assignments) are redacted from MCP tool errors, terminal output and logs.

What the agent can actually read — the honest limit

These stores keep a secret out of the model’s words, the saved transcript and the logs, and withhold it from MCP servers and generated code unless you explicitly grant it. They are not an operating-system sandbox. On the default local backend the agent’s terminal tool runs as your user account, so a command it runs has your permissions; a plugin you install runs inside Hermes and can reach what Hermes can. The vault’s own documentation is blunt: a program or plugin “running as you” can decrypt the vault. The protections are defence-in-depth against leaks and accidents, not a guarantee against code you have told the agent to run. For a hard boundary, run the terminal in an isolated container backend and run unreviewed plugins out of process. And once a password is typed into a website, that site has it, exactly as if you had typed it yourself.

Using this on Vavio

Vavio provides a managed Hermes computer for $14.99 per month, with model usage billed separately by your provider. Its MCP server and CLI let a supported assistant connect a model, check Hermes and recover it — that is the proven path for handing your Hermes its model provider key, and it means you direct the setup through the assistant rather than pasting a key into a chat with Hermes itself. The other stores above — the vault, a bot token in .env, an MCP server’s env:, a skill’s declared variables — are set on the computer through Hermes’s own CLI and config exactly as the official Hermes documentation describes; we have not published a Vavio walkthrough for them and do not claim one here. If you run Hermes yourself, everything above applies directly. Either way, the rule is the same: a secret goes in its store, never in the conversation. Compare the current hosting offer when deciding between managed hosting and running Hermes yourself.

Sources

Written by Vavio with AI assistance and checked against pinned official Hermes v0.23.1 source and documentation. This is a source review, not a live secret-handling trial on a customer computer.

More from the Vavio blog: Hermes Agent guides