hermes-voice README

The project's README from github.com/majorminorlabs/hermes-voice. As one markdown file: README.md.

Hermes Voice

Talk to one of your Hermes Agent profiles out loud, through Home Assistant Assist, on an old Amazon Echo running echo-dot-assist.

On an Echo Show, the screen follows along: what it heard, the answer as it is written, the tools Hermes is using, and, when idle, what it is working on in the background. The screen is a web page, so you can make it your own (The Hermes screen).

echo-dot-assist replaces the Alexa client while keeping Fire OS and the Echo's audio processing. Hermes Voice runs on the Home Assistant and Hermes hosts. It connects Assist to a Hermes profile once the Echo has been set up as an Assist satellite.

Echo compatibility: check before buying

[!WARNING] Check the exact model number and installed Fire OS build before buying an Echo for this project. A used unit can already have an Amazon update that blocks its unlock, even if the model is listed below. Ask the seller for a photo of the model label and the full software version. Treat compatibility as unknown if the seller can't confirm the build. A factory reset leaves the installed firmware in place.

The table lists the firmware builds that echo-dot-assist targets. To check a unit before buying, compare its currently installed build, and its bootloader where required, with the linked model guide. Some guides install the target build after unlocking, so the installed build and the target build can differ. Keep a stock unit off Wi-Fi until its model guide calls for a connection.

Echo Model number Target Fire OS build Model guide
Echo Dot 2nd gen (2016) RS03QR 6574.1 (NS65741, build 8146) biscuit
Echo 2nd gen (2017) XC56PY 6.5.7.2 (NS6572, build 6436) radar
Echo Dot 3rd gen (2018) D9N29T 6574.1 (NS65741, build 8138) donut
Echo Input (2018) C1125P 6.5.7.5 (NS6575, build 8338) cupcake
Echo Show 5 1st gen (2019) H23K37 6574.1 (NS65741, build 8149) checkers
Echo Show 8 1st gen (2019) C7H6N3 6.5.7.0 (NS6570, build 6074) crown
Echo Show 5 2nd gen (2021) C76N8S 6574.1 (NS65741, build 8149) cronos
Echo Show 8 2nd gen (2021) A8H3N2 7574.1 (PS75741.7080N, build 7080); the guide also covers builds 7077, 7082 and 7806 athena

Echo Show 5 1st gen (H23K37): Fire OS 6575.1 (NS65751, build 8848) blocks the unlock in our guide. Our working setup used build 8149. See the Echo Show 5 setup notes.

Echo Dot 3rd gen: Look for D9N29T. The 2019 refresh (C78MP8) and the version with a clock (36EBT3) are unsupported. See the upstream Echo model list.

Project components

 Echo (echo-dot-assist)          Home Assistant                        Hermes Agent
 ┌──────────────┐  audio  ┌──────────────────────────────┐  HTTPS/HTTP  ┌─────────────────────┐
 │ wake word,   │ ──────▶ │ Assist pipeline              │ ───────────▶ │ one profile's       │
 │ mic, speaker │ ◀────── │  speech-to-text (Whisper…)   │  /v1/chat/   │ API server          │
 └──────────────┘  audio  │  conversation: hermes_voice ─┼─ completions │ (SOUL.md, memory,   │
                          │  text-to-speech (Piper…)     │ ◀─────────── │  tools, provider)   │
                          └──────────────────────────────┘   reply      └─────────────────────┘

This repo adds only the missing pieces:

Piece What it does
custom_components/hermes_voice Home Assistant conversation agent that sends each turn to a Hermes profile with a stable X-Hermes-Session-Id, so Hermes keeps the conversation. Streams the reply so speech starts early, cleans it for speech, and speaks a short fallback instead of error text.
custom_components/hermes_voice/screen, devices/echo/screen-app The Hermes screen: a page Home Assistant serves with the conversation as it happens, and a small Android app that shows it full screen on an Echo Show.
devices/echo/eye-app, extras/eye Hermes Eye: a small app that lets Hermes use the Echo Show's camera (snapshots, video mode, a REC badge), and the look tool for the voice profile. The setup skill builds it on your computer with your own key.
extras/visual-memory Hermes Visual Memory (a Hermes plugin, or a standalone service): remembers what the Echo Show's camera saw, answers "what changed?" and "where did you last see …?", and shows before/after pictures on the Echo. Off until turned on; local SQLite; the vision model (Codex CLI or a local model such as qwen3.6 through Ollama) looks only when turned on, when the camera is uncovered and when asked.
extras/agent-tasks A read-only view of the other Hermes agents' task boards for a voice profile.
skill/hermes-voice-setup A Hermes skill: your own agent prepares a voice profile, installs/configures Home Assistant + hermes_voice, and verifies it.
docs/changes-and-undo.md Everything Hermes Voice changes in Home Assistant, Hermes and on the Echo, and how to undo each.
docs/voice-profile.md How to set up a dedicated voice profile by hand (SOUL.md, tools, thinking effort, separate provider).
wakeword/ Reproducible pipeline that trains a "hey hermes" microWakeWord model, plus the trained model (wakeword/model/).

Everything else is existing open-source work, used as-is; see CREDITS.md.

How it works

The Hermes screen (Echo Show)

On an Echo Show the home screen becomes Hermes':

The camera and privacy. A ● REC badge shows on the screen whenever the camera is on. The camera's shutter and the mute button always win: with the shutter closed Hermes is told it sees nothing, and mute cuts the camera off in the Echo's kernel, where no app can override it. Pictures go to your voice profile's model only when Hermes looks, and nothing is saved. The camera is off unless something asked for it in the last 15 seconds, or video mode is on.

Make it yours. The screen is one HTML page (custom_components/hermes_voice/screen/: index.html, style.css, app.js) that gets a live feed of events from Home Assistant over its websocket: listening, thinking, each part of the reply, tool calls, timers, background work. Swap the avatar by dropping a picture in Home Assistant's www/hermes_voice/ folder, restyle it, or build something else on the same feed. Open /hermes_voice/screen?demo in a desktop browser to work on it without an Echo.

Set up: devices/echo/README.md. Design, options and the feed: docs/show-screen.md.

What you need

Quick start (let your Hermes agent set it up)

Skill installation is currently blocked by Hermes' security scanner. The command below is the intended installation path, but it does not currently succeed for an unverified community skill. Use the manual install while this is being resolved; do not disable scanning or use a force override. The setup scripts and device guide remain available in this repository. See the scan findings and release check and issue #4.

  1. Install the skill:
    hermes skills install majorminorlabs/hermes-voice/skill/hermes-voice-setup
    
    It carries everything it needs: setup scripts, the Home Assistant integration and the "Hey Hermes" wake word model.
  2. Ask your agent: "Use the hermes-voice-setup skill to make me a voice assistant." It asks you a few questions (which profile, what the voice assistant may do, whether you already run Home Assistant), shows a --dry-run of each step, and then runs:
    voice_profile.py --profile voice --create --write-soul --tools safe --reasoning low --service
    ha_setup.py --profile voice --docker --config-dir ~/hermes-voice/ha-config --set-default
    speech_setup.py --docker --data-dir ~/hermes-voice/speech --set-default --internal-url http://<LAN-IP>:8123 --piper-voice en_US-ryan-high
    verify.py --recall
    
    --tools decides what Hermes may do when spoken to: safe (web search, memory), home (+ Home Assistant control), full (terminal, files, code: for coding by voice) or your own list. See docs/voice-profile.md.
  3. Set up the Echo with echo-dot-assist and switch it to "Hey Hermes" (devices/echo/README.md).

Manual install

  1. Prepare a voice profile and start its API server: docs/voice-profile.md.
  2. HACS → ⋮ → Custom repositories → add this repository's URL, category Integration → install Hermes Voice → restart Home Assistant. Or download hermes_voice-<version>.zip from the release, unzip it into <config>/custom_components/ to create <config>/custom_components/hermes_voice/, then restart.
  3. Settings → Devices & services → Add integration → Hermes Voice: gateway URL, the profile's API_SERVER_KEY, a display name. The URL is validated with GET /v1/models (no model call).
  4. Settings → Voice assistants → your pipeline → Conversation agent → the new Hermes entity. The pipeline also needs speech-to-text and text-to-speech (Wyoming Whisper + Piper, or HA Cloud); speech_setup.py in the skill sets those up.
  5. Options: session mode, idle reset, voice cleanup, voice instruction, fallback message, timeout, optional memory scope key (X-Hermes-Session-Key), stream replies (on), working phrase ("One moment.", said when Hermes starts a tool before saying anything; empty turns it off), tell Hermes the date and time (on: Hermes has no clock, so each turn carries Home Assistant's local date and time).
  6. Recommended: in the pipeline, turn on Prefer handling commands locally. Home Assistant then answers its own sentences at once (the time, timers on the device, lights and other devices) and sends everything else to Hermes. Those answers are Home Assistant's, not Hermes', and Hermes does not see those turns. ha_setup.py --set-default turns it on.

Requires Home Assistant 2026.10 or newer (the version tested).

Devices

We tested Hermes Voice end to end on the Echo Dot 2nd gen (flashed from Windows) and Echo Show 5 1st gen (flashed from an Ubuntu live USB), both with the "Hey Hermes" wake word and Home Assistant in Docker on macOS. The remaining Echo models have upstream support and are untested with Hermes Voice. See the model and firmware table.

Other Home Assistant Assist satellites, such as Voice PE, should work with an Assist pipeline that uses Hermes Voice as its conversation agent. These are untested by this project.

Flashing an Echo with echo-dot-assist can brick it. The Echo Show 5 setup uses a Linux PC and a 16 GB work drive.

The tested Echo Dot 2 required a hardware short after the unlock stalled. The device guide records the Windows driver issue, recovery point, firmware mismatch and subsequent slot inspection. It also explains why matching firmware in both slots does not establish a working fallback. Read the Echo Dot 2 recovery notes before recovering a stalled unlock.

The tested Echo Show 5 needed no opening, but its first unlock run reported success and left it locked; a rerun worked. The device guide has the exact downloads, disk space, timings and the full run (Echo Show 5 notes).

Research log

Everything tested on real hardware is written down in docs/research/: what was checked, the evidence, the decisions and why, and what went wrong.

Known limits

Development

tests/run.sh                   # pytest (pytest-homeassistant-custom-component), ruff, mypy in the pinned HA 2026.10.4 image
tools/sync_skill_assets.sh     # after changing the integration or the wake word model: refresh the skill's copies
tools/build_release.sh         # release files in dist/ (integration zip, skill zip, wake word zip, checksums)

Docs: architecture · voice profile · troubleshooting · what it changes, and undo · decisions

License

The code is MIT-licensed. The bundled hey_hermes.tflite wake word model is for non-commercial use only.

hermes-voice (majorminorlabs/hermes-voice)

Searching Database…

What is this?A way to talk out loud to one of your Hermes Agent profiles through Home Assistant Assist, using an old Amazon Echo running echo-dot-assist as the mic and speaker. On an Echo Show, a screen follows the conversation.
Is it a separate app or an add-on to Home Assistant?Mostly an add-on: a custom Home Assistant integration that acts as a conversation agent and sends each turn to a Hermes profile. It also includes an optional Echo Show screen and a small Android app that runs on the Echo.
How do I get it running?Prepare a voice profile and start its API server (docs/voice-profile.md). Then add the Hermes Voice integration in Home Assistant through HACS or a release zip, enter the gateway URL and the profile's API key, and select it as the conversation agent in your voice pipeline. The one-command skill install is currently blocked by Hermes' security scanner, so the manual install is the working path.
What do I need before starting?A Hermes Agent install with a working model provider (run hermes setup), a Home Assistant install (Docker Desktop on macOS in the example, or an existing one), speech-to-text and text-to-speech for the pipeline (Wyoming Whisper and Piper, or HA Cloud), and a voice device such as an Echo Dot or Echo Show running echo-dot-assist. The Prefer handling commands locally option needs Home Assistant 2026.10 or newer.
Can it control my lights and other devices?Not in v0.1: the integration gives Hermes no Home Assistant tools. To let the agent control devices, give the profile Home Assistant's MCP server. Home Assistant's own local commands, like time or timers, can be handled before Hermes if you enable Prefer handling commands locally, and Hermes doesn't see those turns.
Can I try it without an Echo?Partly. Other Home Assistant Assist satellites, such as Voice PE, should work with Hermes Voice as their conversation agent, but the project hasn't tested them. You can also preview the Echo Show screen in a desktop browser at /hermesvoice/screen?demo.
Which devices does it work with?Tested end to end on an Echo Dot 2nd gen and an Echo Show 5 1st gen, both with the Hey Hermes wake word. Other Echo models have upstream echo-dot-assist support but are untested with Hermes Voice, and some need specific Fire OS builds, so check the model and firmware table first.
Is the camera always watching?No. Hermes Eye is optional. The camera is off unless something asked for it in the last 15 seconds or video mode is on. The shutter and mute always win, a REC badge shows whenever the camera is on, and pictures go to your voice profile's model only when Hermes looks. Nothing is saved; Visual Memory, if you enable it, is a separate feature that stores data locally.
What does the Hermes screen show on an Echo Show?When idle it shows the avatar, the time, timers and Hermes' background work, like running tasks and the next scheduled job. While you talk it shows your words once transcribed, each tool Hermes uses (such as 'Searching the web'), and the reply as it is written.
What if it misheard me?Tap the screen while it is thinking or answering: it stops, says 'Go ahead.' and listens again without the wake word. Hermes is told what it misheard.
Can I restyle the screen?Yes. It is one HTML page (index.html, style.css, app.js) fed by live events from Home Assistant's websocket. You can swap the avatar by dropping a picture into Home Assistant's www/hermesvoice/ folder, restyle it, or build something else on the same feed.
What is Hermes Visual Memory?An optional Hermes plugin, or standalone service, that remembers what the Echo Show's camera saw and answers questions like 'what changed?'. It is off until turned on, stores data in local SQLite, and the vision model looks only when turned on, when the camera is uncovered, or when asked.
Size
0.9 MB
Stars
719
Age
13d
Commits · 90 Days