mirror of
https://github.com/jamiepine/voicebox.git
synced 2026-09-15 04:40:40 -07:00
docs: add Hermes Agent integration guide
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.
This commit is contained in:
James Pine
@@ -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).
|
||||
|
||||
<Callout type="info">
|
||||
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).
|
||||
</Callout>
|
||||
|
||||
## 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.
|
||||
|
||||
<Steps>
|
||||
|
||||
### 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.
|
||||
|
||||
</Steps>
|
||||
|
||||
## 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)
|
||||
@@ -13,6 +13,7 @@
|
||||
"preset-voices",
|
||||
"voice-personalities",
|
||||
"mcp-server",
|
||||
"hermes-agent",
|
||||
"stories-editor",
|
||||
"recording-transcription",
|
||||
"generation-history",
|
||||
|
||||
Reference in New Issue
Block a user