From 126daf53a8ce3dcfbeaead11ce27f6c47b4a6f81 Mon Sep 17 00:00:00 2001 From: James Pine Date: Sun, 12 Jul 2026 14:48:08 -0700 Subject: [PATCH 1/3] docs: add Hermes Agent integration guide MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit New overview page covering both integration surfaces: the MCP hookup (hermes mcp install voicebox — catalog entry submitted upstream) for agent-invoked speak/transcribe/captures tools, and the hermes-voicebox provider plugin (github.com/jamiepine/hermes-voicebox) that routes Hermes's entire voice pipeline — spoken replies, Telegram voice bubbles, and incoming voice-message transcription — through local Voicebox. --- docs/content/docs/overview/hermes-agent.mdx | 139 ++++++++++++++++++++ docs/content/docs/overview/meta.json | 1 + 2 files changed, 140 insertions(+) create mode 100644 docs/content/docs/overview/hermes-agent.mdx diff --git a/docs/content/docs/overview/hermes-agent.mdx b/docs/content/docs/overview/hermes-agent.mdx new file mode 100644 index 000000000..c1bc81763 --- /dev/null +++ b/docs/content/docs/overview/hermes-agent.mdx @@ -0,0 +1,139 @@ +--- +title: "Hermes Agent" +description: "Use Voicebox as the voice and ears of Hermes Agent — spoken replies and voice-message transcription, fully local." +--- + +## Overview + +[Hermes Agent](https://github.com/NousResearch/hermes-agent) is Nous +Research's open-source self-improving agent: a terminal CLI/TUI plus a +messaging gateway that connects one agent to Telegram, Discord, WhatsApp, +Slack, and Signal. It has first-class voice features — spoken replies, +voice-bubble delivery on chat platforms, push-to-talk dictation, and +automatic transcription of incoming voice messages — and every one of them +is pluggable. + +Voicebox slots into both directions of that loop, entirely on-device: + +- **Voice out** — Hermes speaks its replies in one of your cloned or preset + voices instead of a stock cloud voice. +- **Voice in** — voice messages and push-to-talk audio are transcribed by + the Whisper models already bundled with Voicebox. Audio never leaves your + machine. + +There are two integration surfaces, and they compose — most people will +want both. Everything talks to the same local API +(`http://127.0.0.1:17493` while the Voicebox app is running). + + + Running Voicebox in Docker instead of the desktop app? The API is on + `http://127.0.0.1:17600` — set `VOICEBOX_BASE_URL` accordingly wherever it + appears below. See [Docker](/overview/docker). + + +## MCP: agent-invoked voice tools + +Hermes speaks MCP natively, and Voicebox ships a built-in +[MCP server](/overview/mcp-server). Voicebox is in Hermes's approved MCP +catalog, so: + +```bash +hermes mcp install voicebox +``` + +(Or add the block manually to `~/.hermes/config.yaml`:) + +```yaml +mcp_servers: + voicebox: + url: "http://127.0.0.1:17493/mcp" + headers: + X-Voicebox-Client-Id: "hermes" +``` + +Hermes discovers the tools — `voicebox.speak`, `voicebox.transcribe`, +`voicebox.list_profiles`, `voicebox.list_captures` — and the agent can now +*choose* to use them: "read me that summary in Morgan's voice" works +immediately, and the [per-client binding](/overview/mcp-server#per-client-bindings) +for `hermes` lets you pin its default voice from the Voicebox UI. + +MCP makes Voicebox a set of tools the agent may call. It does **not** +reroute Hermes's own voice pipeline — spoken replies, voice bubbles, and +incoming voice-message transcription still use whatever `tts.provider` / +`stt.provider` are set to. That's the plugin's job. + +## Provider plugin: Hermes's own voice pipeline + +[`hermes-voicebox`](https://github.com/jamiepine/hermes-voicebox) registers +Voicebox as a Hermes **TTS provider** and **STT provider** via Hermes's +pluggable backend interfaces (see the Hermes developer guides for +[TTS providers](https://hermes-agent.nousresearch.com/docs/developer-guide/tts-provider-plugin) +and +[transcription providers](https://hermes-agent.nousresearch.com/docs/developer-guide/transcription-provider-plugin)). +Once selected, the providers service the *entire* voice pipeline: every +spoken reply, every Telegram voice bubble, every incoming voice memo — plus +a bundled skill that teaches the agent when speaking aloud is appropriate +and to recall your dictated [Captures](/overview/captures) through MCP. + + + +### Install the plugin + +Into the same Python environment Hermes runs in: + +```bash +pip install git+https://github.com/jamiepine/hermes-voicebox +``` + +No pip? Copy it in as a directory plugin instead: + +```bash +git clone https://github.com/jamiepine/hermes-voicebox /tmp/hermes-voicebox +cp -r /tmp/hermes-voicebox/hermes_voicebox ~/.hermes/plugins/voicebox +hermes plugins enable voicebox +``` + +### Select the providers + +In `~/.hermes/config.yaml`: + +```yaml +tts: + provider: voicebox + +stt: + provider: voicebox +``` + +### Try it + +With the Voicebox app open, start `hermes chat` and ask it to say +something out loud — or send your Hermes bot a voice message on Telegram +and watch the transcript come back from your local Whisper. + + + +## Behavior notes + +- **Voicebox must be running.** The desktop app only serves the API while + it's open. Both providers implement availability as a live `/health` + check, so Hermes's provider picker reflects reality. +- **First generation is slower** while the TTS engine loads into memory; + subsequent calls are fast. Same for the first transcription with a new + Whisper size — Voicebox answers `202` while the model downloads, and the + plugin surfaces a friendly "try again in a minute". +- **Voice selection**: `tts.voice` in Hermes config (or the tool's `voice` + argument) accepts a Voicebox profile **name or id**. With no voice set, + the first profile is used. +- **Engines**: pass a Voicebox engine id (`qwen`, `kokoro`, + `chatterbox`, …) as the Hermes `model` to override the profile's + default engine. + +## Next steps + +- [MCP Server](/overview/mcp-server) — the tool-call route, per-client + bindings, and the speaking pill +- [Creating Voice Profiles](/overview/creating-voice-profiles) — clone the + voice Hermes will speak in +- [Remote Mode](/overview/remote-mode) — reaching a Voicebox instance on + another machine (read the security notes first: the API has no auth) diff --git a/docs/content/docs/overview/meta.json b/docs/content/docs/overview/meta.json index 989670f57..380e1603a 100644 --- a/docs/content/docs/overview/meta.json +++ b/docs/content/docs/overview/meta.json @@ -13,6 +13,7 @@ "preset-voices", "voice-personalities", "mcp-server", + "hermes-agent", "stories-editor", "recording-transcription", "generation-history", From 68feec83056fe258fdb05a5fefdf55e0a2a3b592 Mon Sep 17 00:00:00 2001 From: James Pine Date: Sun, 12 Jul 2026 16:11:46 -0700 Subject: [PATCH 2/3] docs: hermes-voicebox is published on PyPI --- docs/content/docs/overview/hermes-agent.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/docs/overview/hermes-agent.mdx b/docs/content/docs/overview/hermes-agent.mdx index c1bc81763..775c0dcc9 100644 --- a/docs/content/docs/overview/hermes-agent.mdx +++ b/docs/content/docs/overview/hermes-agent.mdx @@ -82,7 +82,7 @@ and to recall your dictated [Captures](/overview/captures) through MCP. Into the same Python environment Hermes runs in: ```bash -pip install git+https://github.com/jamiepine/hermes-voicebox +pip install hermes-voicebox ``` No pip? Copy it in as a directory plugin instead: From fc553e94e53c5d3f06389bce741fe6b5c199bab5 Mon Sep 17 00:00:00 2001 From: James Pine Date: Sun, 12 Jul 2026 18:35:16 -0700 Subject: [PATCH 3/3] docs: link hermes plugin guide instead of unshipped provider-guide pages --- docs/content/docs/overview/hermes-agent.mdx | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/content/docs/overview/hermes-agent.mdx b/docs/content/docs/overview/hermes-agent.mdx index 775c0dcc9..ed76bb0e7 100644 --- a/docs/content/docs/overview/hermes-agent.mdx +++ b/docs/content/docs/overview/hermes-agent.mdx @@ -66,10 +66,9 @@ incoming voice-message transcription still use whatever `tts.provider` / [`hermes-voicebox`](https://github.com/jamiepine/hermes-voicebox) registers Voicebox as a Hermes **TTS provider** and **STT provider** via Hermes's -pluggable backend interfaces (see the Hermes developer guides for -[TTS providers](https://hermes-agent.nousresearch.com/docs/developer-guide/tts-provider-plugin) -and -[transcription providers](https://hermes-agent.nousresearch.com/docs/developer-guide/transcription-provider-plugin)). +pluggable backend interfaces (`register_tts_provider` / +`register_transcription_provider` — see +[Build a Hermes Plugin](https://hermes-agent.nousresearch.com/docs/developer-guide/plugins)). Once selected, the providers service the *entire* voice pipeline: every spoken reply, every Telegram voice bubble, every incoming voice memo — plus a bundled skill that teaches the agent when speaking aloud is appropriate