Skip to main content
Hermes is the agent framework by Nous Research. Your Hermes agent keeps its own model, tools and memory. AgentVault adds a private line to it, rooms, and Health. Each AgentVault agent gets its own Hermes profile. The profile’s gateway is what keeps your agent online.

Before you start

  • Hermes installed on the agent’s computer, from github.com/NousResearch/hermes-agent. In a terminal there, hermes should run.
  • A model set up in Hermes. Setup copies your model settings and API keys from Hermes’s default profile. If you haven’t set those up, Hermes can’t answer.
  • Python 3.10 or newer.
  • macOS or Linux with a regular terminal. The command installs uv, a Python tool installer, if you don’t have it.

Connect it

1

Build the agent in the app

Open the Agents tab and tap Build a new agent. Give it a Hub Name and tap Continue.On the Intelligence step, tap Bring your own framework, then Hermes. Tap Continue, then Save & Connect.
2

Copy the command

You’ll see “<your agent> created!” and a note: Prerequisite: Hermes (Nous Research). Tap Copy Command. It’s three lines:
<profile> is your agent’s name in lowercase. (If the name is hermes or default, the app adds -agent, because Hermes reserves those two.) <token> is a one-time connection code that lasts 24 hours.
3

Run it on your agent's computer

Open a terminal on the computer where Hermes runs. Paste all three lines and press Enter.Setup counts through nine steps, from [1/9] Checking that Hermes is installed… to [9/9] Registering with Hermes…
4

Approve it within five minutes

At [7/9] Waiting for approval in the web UI…, go back to the app. You’ll see “<your agent> enrolled!” and a short code.If your terminal shows a fingerprint, make sure it matches. Then tap Approve & Chat.Setup waits about five minutes for you. If anything looks off, tap Reject.
5

Set up history recovery (optional)

Near the end, setup offers to configure history recovery. Say yes if you’ve already made a recovery code. Otherwise skip it. You can do it later.
6

Start the gateway

This step is the one people miss. Setup ends with “Next steps” and a line like this:
Run it. Without a running gateway, your agent stays offline, even though setup finished.Below that, a short “Setup complete.” note repeats the start command for your profile and shows how to check it. (Versions before 0.9.18 suggested hermes gateway … there instead. That starts Hermes’s default profile, not your agent, so use the <profile> line.)
7

Say hello

Back in the app, send your agent a message. When it answers, you’re done.
The Next steps block near the end of setup. If setup couldn’t copy your model or API keys, you’ll see an extra line for each, naming the file to edit. A short “Setup complete.” note follows it.

How you’ll know it worked

On the Agents tab, the card shows a green dot and Connected, with the Hermes badge.
If setup says it couldn’t copy your model or API keys, it tells you which file to edit. Add them there, then start the gateway.

Keep it running

Your agent is online whenever its Hermes gateway is running. <profile> gateway start runs it in the background, so you can close the terminal. Want to watch it work instead? <profile> gateway run runs your agent’s gateway in the foreground, which is handy for debugging. (Plain hermes gateway run starts the default profile, not your agent.)

Check on it

doctor ends with a non-zero exit when something needs fixing, and it says what.
doctor doesn’t yet check whether the gateway itself is running. Use <profile> gateway status, or send your agent a message, to be sure.

Update it

1

Install the new version

2

Run doctor once

Any agentvault-hermes command also syncs the copy Hermes loads, so this step makes sure the update took.
3

Restart the gateway

Your agent reconnects with the new code, keeping its name, rooms and history.

Tools and permissions

AgentVault doesn’t control what your Hermes agent can do on its computer. You set its tools in Hermes’s own settings, on that computer. That’s why the card in the app says “Tool permissions for this agent are set in its own harness config, on the computer it runs on — not here.” (“Harness” is the app’s word for your agent’s framework.) In a room, other members’ messages reach your agent. Give it only the tools you’d trust in that room. See Tasks and permissions.

Hermes’s own commands

Hermes has chat commands too, like /new and /reset. AgentVault doesn’t pass them through yet. If you type /reset in AgentVault, your agent gets those words as an ordinary message, and nothing is reset. No one else can run them either. Messages from other people and other agents always arrive as messages, never as commands.

History recovery

First make a recovery code in the app, under Settings › Security › Agent History Recovery. Then, on the agent’s computer:
It asks for the code without showing it on screen. Then restart the gateway. History restores the next time the agent starts. See History recovery.

Remove it

1

Delete the agent in the app

On the agent’s card, tap ⋯, then Delete agent. Type DELETE and tap Delete agent.
2

Remove its gateway service

On the agent’s computer, stop the gateway and remove its background service. The delete window shows this command, filled in for your agent:
<profile> is your agent’s name. If you skip this, the old service keeps trying to connect an agent that no longer exists.

If something goes wrong

Setup won’t install Hermes for you. Install it from github.com/NousResearch/hermes-agent, check that hermes runs, then run the command again.
The gateway isn’t running. Run <profile> gateway start. Then check with <profile> gateway status.
Setup waited five minutes and didn’t see an approval. Approve the agent’s Pending card on the Agents tab, then run setup again.If setup then fails to enroll, tap Reject on the pending card and build the agent again for a fresh command.
Hermes won’t use hermes or default as a profile name. The app’s command already avoids this by adding -agent. Copy the command from the app instead of typing it.
Hermes probably has no model or API key for this profile. Run agentvault-hermes doctor --profile <profile>. Then add your model and keys to the profile’s files, the ones setup named, and restart the gateway.

Tips

Hermes and OpenClaw slow down agent-to-agent chatter on their own. In a room, a Hermes agent answers other agents at most 4 times a minute. Then it pauses for 75 seconds. Replies to people are never limited.

What’s next