README.md

metadata

title: Reachy OpenWebUI
emoji: 🐞
colorFrom: gray
colorTo: blue
sdk: gradio
app_file: app.py
pinned: false
short_description: Phone-style OpenWebUI conversations for Reachy Mini.
tags:
  - reachy_mini
  - reachy_mini_python_app
sdk_version: 6.18.0
license: apache-2.0

Reachy OpenWebUI

Reachy OpenWebUI is a phone-style conversation app for Reachy Mini. OpenWebUI owns the model, transcription, chat behavior, user context, and TTS. This app owns the robot-side runtime: settings, no-wake-word listening, camera buffering, local Reachy tools, avatars, chat state, and motion.

This Hugging Face Space is a project page. The real app runs inside the Reachy Mini app environment where it can access the robot daemon, microphone, speaker, camera, and movement APIs.

Highlights

• Phone-inspired settings and conversation UI served by the Reachy Mini app webserver.
• OpenWebUI model/workspace picker shown as contacts.
• OpenWebUI conversation list support for returning to saved chats.
• Model and user avatar proxying from OpenWebUI profile image endpoints.
• No-wake-word voice loop using Reachy audio, Silero VAD, OpenWebUI STT, OpenWebUI chat, and OpenWebUI TTS.
• Sentence-by-sentence speech streaming so audio starts before the full model answer is finished.
• Reachy-side tools for dance, recorded emotions, camera, head tracking, head movement, and speech.
• Speech-reactive head motion blended with queued robot moves.
• Robot attitudes that can shape idle motion, speaking motion, and which dance/emotion moves the model can choose.

Runtime Flow

Reachy microphone
  -> audio startup tuning and SDK record loop
  -> Silero VAD and level fallback
  -> OpenWebUI audio transcription
  -> OpenWebUI chat stream with optional Reachy tool specs
  -> optional Reachy-side tool execution
  -> OpenWebUI speech
  -> Reachy speaker output plus speech-reactive motion

OpenWebUI may accept requests at /api/chat/completions while returning either classic chat-completion chunks (chat.completion.chunk) or Responses-style events (response.output_text.delta, response.output_text.done, response.completed). The runtime reader must support both formats because the selected OpenWebUI model/contact can route through different providers even when the model id shown in the UI is unchanged.

Install

This repo currently has no uv.lock, so do not use uv sync --frozen.

uv venv --python python3.12 .venv
source .venv/bin/activate
uv sync

Editable pip install:

python -m venv .venv
source .venv/bin/activate
pip install -e .

Optional local vision extra:

uv sync --extra local_vision
pip install -e .[local_vision]

Developer tools:

uv sync --group dev

requirements.txt is only for this Hugging Face Space project page. The robot app dependencies live in pyproject.toml.

Configuration

The app reads ~/.config/settings/.env first, then a local .env if present. The settings UI writes the stable file at ~/.config/settings/.env.

Core OpenWebUI settings:

Variable	Purpose
OPENWEBUI_URL	OpenWebUI base URL. Values ending in /api are accepted.
OPENWEB_LOADED_LLM	Selected OpenWebUI model, workspace, or contact id.
OPENWEBUI_API_KEY	API key for HTTP requests when your OpenWebUI server accepts API-key bearer auth.
OPENWEBUI_TOKEN	Browser/session JWT. Preferred for chat, Socket.IO, transcription, and speech.
OPENWEBUI_CHAT_ID	Saved OpenWebUI chat id. Leave blank on first launch.
MIC_GAIN	Digital gain applied before VAD and transcription upload.
HF_HOME	Hugging Face cache directory.
HF_TOKEN	Optional token for gated or private assets.

User/context variables sent to OpenWebUI:

Variable	Purpose
OPENWEBUI_USER_ID	Optional user id. If blank, the app tries to derive it from the JWT.
OPENWEBUI_USER_NAME	User name supplied to OpenWebUI variables and socket context.
OPENWEBUI_USER_EMAIL	User email supplied to OpenWebUI variables and socket context.
OPENWEBUI_USER_LANGUAGE	User language variable.
OPENWEBUI_USER_LOCATION	User location variable.
OPENWEBUI_USER_TIMEZONE	User timezone variable.

Audio and timing settings:

Variable	Purpose
OPENWEBUI_TTS_READ_TIMEOUT	Read timeout for OpenWebUI speech responses.
OPENWEBUI_CONVERSATION_IDLE_RESET_SECONDS	Optional idle reset. 0 disables it.
VAD_THRESHOLD	Silero speech probability threshold.
VAD_FALLBACK_THRESHOLD	RMS fallback threshold.
VAD_SPEECH_ONSET_CHUNKS	Speech chunks required before a turn starts.
VAD_SILENCE_END_CHUNKS	Silence chunks required before a turn ends.
VAD_MIN_SPEECH_CHUNKS	Minimum speech chunks before sending audio to OpenWebUI transcription.
SILERO_VAD_ONNX_PATH	Optional path for the Silero ONNX model.

TTS Voices

Set TTS voices in OpenWebUI. This app reads the selected model/contact voice metadata and sends that voice back to the OpenWebUI speech endpoint.

If a model/contact has no voice set in OpenWebUI, the app sends no voice value and lets OpenWebUI use its default TTS behavior. There is intentionally no app-level voice picker because every OpenWebUI install can expose different TTS engines and voice names.

Running

The normal runtime path is the Reachy Mini Apps launcher. It provides the FastAPI settings app and serves the phone UI declared by:

custom_app_url = "http://0.0.0.0:7860/"

Console entry point:

reachy-mini-conversation-app-openwebui

CLI options:

Option	Default	Description
--no-camera	False	Skip camera frame buffering.
--smolvlm	False	Try to initialize the optional local SmolVLM vision manager.
--robot-name <name>	None	Connect to a daemon started with the same robot name.
--debug	False	Enable verbose app logging.

Settings UI

The phone-style UI lives in src/Reachy_OpenWebUI/static/.

It includes:

• Power-on screen while the backend is getting ready.
• Home screen with contacts, conversations, quick connect, and settings.
• Contacts page backed by OpenWebUI models.
• Conversations page backed by OpenWebUI chat history.
• Call screen with transcript bubbles, typing indicators, model avatar, user avatar, mute, end call, and back navigation.
• Settings for OpenWebUI URL, model/contact, credentials, mic gain, vision-only contacts, attitude, and Reachy-side tools.

Tools

Default Reachy-side tool allow-list:

src/Reachy_OpenWebUI/profiles/default/tools.txt

Enabled by default:

Tool	Behavior
dance	Queue a named or random dance from reachy_mini_dances_library.
stop_dance	Clear the dance queue.
play_emotion	Queue a recorded emotion from reachy-mini-emotions-library.
stop_emotion	Clear the emotion queue.
camera	Read the latest buffered camera frame and pass it to an optional vision manager.
idle_do_nothing	Explicit idle no-op for idle turns.
head_tracking	Attempt to toggle camera-worker head tracking.
move_head	Queue a head pose change: left, right, up, down, or front.
speak	Send text through the same OpenWebUI speech path used by normal assistant responses.

The settings page can enable or disable Reachy-side tools. OpenWebUI tools are still managed in OpenWebUI.

Attitudes

Attitude is one user-facing movement setting. It is designed to control:

• idle motion
• speech-reactive motion
• which dance and emotion moves are offered to the model

The goal is simple: a serious model should not move like a silly one, and a playful model should not be stuck with the same tiny idle pattern as a formal one.

Chat State

OpenWebUI chat state is stored in the stable settings file and recorded in:

~/.config/settings/openwebui_chat_history.json

The conversation window rolls over at local 7 AM. Callback and conversation selection clear or replace the saved chat id so OpenWebUI can attach the next turn to the right conversation.

Vision Status

Camera frame buffering is bundled and enabled unless --no-camera is passed. The optional local vision manager expects Reachy_OpenWebUI.vision.processors, which is not present in this checkout. If that module is absent, startup logs a warning and the camera tool returns an unavailable-vision error.

Project Layout

app.py                                    Hugging Face Space project page
pyproject.toml                            package metadata, dependencies, app entry points
requirements.txt                          Space-only dependency file
src/Reachy_OpenWebUI/main.py              Reachy Mini App entry point
src/Reachy_OpenWebUI/console.py           settings routes and media loop
src/Reachy_OpenWebUI/local/               OpenWebUI chat, speech, transcription, VAD
src/Reachy_OpenWebUI/tools/               Reachy-side tools
src/Reachy_OpenWebUI/static/              phone-style UI
src/Reachy_OpenWebUI/profiles/default/    default tool allow-list
external_content/                         starter external profile/tool examples

Development Checks

Run the checks available in this checkout:

uv run ruff check .
uv run ruff format . --check
uv run mypy --pretty --show-error-codes
uv run python -m compileall src app.py

There is no tests/ directory in this checkout. Add focused tests when adding behavior that can be tested off-robot.

License

Apache 2.0