Hermes Agent + ElevenLabs Voice: Full Setup Guide

Your Free Voice Is Fine, Until Someone Actually Hears It

Edge TTS ships with Hermes Agent and costs nothing. It works, it speaks 400+ voices across dozens of languages, and if you are the only one who hears your bot it is genuinely good enough. The moment you hand your Telegram bot to a client, put it in a group chat, or use it to record something a human is going to react to, the default suddenly sounds like a default. ElevenLabs is the fastest fix, and it is the single most-searched paid TTS provider Hermes supports.

This guide is the end-to-end wiring, one config file at a time. What the free tier actually covers, where the API key goes, how to pick a voice_id that will still exist in six months, which model to set for chat vs long-form, and where the honest tradeoffs are (US-hosted, usage priced, no offline path). No screenshots, no filler, just the steps and the numbers.

What the Free Tier Buys You

ElevenLabs gives every account 10,000 credits per month on the free tier. Multilingual v2 charges 1 credit per character, so that is roughly 10,000 characters, or about 1,500 spoken words, or ten to twelve minutes of finished audio at a natural pace. Credits do not roll over: the counter resets on your billing date and unused credits are gone.

For a personal Hermes agent that answers a handful of Telegram voice memos a day, ten minutes is often the whole month. For a customer-facing bot, plan on the Creator tier or above. Overages on Creator run about $0.30 per 1,000 characters, which is the honest number to model against Edge TTS being free.

Two free-tier gotchas worth naming up front:

The free plan permits commercial use, but the audio must attribute ElevenLabs. For a private chat that is fine. For a bot that speaks to your paying customers, that attribution requirement is a reason to pay.
The Default preset voices (Rachel, Adam, and the rest) are being retired at the end of 2026. Pin a Voice Library voice_id before then or your bot will silently break when the switchover happens.

Step 1: Install the Premium TTS Extra

Hermes ships with the free TTS providers baked in. ElevenLabs lives behind a tts-premium extra so the dependencies stay lean if you never turn it on:

pip install "hermes-agent[tts-premium]"

If you already installed the messaging extra, run the two together to avoid resolver churn:

pip install "hermes-agent[messaging,tts-premium]"

Step 2: Put the API Key Where Hermes Reads It

Create a key at elevenlabs.io under Profile then API Keys. The key looks like sk_... and is the only credential ElevenLabs needs. It goes in ~/.hermes/.env:

ELEVENLABS_API_KEY=sk_your_key_here

Two things about that path. First, it is ~/.hermes/.env, not the .env in whatever project you launched Hermes from - the gateway reads only the config directory. Second, if you export the key at the shell instead, Hermes will pick it up too, but the .env file is what survives a reboot without you thinking about it.

Step 3: Wire the Provider in config.yaml

Edit ~/.hermes/config.yaml and set the TTS block:

tts:
  provider: elevenlabs
  voice_id: 21m00Tcm4TlvDq8ikWAM   # Rachel (default female)
  model_id: eleven_multilingual_v2

That is the whole setup. Restart the gateway:

hermes gateway restart

From a CLI session, verify:

hermes
> /voice on
> Say "one two three, ElevenLabs is wired up."

You should hear the reply in the voice you configured. If you hear nothing, the two usual causes are a bad key (401 in the gateway log) and no ffmpeg on the box when Hermes tries to convert audio for Telegram - see the Telegram section below.

Step 4: Pick a voice_id That Will Still Exist

The voice_id is the single lever that decides how your bot sounds. Two families of voices, both accessed the same way:

Preset voices - Rachel, Adam, and the other names built into the free tier. Zero cost, work out of the box, but again: the whole preset roster is being sunset at the end of 2026. Fine for a weekend build, wrong for anything you plan to still run in 2027.
Voice Library voices - 10,000+ voices shared by ElevenLabs users and voices you design yourself. Browse the library at elevenlabs.io, click Add Voice on the ones you like, and paste the ID into voice_id. These voices persist and are the right pick for production.

The safe workflow: even for a first setup, pick two Voice Library voices, add both to your account, and put the primary one in voice_id. When one gets deprecated (community voices come and go), you swap without a scramble.

A close-up of an audio waveform in green over a dark background, with soft glowing peaks representing spoken audio

Step 5: Choose the Model

Two models matter for Hermes on Telegram, and you pick between them on latency versus quality:

Model	Cost	Latency	Best for
`eleven_multilingual_v2`	1 credit / char	Higher, quality-first	Long-form replies, voice-memo answers, multilingual chat
`eleven_flash_v2_5`	0.5 credit / char	Around 75 ms time-to-first-byte	Short chat responses, low-latency conversation

Multilingual v2 is the default in the config above because it produces the more expressive audio and covers 29+ languages, which matters if your Hermes agent replies in Spanish half the time. Flash v2.5 wins for short back-and-forth chat where the reply is a sentence or two and every 100ms is noticeable.

A pragmatic default: start on Multilingual v2, listen to a few real replies from your bot, and only move to Flash if the pause after your voice memo actually bothers you or the person on the other end.

Step 6: The Telegram Opus Advantage

This is the piece most setup guides skip and it is the reason ElevenLabs is a better fit for Telegram than most alternatives.

Telegram voice bubbles must be encoded as Opus. Local TTS engines like NeuTTS produce WAV, so Hermes has to shell out to ffmpeg for every reply, and that re-encode step adds latency you can feel. ElevenLabs can return Opus natively, so the audio bytes go straight from the API response to the Telegram voice bubble with no conversion.

You still want ffmpeg installed for fallback:

sudo apt install ffmpeg   # Linux
brew install ffmpeg        # macOS

But with ElevenLabs configured, ffmpeg sits idle on the happy path and voice replies arrive faster. Cross-reference the full TTS provider comparison if you are weighing this against NeuTTS or Piper for the same slot.

Step 7: Sanity-Check the Whole Loop

From your phone, send a voice memo to your Telegram bot:

Hold the mic button in the chat, speak a short question, release
The bot transcribes with Whisper
The agent processes the message
ElevenLabs synthesizes the reply as Opus
Hermes ships it back as a voice bubble

The whole loop should complete in a few seconds for a short question, longer for anything that triggers tool calls or MCP lookups. If audio never arrives, check the gateway log for 401 (bad key), 429 (rate-limited on free tier), or voice_id not found (usually a voice you did not add to your account before pasting the ID). For a broader troubleshooting pass, see the voice-not-working guide.

The Honest Tradeoffs

ElevenLabs is the best-sounding TTS you can wire into Hermes today, and it is not free of consequences worth naming:

Usage priced. You pay per character and the free tier is tight. If your bot writes long-form replies at scale, budget accordingly.
US-hosted, cloud-only. Every reply round-trips to ElevenLabs. If your agent must run air-gapped or your data cannot leave your jurisdiction, NeuTTS or Piper are the honest answer, not this.
Vendor lock on the voice. A voice cloned or picked from the Voice Library exists inside ElevenLabs. If you switch providers, you rebuild the identity.
Preset voice sunset. The Default voices go dark at the end of 2026. Move to the Voice Library before then.

For most people running a personal Hermes agent on Telegram, none of those are dealbreakers, and the quality lift is immediately audible.

A soft, cinematic scene of a phone on a wooden desk showing a Telegram voice bubble playing, with a faint green audio waveform above the screen

Skip the Wiring: Hermify Ships It Preconfigured

The setup above is not hard, but it is still four config touchpoints, one restart, and a voice-ID hunt to get the audio you want. If you would rather not manage any of it, Hermify runs a managed Hermes Agent on Telegram with the TTS layer already provisioned. Add your ElevenLabs key in the dashboard, pick your voice_id, and the change is live on the next reply. No SSH, no config.yaml, no ffmpeg install. The memory files stay yours regardless.

Get started with Hermify and skip straight to the fun part - the moment your bot answers in a voice that sounds like it belongs to you.