How Do I Connect Hermes Agent to WaveBrain?
Connect Hermes Agent to WaveBrain as a remote MCP server: the config.yaml block, the .env key, the restart command, how to confirm it works and fixes.
Reviewed by WaveBrain Operations TeamReviewed 6 min read
The short answer
To connect Hermes Agent to WaveBrain, add WaveBrain as an HTTP MCP server under mcp_servers in ~/.hermes/config.yaml, put your API key in ~/.hermes/.env as WAVEBRAIN_API_KEY, and run hermes gateway restart. Setup takes about five minutes, and Hermes then logs its actions to one WaveBrain timeline with tools like log_action, start_session and list_actions.
Hermes is often the agent that runs while you're away. It answers support email from a home server, posts on a schedule, or works through a queue on a VPS, and when you come back the only record is its own session history on that machine. If a customer asks why they got a refund, you want to see what the bot did without logging into the box.
Hermes supports remote MCP servers natively, so connecting it to WaveBrain is a config change rather than a plugin install. The steps below use the exact block from the WaveBrain Setup page.
How do I connect Hermes Agent to WaveBrain?#
Add a wavebrain entry under mcp_servers in your Hermes config, store the API key in Hermes' .env file, and restart the gateway. The Hermes MCP docs show remote servers configured with a url and a headers map, which is the shape WaveBrain uses, and they confirm that ${VAR} placeholders in headers resolve from environment variables, including everything in ~/.hermes/.env.
Sign in to WaveBrain and open the Setup page in the dashboard (or sign up free first; no credit card needed).
Create an API key. Name it after the machine, for example
homeserver-hermes, and copy it.Add the key to
~/.hermes/.env:WAVEBRAIN_API_KEY=<YOUR_API_KEY>Add this block to
~/.hermes/config.yaml:mcp_servers: wavebrain: url: "https://getwavebrain.com/api/mcp" headers: Authorization: "Bearer ${WAVEBRAIN_API_KEY}"Restart the gateway with
hermes gateway restart. In a chat that is already open,/reload-mcpalso reloads MCP servers.Ask Hermes to log a test action and check the WaveBrain timeline (see the confirm steps below).
If you already have other servers under mcp_servers, add wavebrain as one more entry under the same key rather than a second mcp_servers block. The Setup page also has an "Add to Hermes desktop" link if you use the desktop app.
What do I need before I start?#
You need Hermes Agent installed, a WaveBrain account and one API key. MCP support ships with the standard Hermes install, according to the Hermes docs, so there is nothing extra to add. WaveBrain's free plan includes 1,000 actions a month, 7 days of history and 2 API keys.
The WaveBrain endpoint is https://getwavebrain.com/api/mcp, a stateless Streamable HTTP MCP server that authenticates with Authorization: Bearer <API key>. Hermes needs outbound HTTPS access to getwavebrain.com, which most servers and VPSs already have.
It helps to decide on names before the first log. Pick an agent name such as hermes-support and a project name such as northwind/support, and use the same ones on every machine. Agent names are stored lowercase, and the timeline filters by agent, project and action type, so consistent names are what make those filters useful once Claude Code, cron scripts and other agents log to the same workspace. WaveBrain only stores what Hermes sends in a log call. It never signs in to the inbox or accounts Hermes works in.
How do I set it up for a Hermes profile?#
Use the profile's own files. The Hermes profiles docs say each profile is a separate Hermes home directory with its own config.yaml, .env, SOUL.md, memories and sessions, so a profile at ~/.hermes/profiles/<name>/ needs the block in ~/.hermes/profiles/<name>/config.yaml and the key in ~/.hermes/profiles/<name>/.env.
Then restart that profile's gateway with hermes -p <name> gateway restart. If you run several profiles (a support bot and a research agent, say), give each one its own agent name in its instructions so the WaveBrain timeline shows them apart. Each profile can share one API key, or use separate keys if you want to revoke them separately.
How do I confirm Hermes is logging to WaveBrain?#
Ask Hermes to log a test entry and look for it in the dashboard. Hermes prefixes each MCP tool with mcp and the server name, so WaveBrain's five tools show up with wavebrain in their names, ending in log_action, start_session, end_session, list_actions and list_recent_actions.
- In a Hermes chat, ask: "Log a test action to WaveBrain with type other, title 'Connected Hermes to WaveBrain', and project setup."
- Open the WaveBrain dashboard. The entry should appear at the top of the timeline with agent, project, time and status.
- Ask Hermes to call
list_recent_actions. It should return the entry you just created.
After that, Hermes logs on its own. The WaveBrain server's instructions tell agents to call log_action right after any action with external effects, such as emails, posts, deploys or config changes, and to skip pure reads. For a firmer rule, paste the logging rules block from the Setup page into the profile's SOUL.md or system prompt.
Why isn't Hermes showing the WaveBrain tools?#
The usual cause is a config that Hermes didn't load, either because of the YAML shape or because the gateway wasn't restarted. Hermes' docs list the possible causes of missing tools as a failed connection, failed discovery, a filter that excluded the tools, or a disabled server.
| Symptom | Likely cause | Fix |
|---|---|---|
| No WaveBrain tools after editing config | Gateway still running the old config | Run hermes gateway restart or /reload-mcp |
| Config pasted from Cursor or Claude | JSON mcpServers shape | Use YAML under mcp_servers, as above |
| 401 or connection rejected | Key missing from .env, or a typo | Check WAVEBRAIN_API_KEY in the right .env, then run hermes mcp test wavebrain |
| Works in default Hermes, not in a profile | Block or key added to the wrong home | Edit the profile's own config.yaml and .env |
| Server skipped or some tools missing | enabled: false, or a tools include or exclude filter | Remove the flag or adjust the filter |
| Actions rejected later in the month | Monthly quota reached | Free plan limit is 1,000 actions a month |
The Hermes docs describe hermes mcp test <name> as the command that reports what a remote server actually answered, including the HTTP status, so it is the fastest way to tell a bad key (401) from a network problem. A server entry must have either url or command, so don't add a command line to the WaveBrain entry.
If WaveBrain is ever unreachable, Hermes keeps working. The log_action call returns an error and the task continues. For other agents on other machines, see tracking agents across machines.
When Hermes is the agent you trust to work unattended, a record of what it did is worth five minutes of setup. Start free, paste the block, and the next email or post Hermes sends will show up in your timeline. You can also connect Slack to hear about failures as they happen.
Frequently asked questions#
Where does Hermes keep its MCP server config?#
In ~/.hermes/config.yaml under the mcp_servers key, or in a profile's own config.yaml under ~/.hermes/profiles/<name>/.
Can I put the API key directly in config.yaml?#
It works, but keeping it in .env and referencing it as ${WAVEBRAIN_API_KEY} keeps the secret out of a file you might share or back up. Hermes resolves the placeholder from ~/.hermes/.env when it connects.
Do I need to restart Hermes after changing the config?#
Yes. Run hermes gateway restart, or hermes -p <name> gateway restart for a profile, or use /reload-mcp in an open chat.
Does WaveBrain see my Hermes conversations?#
No. WaveBrain never receives prompts, responses or conversations. It stores only what Hermes sends in a log call, such as the title, details, project, link and status.
Can Hermes read what other agents logged?#
Yes. Hermes can call list_actions or list_recent_actions to see actions logged by any agent in your workspace, within your plan's history window.