Visualize and chat with hermes in a web app
README.md

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.

demo

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=true in ~/.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.