Prerequisites
Python 3.12+, uv, Node.js 22 and pnpm 10. These versions follow pyproject.toml, .python-version and CI. Use a shell capable of running the repository's Bash launch scripts. Native Windows users should use a compatible environment such as WSL; this documentation update has not validated native Windows startup.
Start the demo
git clone https://github.com/happy-token/OpenRealtime.git
cd OpenRealtime
uv sync
pnpm install
pnpm dev
Open http://localhost:3010 (the default in scripts/dev_web.sh; an exported OPENREALTIME_WEB_PORT can override it). pnpm dev starts the Web frontend, Python WebSocket service (8765), control plane (8766), and the optional avatar-service launcher. Local neural avatar rendering is disabled by default; it does not require a GPU to open the application. The Python launcher requests optional dependency extras through uv, so its first run can install more packages than uv sync alone.
Start with voice and a short product document. After checking the application path, follow the product assistant walkthrough for retrieval testing, role binding and answer checks. Avatars are an optional next step.
Without configured provider credentials the server uses deterministic model/speech adapters. Test the page and typed-chat path first. If available, browser speech is an explicit fallback, with browser/platform limitations. Neither fallback nor a synthetic reply proves that cloud ASR/LLM/TTS is connected.
To enable real providers, follow cloud services. For persistent deployment use the deployment guide; the fixed local development identity is not production authentication.
Run production builds locally
Use pnpm start for local operation without the development compilers and hot-reload caches.
Its prestart step builds both the frontend and API before starting services. After a successful
build, the two web services can also be started individually:
bash scripts/dev_api.sh start
bash scripts/start_web.sh
The frontend defaults to 127.0.0.1:3010 and the API to 127.0.0.1:3011.
Export OPENREALTIME_WEB_PORT or OPENREALTIME_API_PORT to change their ports;
OPENREALTIME_WEB_HOST controls the frontend bind address. Restart with pnpm dev
when hot reload is needed. The launch scripts run the installed Next CLI directly,
avoiding an extra package-manager process for each service.
Stop and troubleshoot
Stop the foreground launcher with Ctrl+C. If ports remain occupied, identify the old processes before restarting; do not start duplicate backends.
| Symptom | Check |
|---|---|
| uv/pnpm command missing | Install the prerequisite tool and confirm it is on your shell PATH |
| Frontend cannot connect | Check launcher output and whether ports 3010/3011/8765/8766 are already occupied |
| Microphone unavailable | Allow permission; use localhost/HTTPS and select the correct system input |
| No audio | Check browser/site mute, system output, advertised speech capabilities and provider configuration |
| Avatar unavailable | Check the selected mode's assets, credentials and service readiness; a video preview is not real-time lip sync |
| Only demo responses | Configure compatible providers; inspect errors without exposing credentials |
These commands were checked against repository configuration during this documentation update; a fresh-machine installation and real-provider calls were not rerun.