- HTML 71%
- Python 22%
- Nix 4%
- JavaScript 2%
- Shell 1%
Hermes Persona #
A fullscreen browser-based voice interface for Hermes Agent — the open-source AI agent by Nous Research. Features an animated particle orb persona that reacts to listening, thinking, and speaking states.

Routes through the Hermes Gateway's API Server platform, sharing the same agent pipeline as Signal, Telegram, and other messaging platforms. Alternative backends include the local CLI (hermes chat -q) and test mode for previewing without any LLM.
Other agentic tools (Claude Code, Codex, etc.) are not supported.
Features #
- Speech-to-text via browser Web Speech API for Chromium-based browsers with text input fallback for Firefox/Safari
- Text-to-speech via Edge TTS (free, no API key needed)
- Animated persona — a glowing particle entity
- Real-time audio visualization with frequency bar
- Fullscreen UI — dark theme, no distractions
Architecture #
Designed exclusively for Hermes Agent. The primary backend routes through the Hermes Gateway's built-in API Server platform, giving browser voice the same agent pipeline as messaging platforms:
┌─────────────────────┐
Browser (index.html) │ FastAPI Server │ ┌──────────────────┐
┌──────────────────┐ │ (server.py) │ │ Hermes Gateway │
│ Web Speech API │◄──┤ WebSocket /ws │ │ (port 8642) │
│ (STT) │ │ │ │ │
│ Canvas Persona │ │ API Server Proxy │─────►│ Signal Platform │
│ Audio Playback │◄──┤ (POST /v1/chat) │ │ Telegram Plat. │
│ Vibe Bar │ │ │ │ API Server Plat │
└──────────────────┘ │ Edge TTS │ │ ┌────────────┐ │
│ (voice synthesis) │────► │ │ AIAgent │ │
└─────────────────────┘ │ │ (same one) │ │
│ └────────────┘ │
└──────────────────┘
All three interfaces (Signal, TUI, hermes-persona) route through the same Hermes Agent pipeline, sharing persistent memory and tool access. Each has its own conversation session, bridged by memory.
Prerequisites #
- A running Hermes Gateway with the API Server platform enabled (
API_SERVER_ENABLED=truein~/.hermes/.env) on the same system as Hermes Persona
Quick Start #
If you enable test mode (Settings > Test Mode) you can try out the core functionality without needing a functional Hermes deployment
Run with Nix, like so:
nix run git+https://tangled.org/heywoodlh.io/hermes-persona
Manual Setup #
# Install dependencies
pip install fastapi uvicorn edge-tts httpx websockets
# Make sure the gateway is running with API_SERVER_ENABLED=true
# (already set if you followed the gateway setup)
# Run
python server.py
Open http://localhost:8765 in a Chromium-based browser. Press the mic button to speak. Alternatively, type into the text field.
Environment Variables #
| Variable | Default | Description |
|---|---|---|
HERMES_BACKEND |
api_server |
Backend mode: api_server (gateway API server), local (Hermes CLI), or test (no LLM) |
HERMES_API_SERVER_URL |
http://localhost:8642/v1/chat/completions |
Gateway API Server endpoint (only used with api_server backend) |
HERMES_VOICE_MODEL |
openai/gpt-4o-mini |
LLM model advertised to the gateway API server |
HERMES_VOICE_SYSTEM_PROMPT |
(see below) | Custom system prompt for the LLM. Default: "You are Hermes Persona... Keep responses concise, natural, and conversational since they will be spoken aloud." |
HERMES_TTS_VOICE |
en-US-BrianNeural |
Edge TTS voice name (see Microsoft's list of supported voices) |
HERMES_TTS_RATE |
+10% |
TTS speech rate adjustment (e.g. +20%, -10%) |
PORT |
8765 |
HTTP server port |
HERMES_BIN |
hermes |
Path to Hermes CLI binary (used with local backend) |
HERMES_AUDIO_DIR |
~/.local/share/hermes-persona/audio_cache |
Writable directory for TTS audio cache |
Project Structure #
hermes-persona/
├── server.py # FastAPI backend (WebSocket + LLM proxy + TTS)
├── run.sh # Startup script (sources .env vars)
├── static/
│ └── index.html # Fullscreen browser app (Canvas persona + STT)
├── audio_cache/ # Generated TTS audio files (auto-cleaned)
├── README.md
└── LICENSE
Backend Modes #
API Server (Default) #
Routes through the Hermes Gateway's API Server platform on port 8642. The same agent instance handles Signal, Telegram, and browser voice requests. Persistent memory is shared between all interfaces.
HERMES_BACKEND=api_server python server.py
Local CLI #
Route through your local Hermes Agent CLI (hermes chat -q):
HERMES_BACKEND=local python server.py
Uses whatever model and provider Hermes is configured with. No gateway needed.
Test Mode #
Preview the persona animation and test microphone input without any LLM backend:
# Open in browser with test mode
open http://localhost:8765/?mode=test
# Or click the Settings Icon > "Test Mode" button in the UI to toggle
In test mode, speaking into the mic will animate the persona and respond with "I hear you loud and clear!" — no LLM API call is made.
Browser Support #
| Feature | Chrome | Edge | Firefox | Safari |
|---|---|---|---|---|
| Voice input (mic) | ✓ | ✓ | — (text fallback) | — (text fallback) |
| Text input | ✓ | ✓ | ✓ | ✓ |
| Audio playback | ✓ | ✓ | ✓ | ✓ |
| Canvas persona | ✓ | ✓ | ✓ | ✓ |
Firefox and Safari users get the same futuristic persona and audio experience, but type their messages instead of speaking.
HTTPS Requirement for Microphone #
The Web Speech API (speech-to-text) and getUserMedia (microphone access) require a secure context (HTTPS). This is a browser security feature — Chrome and Edge block microphone access on plain HTTP pages to prevent eavesdropping.
What works:
- Any HTTPS URL
http://localhost:8765— localhost is always treated as a secure context, so microphone works on HTTP
What does NOT work:
- Any non-localhost HTTP URL — microphone access is denied by Chromium-based browsers as a security precaution
The text input fallback always works regardless of protocol, so you can always type messages even when microphone access is unavailable.
License #
GNU General Public License v3.0 — see LICENSE.
Built for use with Hermes Agent by Nous Research.