Hermes Agent Peer to Peer Messaging: The Peer Command Guide (2026)

Run hermes peer add office --url https://your-second-machine:port in your terminal, then hermes peer dm office "status update please" — and the Hermes agent on your second machine receives that message directly in its Bot Chat. That is hermes agent peer to peer messaging in one move: the hermes peer command registers another Hermes gateway as a peer, and from that point your agents can message each other across machines without you acting as the middleman, according to the official Hermes Agent CLI reference published by Nous Research (accessed 18 September 2026).

📺 Watch: NEW Hermes Update Lets You Control Subagents Live

🔥 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 Hermes Agent Peer to Peer Messaging Actually Does

The official CLI reference describes the feature plainly: "Bot-to-bot DMs across machines. Register another Hermes gateway (any machine running the api_server platform) as a peer, then message its agents." In practice, hermes agent peer to peer messaging turns a collection of separate Hermes installs — your desktop, a VPS, a spare laptop running an always-on agent — into a network where any agent can hand work or information to any other. The requirement is simply that the receiving machine runs the api_server platform, which is what exposes a gateway other peers can reach.

This matters because most multi-agent setups on a single machine already have ways to coordinate — subagents, shared workspaces, cron handoffs. The gap has always been between machines. If your research agent lives on a server and your writing agent lives on your desktop, peer messaging is the official, documented bridge between them. It is a different tool from the Hermes MCP server, which connects your agent to external tools and data sources — peer messaging connects agents to other agents.

The hermes peer Subcommands

The CLI reference lists seven subcommands under hermes peer, and between them they cover registration, synchronous chat, and asynchronous jobs:

Two details in the reference are easy to miss and genuinely useful. First, the dm, run and status subcommands all accept a --json flag for machine-readable output, which means you can wire peer messaging into scripts and pipelines rather than reading terminal text. Second, exit codes are defined explicitly — 0 for success, 1 for delivery failure, 2 for usage errors — so automations built on top of the peer command can branch on real signals instead of guessing.

If you want working multi-agent setups without months of trial and error, the AI Profit Boardroom includes Julian's agent configs, prompt libraries and weekly live coaching — check out the AI Profit Boardroom. Want a 1-on-1 plan for your own agent stack and SEO? Book a free SEO strategy session.

Setting Up Your First Peer Connection

Getting hermes agent peer to peer messaging running comes down to three steps, all drawn from the CLI reference:

1. Confirm the target machine runs the api_server platform. The docs are explicit that a peer is "any machine running the api_server platform" — that is the gateway other machines register against. If your second install only runs local chat platforms, there is nothing for a peer to connect to.
2. Register the peer. On the sending machine, run hermes peer add name --url URL, adding --key if the receiving gateway requires one. Running add again for the same name updates the entry, so you can rotate URLs or keys without removing and re-adding.
3. Send a message. hermes peer dm name "your message" lands in the peer agent's Bot Chat. Run hermes peer list at any point to confirm which peers are registered and whether keys are set.

The reference also notes that the Bot Mode messaging protocol automatically discovers registered peers — so once a peer is added, agents operating in Bot Mode can find and use that route themselves rather than needing you to type every dm by hand. That is the point where this stops being a remote-control trick and becomes genuine agent-to-agent communication.

If a connection misbehaves, work through the basics before blaming the peer registry: the hermes doctor command diagnoses common install and gateway problems, and updating Hermes Agent rules out version mismatches between the two machines — the recent 0.21.3 patch notes were largely about session and gateway reliability, so staying current is not optional housekeeping here.

Async Runs: run, status and stop

The dm subcommand is synchronous chat, but the run subcommand is where peer messaging earns a place in real workflows. hermes peer run name "task" starts an asynchronous turn on the peer and hands back a run_id immediately. You then poll hermes peer status name run_id until it reports completion, or kill the job with hermes peer stop name run_id. Because run supports an --idempotency-key flag, a retried request will not accidentally start the same job twice — the reference calls this out for retry safety, and it is exactly what you want when a flaky network sits between your machines.

The shape this enables: a coordinator agent on your main machine fires long research or build tasks at worker agents on other machines, carries on with its own work, and collects results when status says they are done. Combined with the JSON output flag, that loop is fully scriptable.

Targeting Named Agent Profiles

Peer addressing has one more layer. Using the peer name alone targets that gateway's main agent, while a name in the form peer/agent targets a named profile on the same gateway — the reference shows this for dm, run, status and stop alike. So a single remote machine can host several specialised agents, and your messages route to precisely the one you mean. If you keep separate profiles for research, content and operations agents, peer-to-peer messages address each one individually rather than dumping everything on the default agent.

📺 Watch: Automate Anything with The NEW Hermes Skills!

Where Peer Messaging Fits in a Multi-Agent Stack

Peer messaging is transport, not organisation — it moves instructions and results between agents, but it does not decide what your agents should actually do all day. That structure is what Agent OS provides: the roles, files and routines that give each agent a job worth messaging about. And if you are choosing which model brain to run behind each Hermes install before wiring them together, the Goldie Bench write-up covers how the current brains compare in hands-on tests.

A sensible build order: get one agent genuinely useful first — learning Hermes Agent properly beats a sprawling network of half-configured bots — then add a second machine when a clear job exists for it, such as an always-on VPS agent handling overnight work. Peer-to-peer messaging is the last piece you add, not the first. It is also worth knowing what the Nous free tier covers before you spin up extra gateways, since every peer machine still needs its own working inference behind it.

Hermes Agent Peer to Peer Messaging: Quick Answers

Does peer messaging need both machines online? Yes for delivery — dm reports a delivery failure through exit code 1 if the peer cannot be reached. The async run and status pattern tolerates you disconnecting between poll checks, but the peer gateway itself must be reachable when a request lands.

Is a key required? The --key flag is optional in the add syntax, and peer list shows key status per peer — if your gateway is exposed beyond a trusted network, treat the key as mandatory in practice even though the syntax does not force it.

Can it message agents on the same machine? Its documented purpose is cross-machine DMs between gateways; on a single machine, named profiles and subagents already cover most of what you would want it for.

If you want an agent network that actually earns its keep — configs, prompts, and the exact setups behind these tutorials — join the AI Profit Boardroom and get the full Agent OS bonus on the inside. And if you would rather map your AI and SEO stack 1-on-1 first, book a free SEO strategy session.

Real wins from inside the AI Profit Boardroom

See all 3,000+ members →

← Back to all posts