Skip to content
EN
Add to Chrome

Connect a Hermes agent

How-toNew

For anyone who runs a Hermes agent on a computer of their own and wants to talk to it from Riff Home. Agents are for Chat only: Riff never sends a reply or a post to one, because those carry text from the web and an agent can run commands.

Add the agent, add the line the card shows to its .env, restart the gateway, and it connects.

1. Turn on Hermes' API server

On the agent's computer, add these lines to ~/.hermes/.env:

LineWhat it does
API_SERVER_ENABLED=trueTurns on the API server Riff talks to (port 8642)
API_SERVER_KEY= and a long random keyThe key Riff will send. Anyone with this key and the address can use your agent
API_SERVER_CORS_ORIGINS=chrome-extension:// and Riff's IDLets this copy of Riff in (step 3 shows the exact line)

Add API_SERVER_HOST=0.0.0.0 only if Riff reaches the agent over your network rather than a tunnel.

2. Restart the gateway

The API server is part of the Hermes gateway. From a terminal on that computer, run hermes gateway restart (or start it with hermes gateway).

  • Not hermes serve: that runs the dashboard, not the API server.
  • Restart it from a plain terminal. Asking the agent to restart its own gateway ends the session it's running in.

3. Add it in Riff

  1. In Riff Home › Models, click Add on Add a model app.
  2. App: Hermes agent. Address: where it answers, like 192.168.1.30:8642 or your tunnel's agent.yourdomain.com. API key: the API_SERVER_KEY from step 1.
  3. Click Save and connect and allow the browser's question about that address.
  4. The card reads Connected and Chat with this agent. You're done: see Chat with your agent.

"Needs one setting": the extension-ID line

Hermes lets anyone with the key read its list of models, but it only acts for browser extensions it knows. So the card can find the agent while every chat message is refused. Riff checks for this, and the card then reads Needs one setting with the exact line, Riff's own ID included:

API_SERVER_CORS_ORIGINS=chrome-extension:// followed by Riff's ID.

  1. Copy the line from the card into ~/.hermes/.env. If the line is already there, add the new ID after a comma.
  2. Run hermes gateway restart.
  3. Click Connect on the card.

The ID belongs to this copy of Riff in this browser. Riff in another browser, or loaded again as a new copy, has its own ID and needs its own entry.

Reach it from anywhere: a tunnel

A tunnel gives the agent an https address without opening a port on your router. With a Cloudflare Tunnel, route a hostname to the agent's port on that computer. In ~/.cloudflared/config.yml:

  • hostname: agent.yourdomain.com
  • service: http://localhost:8642

Then add agent.yourdomain.com in Riff as above. The agent can keep listening on localhost, so you don't need API_SERVER_HOST. Through a tunnel, what you type passes through Cloudflare to your computer.

Keep the key safe

On a tunnel, the key is the only lock between the internet and an agent that can run commands on your computer.

  • Use a long random key, and change it if it may have leaked.
  • Riff keeps it apart from your other settings, where only Riff's own pages can read it. It is never in a backup or in Copy agent log.
  • Trim the agent's list of commands it may run without asking. Riff shows the agent's approval requests Chat with your agent, but only for what the agent asks about.