OpenVoiceUI

A browser-based, voice-first "AI computer" for your own agent.

Quick start · Features · How it works · Configuration · Docs · Contributing

---

OpenVoiceUI is the front end of a self-hosted AI agent. You talk to it in the browser; the agent answers out loud and can put real, interactive HTML pages on screen while it talks: dashboards, tools, galleries, reports, full web apps. It also plays and generates music, drives an OS-style desktop of saved pages, and exposes everything through a mobile-friendly admin dashboard.

The agent itself runs in OpenClaw, an open-source agent gateway that routes to the LLM provider you choose (OpenAI, Anthropic, Groq, Z.AI, Gemini and others) and supplies tools, skills, memory and sub-agents. OpenVoiceUI is a Flask server plus a vanilla-JS browser app that sits in front of that gateway and handles voice in, voice out, and everything you see. Other agent backends can be added as gateway plugins.

Self-hosted and MIT licensed: your hardware, your keys, your data.

Features

Voice

• Hands-free conversation with wake word, push-to-talk, interruption ("interject") and a text mode toggle.
• Speech-to-text: browser Web Speech (default, free), Deepgram streaming, Groq Whisper, or any Whisper-compatible server you run.
• Text-to-speech from nine providers, from free and local to premium cloned voices (see Providers), with per-profile voice settings and a fallback chain.
• Voice cloning through Qwen3-TTS (fal.ai), ElevenLabs or Resemble.

Canvas and desktop

• The agent builds and opens live HTML canvas pages mid-conversation; pages update in place.
• An OS-style desktop (Windows XP, macOS, Ubuntu, Windows 95 and Windows 3.1 themes) that holds every saved page, with a start menu, recent pages and a recycle bin.
• Shipped pages include a file explorer, image tools (AI image creator, splitter, grid creator, bulk uploader), icon library, camera capture and job albums, interactive map, sing-along, voice studio, terminal, ChatGPT conversation import and a canvas style picker.
• Each canvas page has public/private and lock controls in the admin dashboard; with authentication enabled, pages are private by default.

Media

• Suno music generation from voice, with a built-in player and playlists.
• Image generation through Hugging Face models and Google Gemini/Imagen.
• An audio clip creator (text to MP3) and sound-effect soundboard.

Agent

• Profiles: switch persona, voice, gateway and LLM settings per agent.
• Animated faces: the "AI Eyes" and halo-smoke orb faces, a custom-face editor, and face plugins.
• Sub-agent visibility, and the agent's workspace files (identity, instructions, memory) are browsable and editable from the dashboard.
• Credential vault with one-click OAuth connectors (Supabase, GitHub, Netlify).

Operations

• Admin dashboard (/admin): profiles, agent editor, plugins, canvas pages, custom faces, workspace files, music, provider and voice configuration, connectors, health and sessions, updates, logs and a built-in connector test suite.
• Optional Clerk authentication for public deployments.
• One-click self-update, and plugins installed from a remote catalog.

Screenshots: none are checked into the repository yet. The documentation site and openvoiceui.com show the UI.

Quick start

All install paths need Docker installed and running, except the native Linux server install.

npm CLI (recommended)

Requires Node.js 18+ and Docker.

npx openvoiceui setup     # interactive wizard: LLM + TTS providers, API keys, builds the images
npx openvoiceui start     # starts OpenClaw, Supertonic TTS and OpenVoiceUI

Open http://localhost:5001. Other commands: stop, restart, status, logs.

The wizard writes .env and an openclaw-data/ folder (the gateway's config, workspace and a pre-paired device identity), then runs Docker Compose with docker-compose.local.yml layered on top so the gateway can read that config and your keys.

Pinokio

In Pinokio, add OpenVoiceUI from this repository's URL (https://github.com/MCERQUA/OpenVoiceUI), then click Install and Start. Pinokio does not install Docker for you: its installer checks that Docker is installed and running, asks for your API keys, and then runs the same setup as the npm wizard (setup-config.js + Docker Compose).

Docker Compose (manual)

git clone https://github.com/MCERQUA/OpenVoiceUI.git
cd OpenVoiceUI
cp .env.example .env      # edit: gateway token, TTS keys, SECRET_KEY
docker compose up --build

This starts three containers:

Service	Port	Purpose
openclaw	18791	Agent gateway (routes to your LLM provider)
supertonic	internal	Free local text-to-speech
openvoiceui	5001	Voice UI, canvas, API and admin dashboard

openvoiceui shares the openclaw container's network, so port 5001 is published through the openclaw service. With plain docker compose, the gateway does not receive .env or a generated config: either configure OpenClaw's LLM provider yourself (see OpenClaw requirements), or use the npm wizard, which does it for you.

Linux server (systemd + nginx + SSL)

git clone https://github.com/MCERQUA/OpenVoiceUI.git
cd OpenVoiceUI
cp .env.example .env                    # edit with your keys
python3 -m venv venv && venv/bin/pip install -r requirements.txt
# edit DOMAIN and EMAIL at the top of setup-sudo.sh, then:
sudo bash setup-sudo.sh

setup-sudo.sh offers to install OpenClaw at the tested version (or use an existing install), then writes the nginx reverse-proxy config, gets a Let's Encrypt certificate, and installs the openvoiceui systemd service that runs venv/bin/python3 server.py. See docs/SETUP.md for the full walkthrough.

Requirements

	Version
Python	3.11+ (CI runs 3.11; the Docker image uses 3.12)
Node.js	18+ (npm CLI and Pinokio helpers only)
Docker + Compose	Any current release (npm, Pinokio and Docker installs)
OpenClaw	The tested version pinned in docker-compose.yml, deploy/openclaw/Dockerfile and setup-sudo.sh (kept in sync by bump-openclaw-version.sh)
Browser	A current Chrome or Edge is recommended for the default Web Speech STT; other browsers can use Deepgram or Groq Whisper. Microphone access is required for voice.

Configuration

Configuration lives in .env. Copy .env.example, which documents the available options.

Setting	Needed for
CLAWDBOT_GATEWAY_URL, CLAWDBOT_AUTH_TOKEN	Connecting to the OpenClaw gateway. Docker Compose sets the URL for you.
SECRET_KEY	Stable sessions across restarts (a random key is generated if unset).
A TTS provider key, e.g. GROQ_API_KEY	Cloud voices. Supertonic works with no key.
DEEPGRAM_API_KEY	Deepgram streaming speech-to-text (optional).
SUNO_API_KEY	Music generation (optional).
CLERK_PUBLISHABLE_KEY, CANVAS_REQUIRE_AUTH	Login for public deployments (optional).

LLM provider keys belong to the gateway: OpenClaw's own setup (or the npm wizard) configures which model the agent uses. Server behaviour is tuned in config/ (YAML), agent personas in profiles/, and the voice system prompt in prompts/voice-system-prompt.md, which is hot-reloaded.

How it works

 Browser  (index.html + src/ ES modules, no build step)
   │  mic ──► speech-to-text (Web Speech / Deepgram / Groq Whisper / your server)
   │  POST /api/conversation ──► streamed reply (NDJSON) ──► text-to-speech ──► speaker
   │  canvas iframe ◄── server-sent events when pages change
   ▼
 OpenVoiceUI server  (Flask, server.py, port 5001)
   ├─ routes/            conversation, canvas, music, admin, vault, uploads, ...
   ├─ services/          gateway manager, auth, TTS, plugins, paths, ...
   │    └─ gateways/openclaw.py ──WebSocket──►  OpenClaw gateway (port 18791) ──► your LLM
   ├─ tts_providers/     Supertonic, Groq, Resemble, ElevenLabs, Hume, ...
   └─ runtime/           canvas pages, uploads, music, transcripts (persistent volumes)

The agent controls the interface with short tags in its replies (for example, open a canvas page, play a track, change the face's mood). The browser strips the tags from what is spoken and acts on them. The tag set is documented in Agent Tags. The full technical map is docs/ARCHITECTURE.md.

Repository layout

Path	Contents
server.py, app.py	Flask entry point and app factory
routes/	Flask blueprints, one per feature area
services/	Backend services: gateway manager and gateways, auth, TTS, plugins, vault, paths
providers/, tts_providers/	Provider registry and TTS/STT/LLM provider implementations
src/	Browser app (vanilla JS ES modules): adapters, core, shell bridges, UI, faces
static/, index.html, sounds/	Static assets, page shell, soundboard clips
default-pages/, default-faces/, default-styles/	Canvas pages, face template and style presets shipped with the app
canvas-shared/	Shared scripts for canvas pages
skills/, install-skills.js	Agent skills bundled for OpenClaw and their installer (docs/SKILLS.md)
plugins/	Plugin catalog stubs and the example gateway
profiles/, prompts/, config/	Agent profiles, the voice system prompt, server configuration
deploy/	Container builds for OpenClaw, Supertonic and optional services
cli/, pinokio.js, install.js, start.js, ...	npm CLI and Pinokio launcher scripts
setup-sudo.sh, setup-nginx.sh, openvoiceui.service	Native Linux server install
tests/	pytest suite
docs/, website/	Documentation and the Docusaurus site that publishes it
archive/	Superseded files kept for reference (not shipped)

docs/REPO-ORGANIZATION.md explains the layout and the planned clean-ups.

Providers

LLM. Through the OpenClaw gateway: any provider OpenClaw supports (OpenAI, Anthropic, Groq, Z.AI GLM, Google Gemini, MiniMax and more). A direct Z.AI fallback path exists for slow or empty gateway turns. Other agent backends plug in as gateway plugins (see plugins/example-gateway).

Text-to-speech (tts_providers/providers_config.json)

Provider	Notes	Key
Supertonic	Local, free; ships with the Docker setup	none
Pocket TTS	Local voice cloning	none
Groq Orpheus	Fast cloud TTS	GROQ_API_KEY
Qwen3-TTS (fal.ai)	Cloud voice cloning	FAL_KEY
Qwen3-TTS (local)	Voice cloning on your own GPU	none
Resemble AI	Premium cloned voices	RESEMBLE_API_KEY
ElevenLabs	Large voice library, instant cloning	ELEVENLABS_API_KEY
Hume Octave	Emotion and acting-direction TTS	HUME_API_KEY
xAI Grok	Cloud TTS	XAI_API_KEY

Speech-to-text: browser Web Speech (default), Deepgram streaming (DEEPGRAM_API_KEY), Groq Whisper, xAI, or an external Whisper-compatible server (STT_API_URL).

Realtime voice adapters (src/adapters/): ElevenLabs, Hume EVI and xAI Grok Realtime, opt-in per profile. New adapters start from src/adapters/_template.js.

Plugins

Plugins add face packs, canvas pages, gateways or combinations of them, and are installed from the admin dashboard. This repository carries the catalog entries (plugin.json + README.md); the plugin code lives in the plugins repository.

Plugin	Type	What it adds
BHB Animated Characters	Face pack	Animated BigHead Billionaires characters with lip-sync and moods, by BHaleyart
Hermes Agent	Gateway	The Hermes self-improving agent as a standalone or OpenClaw+Hermes hybrid backend (pinned version in its plugin.json)
Booking	Canvas pages	Appointment booking pages backed by a Cal.diy instance
MidiViz	Canvas page	Audio-reactive MIDI visualizer
SEO Platform	Canvas page	SEO dashboard powered by DataForSEO
Twenty CRM	Canvas page	Embedded Twenty CRM with a setup wizard
Example Gateway	Gateway template	Echo gateway to copy when building your own

Build your own with the plugin guide and the plugin system docs.

Bundled agent skills

OpenVoiceUI ships OpenClaw skills in skills/ that teach the agent its own features: canvas pages and their visibility, canvas design, custom faces, Suno music, Three.js pages, and voice conversation rules. Every installer puts them where OpenClaw loads them (~/.openclaw/skills/openvoiceui/): Docker, Pinokio and npm mount them read-only, native installs copy them. See docs/SKILLS.md for what each one does, how updates work, and where your own skills go.

Development

python3 -m venv venv
venv/bin/pip install -r requirements.txt pytest
cp .env.example .env
venv/bin/python3 server.py                 # http://localhost:5001
venv/bin/python3 -m pytest tests/ -q       # test suite (CI runs this on every PR)

There is no frontend build step: edit files under src/ and reload. See CONTRIBUTING.md for the branch workflow (trunk-based, PRs to main), code style and how to add providers, adapters and gateway plugins. AI coding agents should start with AGENTS.md.

Documentation

• Docs site: mcerqua.github.io/OpenVoiceUI, built from docs/: installation, configuration, OpenClaw requirements, features, customization, extending, API reference.
• Repository docs: Architecture · Vision · Setup guide · Bundled agent skills · Releasing · Repository organization · Design plans
• Project: Changelog · Contributing · Code of Conduct · Security policy · Contributors

Contributing

Contributions are welcome: providers, canvas pages, faces, plugins, docs and fixes. Read CONTRIBUTING.md, open a pull request against main, and keep each PR to one change. Community plugins go to the plugins repository. Please report security issues privately as described in SECURITY.md.

License

MIT © OpenVoiceUI contributors.

Website · Docs · npm · Plugins