The hermes peer command is Hermes Agent's built-in way to send direct messages from one agent to another: you register a peer once, then use hermes peer dm to message that agent's canonical Bot Chat and read the reply without ever leaving your own session. It arrived with Hermes Agent v0.21.0 — the "Pantheon" release published on 31 August 2026, per the project's official GitHub releases page — and it quietly changes what a Hermes setup is. Instead of one agent on one machine, you now have a wire protocol for a networked team: your research agent can hand findings to your coding agent, and the reply lands back where you can read it.
📺 Watch: New Hermes Agent Update is SCARY GOOD!
🔥 Get the Agent OS as a free bonus: AI Profit Boardroom members get the full Agent OS zip, prompt libraries, daily tutorials and weekly live coaching calls. → Get inside · Want AI SEO help 1-on-1? Book a free SEO strategy session →
What The Hermes Peer Command Actually Does
According to the official CLI reference in the Hermes Agent documentation, the hermes peer command "manages bot-to-bot messaging across machines". In plain terms: every Hermes install can expose an API server, and the peer system lets another Hermes install talk to it as a first-class citizen — across profiles and gateways, from the CLI or from inside a conversation. The release notes describe the headline use case directly: ask your research bot to hand findings to your coding bot and get the reply back where you can read it.
That matters because agent-to-agent messaging used to require glue code — webhooks, shared folders, or copy-pasting between terminals. The hermes peer command replaces all of that with a registry of named peers and a handful of subcommands. It also slots neatly into the rest of the v0.21.0 "Pantheon" feature set: Bot Mode with named agents and avatars, live orchestration of subagents via delegate_task, and cron jobs with persistent memory, all listed in the same release notes.
Every Hermes Peer Subcommand, Explained
The official CLI reference documents seven subcommands under hermes peer. Here is the full set as documented, with what each one is for:
| Subcommand | What it does (per the official CLI reference) |
|---|---|
| hermes peer add | Registers or updates a peer with a name, a URL and an API key. The URL is saved to config.yaml under bot_peers; the key is stored in the .env file inside your .hermes folder. |
| hermes peer list | Lists your peers and shows whether each one has a key configured. |
| hermes peer dm | Messages the peer agent's canonical Bot Chat and prints the reply. Supports a json flag for machine-readable output; the message falls back to stdin if you do not pass it inline. |
| hermes peer run | Starts a long Bot Chat turn asynchronously and returns its run id, session id and idempotency key. You reuse the same idempotency key when retrying the same request. |
| hermes peer status | Polls an asynchronous peer run and prints its final output when complete. |
| hermes peer stop | Stops the exact asynchronous peer run without targeting another turn. |
| hermes peer remove | Removes a peer from the registry, though the key entry in .env is left in place. |
Two details in that list are easy to skim past and are actually the whole story. First, the split between dm and run: dm is synchronous — fire a message, wait, print the reply — while run is built for long jobs, returning a run id you can poll with status and kill with stop. Second, idempotency keys: because you reuse the key when retrying, a flaky connection never causes the peer agent to do the same expensive job twice. The reference also documents clean exit codes — 0 on success, 1 on delivery or peer failure, 2 on usage errors — which makes the hermes peer command safe to wire into scripts.
If you want multi-agent systems like this doing real work in your business — not just demos — the full Agent OS build, prompt libraries and five live coaching calls a week are inside the AI Profit Boardroom. Want a 1-on-1 plan first? Book a free SEO strategy session and I will map your agent stack with you.
How To Set Up Your First Peer
The setup flow, following the official documentation, looks like this:
- Update both machines to v0.21.0. The docs give hermes update as the standard path — it pulls the latest code, updates dependencies and prompts you to configure new options. Run hermes update with the check flag first if you only want to preview what would change.
- Register the peer. On machine A, run hermes peer add with a name for machine B's agent, its URL (host and port of its API server) and its API server key. Hermes writes the URL into config.yaml under bot_peers and stores the key in the .env file in your .hermes directory.
- Confirm it is wired up. hermes peer list shows the peer and whether its key is configured.
- Send the first message. hermes peer dm with the peer's name and a message prints the reply straight back into your terminal.
Peers can also be addressed per agent — the reference shows the peer name optionally followed by a slash and an agent name — which pairs naturally with Bot Mode's named agents from the same release. If you have a "researcher" and a "writer" defined on one machine, a remote Hermes can message either of them specifically.
📺 Watch: New Hermes Agent OS is Absolutely WILD!
What You Can Build With Agent-To-Agent Messaging
The obvious pattern is the one the release notes name: research-to-build handoffs. A research agent gathers sources all morning, then uses the hermes peer command to hand a brief to a coding agent on a beefier machine. Because run is asynchronous, the research agent does not sit blocked while the build happens — it fires the job, keeps the run id, and polls status later.
Three more patterns fall out of the same primitives:
- Specialist farms. One cheap always-on box runs an orchestrator; heavier peers wake up only for their speciality. Combine this with multi-agent orchestration patterns and the delegate_task live orchestration that v0.21.0 added for subagents.
- Scheduled pipelines. The same release upgraded Hermes cron jobs with persistent memory and continuity — a cron-triggered agent can now dm its peers on a schedule, so a nightly report can be researched on one machine and formatted on another with nobody at the keyboard.
- Memory-aware handoffs. Each peer keeps its own Hermes memory system, so the coding bot remembers your codebase conventions while the research bot remembers your niche — the handoff carries the task, and each side brings its own accumulated context.
Model choice per peer is a real lever here too. Nothing forces every peer onto the same brain: one box can run Hermes on DeepSeek for cheap bulk work while another runs a premium model for final output — v0.21.0 also added six new providers and a model picker, per the release notes. The Goldie Bench write-up covers how these brains compare in hands-on tests if you are deciding which model deserves which role.
Hermes Peer Command vs Bot Mode: Which Do You Need?
These two v0.21.0 features solve different problems, and the distinction is worth being precise about. Hermes Bot Mode is about many named agents with their own avatars and group chats — personalities living inside one Hermes installation, talking to you. The hermes peer command is about separate Hermes installations talking to each other over the network, each with its own config, memory and gateway. You will often use both at once: Bot Mode defines who lives on each machine, and peer messaging is how the machines exchange work. If everything you need fits on one box, start with Bot Mode; reach for peers the moment a second machine, a second profile or a second physical location enters the picture.
📺 Watch: 5 Things You Didn’t Know Hermes Agent Could Do
Practical Notes Before You Wire Agents Together
A few things the documentation makes explicit that will save you debugging time with the hermes peer command:
- Keys live in .env, config lives in config.yaml. If a peer suddenly stops authenticating after you copy a config between machines, remember the two halves are stored separately — hermes peer list will tell you if the key is missing.
- Removing a peer does not remove its key. The reference notes that hermes peer remove leaves the .env key entry in place — worth knowing if you rotate credentials.
- Use the json flag in scripts. dm, run, status and stop all support machine-readable output, and the documented exit codes mean your shell scripts can branch on failure properly.
- Long jobs belong on run, not dm. A synchronous dm that takes twenty minutes is a timeout waiting to happen; run with a stored run id is the supported path.
Where this is heading is hard to miss. In the same week, per its releases page, the project shipped v0.20.6 on 27 August with roughly 525 merged pull requests and then the Pantheon release four days later — the peer layer, subagent orchestration and persistent cron memory landing together is the shape of an operating system for agents, not a chat tool. That is exactly the thesis behind Agent OS: treat agents as a system you own and compound, not a subscription you rent. If you already run Hermes across more than one machine or profile — say a laptop plus a Hermes workspace on a server — the hermes peer command is the missing wiring between them, and it costs you one add command per peer to switch on.
If you want your agents earning while you sleep — peer handoffs, cron pipelines and the full Agent OS working together — check out the AI Profit Boardroom → Build your agent network inside AIPB. And if you would rather talk it through first, book a free SEO strategy session and get a personal roadmap.
