Connect a Hermes agent
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.
1. Turn on Hermes' API server
On the agent's computer, add these lines to ~/.hermes/.env:
| Line | What it does |
|---|---|
API_SERVER_ENABLED=true | Turns on the API server Riff talks to (port 8642) |
API_SERVER_KEY= and a long random key | The key Riff will send. Anyone with this key and the address can use your agent |
API_SERVER_CORS_ORIGINS=chrome-extension:// and Riff's ID | Lets 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
- In Riff Home › Models, click Add on Add a model app.
- App: Hermes agent. Address: where it answers, like
192.168.1.30:8642or your tunnel'sagent.yourdomain.com. API key: theAPI_SERVER_KEYfrom step 1. - Click Save and connect and allow the browser's question about that address.
"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.
- Copy the line from the card into
~/.hermes/.env. If the line is already there, add the new ID after a comma. - Run
hermes gateway restart. - 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.comservice: 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.