OpenVoiceUI Voice AI Assistant
A self-hosted, browser-based voice-first front end for your own AI agent: plug in any LLM and TTS, and get live interactive web canvases, music and an OS-style desktop — your hardware, your keys, your data.
- Source repo
- MCERQUA/OpenVoiceUI
- Stars
- ★ 87
- Last updated
- 1d ago
- License
- MIT
- Primary language
- Python
- FA score
- 76/100 · Good
At a glance
- How it runs
- Works with
- Universal · cross-platformOpenAI API · Claude API
- Cost
- Free software; you pay for model usage
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- A developer who wants a hands-free, interruptible voice AI assistant on their own hardware without locking into one model vendor
- Not a fit if
- Users who want a zero-install hosted product and won't run Docker themselves
- Teams wanting a native mobile app rather than a browser voice UI
- Projects that cannot supply any LLM provider API key
- Website
- openvoiceui.com ↗ set on GitHub
- Maintenance
- Commits in the last 30 dayslast commit 2026-11-21
- Source review
- 76/100 · Good
What does this agent do, and when should you use it?
OpenVoiceUI (MCERQUA/OpenVoiceUI, MIT licensed) is the front end of a self-hosted AI agent, built as a Flask server plus a no-build-step vanilla-JS browser app. The agent itself runs in OpenClaw, an open-source agent gateway that routes to your chosen LLM provider (OpenAI, Anthropic, Groq, Z.AI, Gemini and others). You talk to it in the browser; it answers out loud and opens live, interactive HTML canvas pages mid-conversation, held in an OS-style desktop with XP/macOS/Ubuntu themes. The voice stack covers wake word, interruption, Web Speech/Deepgram/Groq Whisper speech-to-text, and nine TTS providers ranging from free local Supertonic to ElevenLabs and Resemble voice cloning. Deployment centers on a three-container Docker Compose stack (openclaw, supertonic, openvoiceui on port 5001), with npm wizard, Pinokio and native Linux systemd+nginx install paths also documented.
The browser captures microphone audio and transcribes it via Web Speech, Deepgram, Groq Whisper or a self-hosted Whisper-compatible server; POST /api/conversation streams the agent reply as NDJSON, which is then spoken via TTS. The Flask server (server.py, port 5001) connects over WebSocket to the OpenClaw gateway (port 18791), which calls your configured LLM. The agent controls the interface with short tags — open a canvas page, play a track, change the face's mood — which the browser strips from speech and executes. Canvas pages update in place via server-sent events; the /admin dashboard manages profiles, plugin catalog installs, a credential vault (Supabase/GitHub/Netlify OAuth), Suno music generation, canvas page visibility and sessions. OpenClaw skills teaching the agent its own features ship in skills/ and install to ~/.openclaw/skills/openvoiceui/.
- A developer who wants a hands-free, interruptible voice AI assistant on their own hardware without locking into one model vendor
- Users who need the agent to produce interactive dashboards, reports or galleries as live web pages rather than plain text replies
- Self-hosting enthusiasts who want zero-cost, key-free voice output via the local Supertonic TTS provider
- Creators who trigger Suno music generation by voice and manage playlists in the built-in player
- Anyone building a named persona with a cloned voice via Qwen3-TTS, ElevenLabs or Resemble
- Operators deploying a public voice assistant on a Linux server with systemd + nginx + Let's Encrypt and optional Clerk authentication
Key setup facts
Pulled from the install and usage notes below. The project README has the current values.
- Install / run
npx openvoiceui setupnpx openvoiceui startdocker compose up --build
- Ports
5001- Environment variables
GROQ_API_KEYDEEPGRAM_API_KEYSUNO_API_KEYCLAWDBOT_GATEWAY_URLCLAWDBOT_AUTH_TOKENSECRET_KEY- Config files
.env.env.example- Runtime
- Node.js 18+
- Install notes cover
- Linux · Docker
How do you install or deploy this agent?
All install paths need Docker installed and running, except the native Linux server install.
npm CLI (recommended; requires Node.js 18+):
npx openvoiceui setup
npx openvoiceui startThe wizard writes .env and an openclaw-data/ folder and builds images; then open http://localhost:5001. Other commands: stop, restart, status, logs.
Pinokio: add the repository URL https://github.com/MCERQUA/OpenVoiceUI in Pinokio, then click Install and Start (Docker must be installed separately).
Manual Docker Compose:
git clone https://github.com/MCERQUA/OpenVoiceUI.git
cd OpenVoiceUI
cp .env.example .env
docker compose up --buildNote: with plain docker compose the gateway does not receive .env or a generated config — configure OpenClaw's LLM provider yourself, or use the npm wizard.
Native Linux install (systemd + nginx + SSL):
git clone https://github.com/MCERQUA/OpenVoiceUI.git
cd OpenVoiceUI
cp .env.example .env
python3 -m venv venv && venv/bin/pip install -r requirements.txt
sudo bash setup-sudo.shCredentials needed: an LLM provider key (configured on the OpenClaw gateway side); a TTS key such as GROQ_API_KEY (local Supertonic needs none); optional DEEPGRAM_API_KEY, SUNO_API_KEY and Clerk keys.
How do you use this agent?
After starting, open http://localhost:5001 and grant microphone access to begin voice conversation (Chrome or Edge recommended for the default Web Speech STT). Use npx openvoiceui status/logs to troubleshoot. In the /admin dashboard, switch agent profiles (persona, voice, gateway and LLM settings), install plugins, and edit agent workspace files and canvas page visibility. Tags in agent replies (open a canvas page, play a track, change the face's mood) are executed by the browser automatically; the tag set is documented in docs/reference/agent-tags.md. Tune server behaviour via .env (CLAWDBOT_GATEWAY_URL, CLAWDBOT_AUTH_TOKEN, SECRET_KEY, etc.); the voice system prompt lives in prompts/voice-system-prompt.md and hot-reloads.
What are this agent's strengths and limitations?
- LLM, STT and TTS are all swappable: nine TTS providers including free local Supertonic, and other agent backends plug in as gateway plugins (plugins/example-gateway)
- Generates live interactive HTML canvas pages and an OS-style desktop mid-conversation — output is full web apps, not just text
- No frontend build step (vanilla ES modules under src/), changes take effect on reload, with a pytest suite running in CI on every PR
- Complete self-hosted operations surface: /admin dashboard, credential vault, Clerk auth, one-click self-update and a remote plugin catalog
- The agent core depends on the OpenClaw gateway, whose version is pinned in docker-compose.yml and deploy scripts and kept in sync via bump-openclaw-version.sh
- The recommended path (npm wizard) requires Docker running persistently, and plain docker compose does not inject gateway config, adding manual setup burden
- Cloud voice and music features need multiple external service keys (Groq, Deepgram, Suno, ElevenLabs, etc.), splitting functionality and cost across providers
- No screenshots are checked into the repository yet, so the real UI must be judged from the docs site; voice requires microphone access and some browsers must switch to Deepgram/Groq Whisper
How does this agent compare with similar options?
The README names no direct competitor, but the positioning is a self-hosted, voice-first agent front end with live web canvases, contrasting with generic chat-style voice assistants and other OpenClaw front ends; differentiators are canvas page generation, the OS-style desktop and the multi-provider TTS chain.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| OpenVoiceUI Voice AI Assistant This agent | 76 · Good | CLIFree + model costs | ★ 87 | 1d ago | Python | OpenAI API · Claude API |
| ElevenLabs Agent Skills | 57 · Major gaps | Agent plugin / skillFree + model costs | ★ 579 | 3d ago | Python | — |
| Rapida Voice | 46 · Major gaps | Self-hosted serviceFree + model costs | ★ 760 | 14d ago | Go | OpenAI API · Claude API |
| jargo | 74 · Some gaps | — | ★ 112 | 2d ago | Go | OpenAI API · Claude API |
How does FollowAgents rate this agent?
Why each dimension lost points
Least privilege is exceptionally evidenced: admin-only route prefixes, WebSocket origin guard, SSRF blocking, uploads served as attachments with nosniff, npm trusted publishing limited to id-token, and an AST taint scanner over agent-writable roots (tests/agent_io_scan.py). Deductions: the app runs fully open without Clerk as the default; the browse service deliberately spoofs a Chrome UA and ships residential-proxy IP-masking for bot-detection evasion, a gray external behavior; self-update git-pulls and may spawn a coding agent as the server without an explicit user-confirmation flow; keys stay server-side (good) but UPLOADS_AUTH_MODE defaults to shadow (log-only); dependencies are pinned but no vulnerability scanning/audit evidence exists; rollback is shown only for canvas page versioning, not installs.
Full fallback chains for TTS/STT (keyless local Supertonic, Web Speech default, parakeet fallback on unreachable) and skill docs with per-error-code tables make failure handling strong. Deductions: version requirements contradict across docs (README: Node 18+/Python 3.11+; installation.md: Node 20+/Python 3.10+); legacy 'clawdbot' env names alongside rebranded docs invite confusion.
Four install paths, tiered audiences (trial/standard/manual/production), and skills with razor-sharp trigger conditions (e.g., the explicit-request hard rule for making pages public) score well. Deductions: capability boundaries rest mainly on VISION.md, which is not in the packet; environment fit leans Docker/Linux — Windows is only claimed in package.json's os field without documentation.
Information architecture is excellent (README layout table, docs site, AGENTS.md + module docstrings as layered orientation); install notes are thorough including a migration script; SECURITY.md lists known limitations (unseparated prompt injection); MIT license complete. Deductions: naming stability is poor — legacy names 'ai-eyes2', 'clawdbot', 'jambot', 'OVU' pervade code and comments, and AGENTS.md itself flags the providers/tts vs tts_providers confusion; CHANGELOG is referenced but not shown; maintenance rests on a single personal email, and the npm publish workflow comments admit repeated publishing failures.
Output usability is well supported (canvas lint, enforced performance gate, three-width check, versioned restore); marginal value over existing voice UIs (voice-first shell + own gateway + live canvas) is clear; cost-benefit thinking is visible (shared STT container, optional heavy deps). Deductions: no screenshots in-repo, and the core value depends on the external OpenClaw project whose quality is not visible to this review; static review cannot confirm overall usability.
Cross-referencing is dense (README→docs→AGENTS.md→docstrings), workflow comments carry PR/issue numbers for traceability, and known defects vs mitigations are clearly separated. Deductions: many key claims (passing tests.yml, docs-site content, OpenClaw behavior) lie outside the packet and cannot be independently confirmed; fact and inference occasionally blend in skill docs (e.g., the actual enforcement path of the performance gate).
- Without Clerk keys the app runs fully open; public deployments must set CANVAS_REQUIRE_AUTH=true and a strong SECRET_KEY.
- The browse-service component ships UA spoofing and residential-proxy IP routing for bot-detection evasion; operators must assess legal/ToS risk themselves.
- The self-update endpoint runs git pull as the server process and may spawn a coding agent — a high-risk surface; restrict to admins and audit logs.
- Environment requirements (Node/Python versions) and legacy naming (clawdbot/jambot/ai-eyes2) are inconsistent across docs; trust the newest in-repo files before installing.
- UPLOADS_AUTH_MODE defaults to shadow (log-only); set enforce explicitly in production.
- Prompt injection is a self-acknowledged unresolved limitation (system prompt and user input share one field); do not trust agent output for sensitive tasks.
FAQ
Can I use it without any cloud service keys?
Is Docker mandatory?
Is OpenClaw the only agent backend?
Where does my data live?
Is development convenient?
Is OpenVoiceUI Voice AI Assistant free?
Is OpenVoiceUI Voice AI Assistant open source?
Is OpenVoiceUI Voice AI Assistant safe to use?
Is OpenVoiceUI Voice AI Assistant still maintained?
Who makes OpenVoiceUI Voice AI Assistant?
What is OpenVoiceUI Voice AI Assistant's official website?
Thanks — we use this to improve the page.