Connect to Hermes

Hermes lets your OpenHome agent answer questions and run tasks through your local Hermes Agent from Nous Research. You ask a question out loud, Hermes answers using its tools, memory, and skills, and the reply is spoken back in natural, conversational language.

You speak  →  OpenHome (cloud)  →  hermes_bridge.py (your PC)  →  Hermes Agent
                   ↑                                                    │
                   └──────────────────  spoken reply  ─────────────────┘

OpenHome runs in the cloud and can’t reach localhost on your machine, so a small bridge runs on your PC. It holds a WebSocket to OpenHome, forwards each question to Hermes, and sends the answer back. The bridge auto-detects how to reach Hermes and needs no separate API server in the common case. For the lighter-weight terminal alternatives, see Connect to OpenClaw and Local Connect.

What you can build

A voice front-end for your Hermes Agent’s tools, memory, and skills
Hands-free system queries (disk usage, running processes, file lookups)
Conversational research and Q&A with follow-up questions
Voice-driven developer workflows backed by Hermes’ tool calls
Any task your Hermes install can already do — now spoken

How it works

The integration has two pieces:

File	Runs where	Purpose
`main.py`	OpenHome (cloud)	The Ability. Installed from the Marketplace template.
`hermes_bridge.py`	Your PC	Connects OpenHome to local Hermes. All-in-one.

The Ability (`main.py`)

Trigger — you say the wake phrase (e.g. “hermes”). OpenHome activates the Ability.
Intent check — an LLM classifier looks at what you said:
- If you only said the wake word (“hermes”), it asks “What would you like to ask?”
- If you said a full question (“hermes, what’s my disk usage”), it sends that straight to Hermes — no extra prompt.
Conversation loop — after the first answer it keeps listening, so you can ask follow-up questions without repeating the wake word.
Exit — an LLM classifier detects when you’re done (“stop”, “that’s all”, “goodbye”, “never mind”), says goodbye, and hands control back to your normal OpenHome assistant.
Speakable output — Hermes’ raw output (which can contain tables, file paths, and symbols) is rewritten by an LLM into a short, natural spoken reply before it’s read aloud.

The bridge (`hermes_bridge.py`)

On startup the bridge picks a backend automatically:

API mode — if a live OpenAI-compatible endpoint answers (Hermes proxy, Open WebUI, or anything at HERMES_API_URL), it POSTs to /v1/chat/completions.
CLI mode (default for a standard Anthropic / Claude-Code Hermes setup) — if no endpoint is found, it runs hermes -z "<question>" directly as a subprocess. No proxy, no login, no extra server.
Error — if neither a live endpoint nor the hermes binary exists, it reports a clear error instead of failing silently.

It also warms up Hermes at startup (the first agent call is a slow cold start) and auto-falls back from API to CLI mode if a chosen endpoint dies.

Setup

1. Install Hermes

Install the Hermes Agent from Nous Research and follow its setup instructions. Configure it with an LLM API key (Anthropic, OpenAI, etc.) as described in the project’s README. Verify the one-shot mode runs:

hermes -z "say hello"

If that prints a reply, the bridge’s CLI mode will work.

2. Install the bridge dependencies

You need Python 3.8+ on the machine running the bridge:

python3 --version
pip install websockets httpx

3. Get the bridge

hermes_bridge.py. Save it anywhere convenient — ~/openhome/ on macOS/Linux, C:\openhome\ on Windows. The source for both the bridge and the Ability also lives on GitHub: openhome-dev/abilities/templates/hermes.

4. Configure and run the bridge

Set your OpenHome API key

Copy it from Dashboard → Settings → API Keys, then export it before launching the bridge:

export OPENHOME_API_KEY="oh_xxx..."

Run it

python3 hermes_bridge.py

Expected output:

... Probing API endpoint: http://localhost:8645/v1
...   no response.
... No API endpoint found; using CLI mode (hermes -z).
... Warming up Hermes (first call initializes the agent)...
... Hermes is warm.
... Connecting to OpenHome at wss://app.openhome.com/ws/local_link/ ...
... Connected to OpenHome [backend=cli]. Waiting for inquiries.

Keep this terminal open while using the Ability.

Keep it alive across sessions:

macOS/Linux — use tmux or screen, or run in the background: nohup python3 hermes_bridge.py > ~/hermes_bridge.log 2>&1 &
Windows — run in a minimized terminal, or via Task Scheduler

5. Install the Hermes Ability

Add the ready-made Hermes template from the Marketplace:

Open the Marketplace

Dashboard → Marketplace.

Add the Hermes template

Find the Hermes ability template and add it to your account.

Review or tweak (optional)

Open it in the Live Editor if you want to review or customize the code.

Set trigger words

Set Trigger Words — e.g. hermes, ask hermes, hey hermes.

Enable it

Enable the Ability on your agent.

To edit the Ability later, use the OpenHome Live Editor — no re-upload needed.

Using it

Say the wake word, with or without a question:

“Hermes.” “Hermes here. What would you like to ask?” “What’s my disk usage and the biggest folders in my home directory?” “Your main drive is about 72 percent full, with roughly 64 gigabytes free. The largest folders are Videos and Projects, each around 28 gigabytes.” “What time is it?” “It’s 1:42 in the afternoon.” “That’s all, thanks.” “Okay, leaving Hermes. Goodbye.”

You don’t repeat the wake word for follow-ups — the loop keeps listening until you signal you’re done.

Configuration reference

All settings are environment variables (set them before launching the bridge), or edit the constants in Config at the top of hermes_bridge.py.

Variable	Default	Meaning
`OPENHOME_API_KEY`	(required)	Your OpenHome API key.
`OPENHOME_HOST`	`app.openhome.com`	OpenHome host.
`OPENHOME_CLIENT_ID`	`laptop`	Device id; must match the Ability’s `target_id`.
`OPENHOME_ROLE`	`agent`	Connection role.
`HERMES_API_URL`	(empty)	Force API mode against this base URL (e.g. a proxy/WebUI).
`HERMES_API_KEY`	(empty)	Bearer token if your API endpoint needs one.
`HERMES_MODEL`	`hermes-agent`	Model name sent in API mode.
`HERMES_BIN`	`hermes`	Path to the hermes CLI for CLI mode.
`HERMES_CLI_EXTRA`	(empty)	Extra CLI args, e.g. `--yolo` to auto-approve tool calls.
`HERMES_TIMEOUT`	`180`	Seconds to wait for a Hermes answer.
`API_PROBE_TIMEOUT`	`2`	Seconds per endpoint probe at startup.
`HERMES_SPEAKABLE_HINT`	`1`	`0` disables the “answer concisely for speech” hint.
`HERMES_BRIDGE_LOG_LEVEL`	`INFO`	Logging verbosity (`DEBUG`, `INFO`, `WARNING`, …).

Troubleshooting

"I couldn't reach Hermes" (spoken)

The bridge isn’t running, or Hermes isn’t installed/working. Test with hermes -z "say hi".

"No API endpoint and hermes not found" (log)

The hermes binary isn’t on PATH. Install Hermes, or set HERMES_BIN to its full path, or run an API endpoint and set HERMES_API_URL.

First question returns nothing, second works

Cold start. The bridge’s warm-up should prevent this; if it persists, raise HERMES_TIMEOUT.

Tool calls hang in CLI mode

Hermes may be waiting for interactive approval. Run with auto-approve:

HERMES_CLI_EXTRA="--yolo" python3 hermes_bridge.py

Replies are too long / read out raw data

Keep HERMES_SPEAKABLE_HINT=1 (default); the Ability also rewrites output for speech. Ask narrower questions for tighter answers.

Bridge won't connect to OpenHome

Wrong/expired OPENHOME_API_KEY, or your account uses a different local-connect host. Check the dashboard.

Multiple devices

Give each bridge a distinct OPENHOME_CLIENT_ID and pass a matching target_id from the Ability.

Security & privacy

The bridge runs Hermes with your user permissions — it can run shell commands, read/write files, and more. Only trigger it with requests you’d be comfortable running yourself.

--yolo auto-approves tool calls. Convenient for voice, but it removes the manual confirmation step — enable it knowingly.
Treat your OPENHOME_API_KEY as a secret. If it has ever been pasted somewhere public, rotate it in the dashboard.
Anyone with access to your OpenHome account can reach Hermes through your bridge while it’s running.

Architecture

Voice Input → OpenHome Ability (main.py)
                      ↓ WebSocket
              hermes_bridge.py (your PC)
                      ↓
        API mode                CLI mode
   POST /v1/chat/completions   hermes -z "<question>"
                      ↓
                Hermes Agent
            (tools · memory · skills)
                      ↓
        Response ← AI formatting ← Ability

Resources

Hermes Agent (Nous Research): github.com/nousresearch/hermes-agent
Hermes template on GitHub: openhome-dev/abilities/templates/hermes
Download the bridge: hermes_bridge.py
Lighter alternatives: Connect to OpenClaw · Local Connect

​What you can build

​How it works

​The Ability (main.py)

​The bridge (hermes_bridge.py)

​Setup

​1. Install Hermes

​2. Install the bridge dependencies

​3. Get the bridge

​4. Configure and run the bridge

​5. Install the Hermes Ability

​Using it

​Configuration reference

​Troubleshooting

​Security & privacy

​Architecture

​Resources

What you can build

How it works

The Ability (`main.py`)

The bridge (`hermes_bridge.py`)

Setup

1. Install Hermes

2. Install the bridge dependencies

3. Get the bridge

4. Configure and run the bridge

5. Install the Hermes Ability

Using it

Configuration reference

Troubleshooting

Security & privacy

Architecture

Resources