> ## Documentation Index > Fetch the complete documentation index at: https://docs.openhome.com/llms.txt > Use this file to discover all available pages before exploring further. # Connect to Hermes > Talk to your local Hermes Agent (Nous Research) through an OpenHome voice device — full setup, bridge configuration, and the marketplace template. Hermes lets your OpenHome agent answer questions and run tasks through your local **Hermes Agent** from [Nous Research](https://github.com/nousresearch/hermes-agent). 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](/building-abilities/openclaw) and [Local Connect](/building-abilities/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`) 1. **Trigger** — you say the wake phrase (e.g. *"hermes"*). OpenHome activates the Ability. 2. **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. 3. **Conversation loop** — after the first answer it keeps listening, so you can ask follow-up questions without repeating the wake word. 4. **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. 5. **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: 1. **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`. 2. **CLI mode** *(default for a standard Anthropic / Claude-Code Hermes setup)* — if no endpoint is found, it runs `hermes -z ""` directly as a subprocess. No proxy, no login, no extra server. 3. **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](https://github.com/nousresearch/hermes-agent) 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: ```bash theme={"system"} 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: ```bash theme={"system"} python3 --version pip install websockets httpx ``` ### 3. Get the bridge [hermes\_bridge.py](https://drive.google.com/file/d/1pEwGb4jO9tkS1_7ZwZl62OJ4eUEizwzG/view?usp=sharing). 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](https://github.com/openhome-dev/abilities/tree/dev/templates/hermes). ### 4. Configure and run the bridge Copy it from [Dashboard → Settings → API Keys](https://app.openhome.com/dashboard/settings), then export it **before** launching the bridge: ```bash theme={"system"} export OPENHOME_API_KEY="oh_xxx..." ``` ```bash theme={"system"} 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: Dashboard → **Marketplace**. Find the **Hermes** ability template and add it to your account. Open it in the **Live Editor** if you want to review or customize the code. Set **Trigger Words** — e.g. `hermes`, `ask hermes`, `hey hermes`. 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 The bridge isn't running, or Hermes isn't installed/working. Test with `hermes -z "say hi"`. 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`. Cold start. The bridge's warm-up should prevent this; if it persists, raise `HERMES_TIMEOUT`. Hermes may be waiting for interactive approval. Run with auto-approve: ```bash theme={"system"} HERMES_CLI_EXTRA="--yolo" python3 hermes_bridge.py ``` Keep `HERMES_SPEAKABLE_HINT=1` (default); the Ability also rewrites output for speech. Ask narrower questions for tighter answers. Wrong/expired `OPENHOME_API_KEY`, or your account uses a different local-connect host. Check the dashboard. 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 "" ↓ Hermes Agent (tools · memory · skills) ↓ Response ← AI formatting ← Ability ``` ## Resources * **Hermes Agent** (Nous Research): [github.com/nousresearch/hermes-agent](https://github.com/nousresearch/hermes-agent) * **Hermes template** on GitHub: [openhome-dev/abilities/templates/hermes](https://github.com/openhome-dev/abilities/tree/dev/templates/hermes) * **Download the bridge:** [`hermes_bridge.py`](https://drive.google.com/file/d/1pEwGb4jO9tkS1_7ZwZl62OJ4eUEizwzG/view?usp=sharing) * **Lighter alternatives:** [Connect to OpenClaw](/building-abilities/openclaw) · [Local Connect](/building-abilities/local-connect)