Reachy Mini

Connect a Reachy Mini to Wactorz, then control it in plain language. Reachy can move, look around, speak, listen, take photos, perform expressive gestures, and optionally control Home Assistant devices.

Beta: Reachy Mini is an experimental agent. Use it for supervised trials, not unattended production workflows. Keep the robot within reach while testing motion.

Installation policy

Reachy's recipe opts into require_install_success: true: it waits for package installation, reports failures, and postpones startup when loaded packages need a restart. The policy defaults to off. Other catalogue agents retain Wactorz's best-effort startup after a busy or timed-out installer. Package refusals block startup under both policies; strict installation never authorizes a package or a restore action.

Before you start

You need:

bash pip install 'wactorz[anthropic,reachy]'

From a clone of the repository, use pip install -e '.[anthropic,reachy]'. The reachy extra installs the robot SDK and its speech packages alongside Wactorz, so adding Reachy later has nothing to install and needs no restart. Already running Wactorz? Run pip install 'wactorz[reachy]' in the same environment and restart it once. For the rest of the setup, follow the README quick start.

For an audited installation from a repository clone, use the committed lock:

uv sync --locked --extra anthropic --extra reachy
uv run --no-sync wactorz

SDK 1.12.0 publishes secure Starlette requirements for both pip and uv. No uv metadata override is used. Reachy requires Python 3.11+, as Wactorz does. Client and HTTP middleware checks do not validate the full daemon dashboard or physical robot. Old saved Reachy recipes with changed dependency pins are refused at restore: respawn through @catalog spawn reachy-mini to use the normal package approval flow, then restart if requested. Saved runtime state is retained.

Where Wactorz runs decides what Reachy can do:

Wactorz runs on… What works
Windows or macOS Everything. The robot SDK brings the media libraries it needs.
Linux Movement and speech, after the preparation in Linux. Listening, conversation and the camera also need GStreamer's WebRTC plugin, which Linux distributions do not package.
Docker, or the Home Assistant add-on Not supported yet. Their images cannot install the robot SDK.

To restart Wactorz, which a first install asks for once, stop it with Ctrl+C and start it again.

Linux

The robot SDK compiles part of itself on Linux, so install the build tools and GStreamer first. On Debian or Ubuntu:

sudo apt install python3-venv python3-dev build-essential pkg-config \
  libcairo2-dev libgirepository1.0-dev \
  gstreamer1.0-plugins-base gstreamer1.0-plugins-good gstreamer1.0-plugins-bad \
  gstreamer1.0-nice gstreamer1.0-libav \
  gir1.2-gstreamer-1.0 gir1.2-gst-plugins-base-1.0 gir1.2-gst-plugins-bad-1.0

Run Wactorz with Python 3.11 to 3.13. The SDK needs a version of PyGObject that does not work on Python 3.14, which is the default on Ubuntu 26.04; there, create the virtual environment with an older Python and with pip in it, for example:

uv venv --seed -p 3.13 venv
venv/bin/pip install 'wactorz[anthropic,reachy]'

Without --seed the environment has no pip; install with uv pip install instead, and Wactorz uses uv for any later installs as long as it is on the PATH of the shell that starts Wactorz.

Wactorz then connects without Reachy's camera and microphone, and says so. Movement and speech work; listening, conversation and the camera stay off until GStreamer's WebRTC plugin (gst-plugins-rs) is installed, which means building it from source.

This was tested on Ubuntu 26.04 with Python 3.13 and a Reachy Mini Wireless.

Quick start

This path gets the robot moving from the Wactorz dashboard. Start with text commands; voice comes last and is optional.

1. Prepare the robot

Choose the model you have:

Reachy Mini Wireless

  1. Power on Reachy.
  2. Connect Reachy and the computer running Wactorz to the same Wi-Fi network.
  3. Close any Hugging Face or Reachy Mini control app that is controlling the robot.

Reachy Mini Lite

  1. Connect Reachy to the computer over USB.
  2. Find the robot's serial port. It looks like COM3 on Windows or /dev/ttyACM0 on Linux.
  3. Open a terminal and start the daemon, replacing <serial_port> with that value:
reachy-mini-daemon -p <serial_port>

Leave that terminal open while using Reachy.

2. Add Reachy to Wactorz

In the dashboard chat, send:

@catalog spawn reachy-mini

Installed with the reachy extra: the chat answers "reachy-mini spawned and running". Go on to step 3. The first start takes up to a minute longer while the robot SDK downloads Reachy's gesture library, once.

Installed without it: Wactorz installs Reachy's packages first. This is what you will see in chat:

  1. Straight away, a reply saying which packages it is installing. The whole install takes a few minutes, longer on a slow connection.
  2. One line per package as it installs, for example Installing reachy-mini==1.12.0 (1/6) for reachy-mini….
  3. Then one of these:
  4. "reachy-mini spawned and running": go on to step 3.
  5. "…restart Wactorz once to finish; reachy-mini will start by itself after the restart": this is normal on a first install. The robot packages need an older version of a library Wactorz had already loaded, and Python cannot swap it while it runs. Restart Wactorz (Ctrl+C, then start it again) and Reachy comes back on its own. Installing with the reachy extra, as in Before you start, avoids this.
  6. "…was not started because some of its packages failed to install": the message names each package and pip's error. Fix the cause it names, usually the network, then send @catalog spawn reachy-mini again. Packages that did install are kept.

Later spawns and restarts skip the install. The first start after it takes up to a minute longer while the robot SDK downloads Reachy's gesture library, once.

3. Check the connection

Send:

@reachy-mini health

A good reply starts with "I'm connected to my body". If it says Reachy is not connected, jump to If Reachy does not connect.

4. Try the first commands

Send these one at a time:

@reachy-mini wake up
@reachy-mini look left
@reachy-mini do a happy gesture
@reachy-mini say hello

Reachy should move for the first three commands and speak for the last one. The dashboard also shows the result, so an audio or motor problem does not look like a successful command.

If Reachy's voice is quiet, see make Reachy's voice louder with ffmpeg.

5. Optional: talk to Reachy

Text commands and Reachy's speech need nothing more. To talk to Reachy, Wactorz needs a speech recognition service. The default is Deepgram, a hosted service; voice audio is sent to it.

  1. Sign up at console.deepgram.com and create an API key.
  2. Put it in the .env file Wactorz reads, then restart Wactorz:

dotenv DEEPGRAM_API_KEY=your-key-here

  1. Try one question, then a conversation:

text @reachy-mini listen and ask Wactorz @reachy-mini start conversation

listen and ask Wactorz records five seconds, then answers out loud. start conversation (or start listening) keeps listening until you say "goodbye" or send @reachy-mini stop conversation.

To keep audio on your own computer instead, use the local recognizer described in Push-to-talk voice input.

Where to go next

Common problems

What you see What to do
The spawn reply says it is installing, and nothing else happens for a few minutes Normal on a first install. Each package is announced as it starts.
"…restart Wactorz once to finish…" Normal when Reachy's packages are installed at spawn. Restart Wactorz; Reachy starts by itself. Installing with the reachy extra avoids it.
"…some of its packages failed to install" Fix what pip's error names, usually the network, then spawn again.
"This Python environment … has no pip" Add pip with python -m ensurepip --upgrade, or put uv on the PATH, then spawn again.
"reachy-mini could not start: the Python module '…' is not installed" Send @catalog spawn reachy-mini again to install what is missing.
"reachy not connected" See If Reachy does not connect.
Reachy talks but does not move Close the Reachy Mini control app, then send @reachy-mini reconnect.
Reachy's voice is quiet Install ffmpeg, see make Reachy's voice louder, or say presenter mode.
Voice input says DEEPGRAM_API_KEY is required Do step 5.
"Reachy is connected without its camera and microphone…" Expected on Linux: movement and speech work. See Linux.
The Wactorz log shows ERROR … No Reachy Mini Audio USB device found! at startup Harmless on Reachy Mini Wireless: the robot SDK first looks for the Lite's USB audio.
Reachy stops talking in the middle of a sentence Check the Wactorz log at that moment for Reachy motor link is down, and report it with the lines around it.

If Reachy does not connect

Work through these checks in order:

  1. Make sure Reachy is powered on and that the preparation steps above still apply.
  2. For Wireless, confirm the robot and Wactorz host are on the same local network. Guest Wi-Fi often blocks devices from seeing one another.
  3. For Wireless, close the Reachy Mini control app. For Lite, confirm the daemon terminal is still running and shows no connection error.
  4. Ask the already-running agent to try again with @reachy-mini reconnect.
  5. If Wireless discovery still fails, or Wactorz runs inside WSL or a virtual machine, set the robot address explicitly as described in Set a Wireless address.

Use @reachy-mini reconnect force when the dashboard claims the link is alive but the robot does not respond. Reinstalling or respawning should not be the first troubleshooting step.

Detailed setup

Set a Wireless address

Automatic discovery is easiest when it works. It does not reach the robot from inside WSL or a virtual machine, which see the network through their host, and it can be unreliable elsewhere. Then tell Wactorz the robot's address yourself.

Find the address in your router's list of connected devices, or try the name reachy-mini.local. The examples below use 192.168.1.42; replace it with yours.

Add these lines to the .env file Wactorz reads:

REACHY_CONNECTION_MODE=network
REACHY_ROBOT_HOST=192.168.1.42

.env is read when Wactorz starts, so restarting only the agent is not enough. Restart Wactorz.

Without restarting: publish the address to Wactorz's MQTT broker, then reconnect. Use mosquitto_pub, or Home Assistant's Settings → Devices & services → MQTT → Configure → Publish a packet when it shares the broker:

topic: custom/reachy/config
payload: {"robot_host": "192.168.1.42", "connection_mode": "network"}
@reachy-mini reconnect

An address set this way is remembered, and it overrides the one in .env. The address in use is published in custom/reachy/state as robot_host.

Reachy's packages

The reachy extra installs everything the agent uses, in the versions it was tested with:

pip install 'wactorz[reachy]'

It holds the same list the catalogue installs on a first spawn: the robot SDK (reachy-mini), numpy, pillow, edge-tts for speech, webrtcvad-wheels for voice detection, and deepgram-sdk for voice input. Deepgram needs an API key; text control and speech output do not.

Optional: make Reachy's voice louder with ffmpeg

Reachy speaks without ffmpeg. With it, speech gets a loudness boost that makes it clearly louder, which helps in a noisy room or in front of an audience. Without it, Reachy asks the speech service for its loudest clean voice instead, which is louder than plain speech but not as loud as the boost.

If ffmpeg is missing, Reachy says so once in chat, the first time it speaks, with the command for your system. @reachy-mini health also says whether the boost is on.

Install it on the computer running Wactorz, not on the robot, then restart Wactorz:

System Command
Windows winget install ffmpeg
macOS brew install ffmpeg
Debian, Ubuntu, Raspberry Pi OS sudo apt install ffmpeg

Or turn Reachy up instead: say presenter mode or speak louder.

Hardware warnings and what Reachy can tell you about itself

Say are you overheating (or health, how are you feeling, battery) for what the robot reports about its own condition.

Motor faults, including overheating, are watched automatically. The daemon reads the servos' hardware-error byte several times a second and decodes overheating, overload, electrical-shock and input-voltage faults — but it writes them to its own log and nowhere the SDK can read, not even into the status it serves. Wactorz therefore follows the daemon's log stream (/logs/ws/daemon, the same source the official control app shows its overheating warning from) and raises each fault in chat with what to do about it. The same fault on the same motor is repeated at most every five minutes, because the daemon re-reads the motors continuously and would otherwise produce a warning per read. The watch starts on connect and reconnects on its own, since the stream ends whenever the daemon restarts.

Only the wireless robot serves that stream — the daemon mounts the route behind its wireless flag — so a Lite over USB has no fault watch. health says so explicitly rather than reporting silence, which would otherwise read as "nothing wrong".

There is no battery level, and there is no way to add one. Pollen state it plainly in their FAQ: "We do not have the possibility to check the battery status, that's a known limitation of the design. We only have the led indication for low battery when it's time to charge it (green -> orange -> red)." The charge state is wired to that LED on the foot and reaches no software at all, so health says so outright rather than leaving an absent number to be read as a full charge. Watch the LED, not the dashboard: green is fine, orange means soon, red means charge it now.

An Input Voltage Error from a motor is not a fault here and is never raised as a warning. Reachy Mini runs its servos above their own protection threshold deliberately — Pollen's FAQ says "We are using a higher voltage on Reachy Mini, it's on purpose" — so it appears on healthy robots. It is written to the Wactorz log and left there; warning about it would train you to ignore the faults that matter.

The one temperature available is the IMU's own, reported by health when the robot has an IMU. It is the inertial chip, not a motor, so treat it as the robot's internal ambient — the thing that actually overheats reports through the fault watch above.

Connection modes (advanced)

By default the SDK auto-detects: it probes localhost first, then the robot. If you run the robot wirelessly and do not have the Reachy Mini control app open, pin network so the agent connects straight to the robot and skips the localhost probe:

topic: custom/reachy/config
payload: {"connection_mode": "network"}

When you do want the Reachy Mini control app or its simulator (for example a shared demo, or working with no physical robot), pin local instead:

topic: custom/reachy/config
payload: {"connection_mode": "local"}

After publishing, say reconnect to apply the new mode. You can also set REACHY_CONNECTION_MODE=network (or local) in the environment, which is read at spawn and so needs a restart. The active mode is reported in custom/reachy/state as connection_mode. This only selects where the agent connects — speaker/host audio routing is set separately by media_backend.

If the robot talks but does not move, the agent likely reached the robot's media stream but not its motor control. Use network mode (no control app), or make sure the control app / simulator is running for local mode.

Everyday commands

Plain English works for normal use:

@reachy-mini wake up
@reachy-mini do a happy gesture
@reachy-mini wiggle your antennas
@reachy-mini look left
@reachy-mini say hello
@reachy-mini turn on the light and nod

Ask Reachy for help

Help is built into the agent and works even when the robot is disconnected. In chat—or while an opt-in conversation is running—say:

@reachy-mini help

The full answer shows examples and keywords for movement, speech, voice input, camera, connection status, volume, and Wactorz/Home Assistant. Ask for a shorter topic guide with:

@reachy-mini help movement
@reachy-mini help voice
@reachy-mini help camera
@reachy-mini help connection
@reachy-mini help volume
@reachy-mini help home

Natural questions work too: what can you do?, how do I use the camera?, and how can I start a conversation?. In voice mode, Reachy speaks a short answer and puts the complete command guide in its dashboard thread.

Other agents can send the same requests directly:

await agent.send_to("reachy-mini", "do a happy gesture")
await agent.send_to("reachy-mini", "say hello")

Use Reachy as the Wactorz interface

Use the explicit ask Wactorz prefix in chat to bypass Reachy's local robot planner:

@reachy-mini ask Wactorz what's the weather in Athens?
@reachy-mini ask Wactorz turn off the living-room light
@reachy-mini ask Wactorz is the living-room light on?

The prefix forwards the remaining text to main with _via_interface=True for restricted conversation, everyday Home Assistant device control, and delegation to its existing bounded allowlist. Main accepts this context only from a reviewed local catalogue program; that admission does not authenticate the original caller. Robot voice, agent tasks and MQTT input cannot issue operator commands, approve plans, or create or delete executable agents through this bridge. Type administrative commands directly in main's operator chat. Payload flags and source labels do not grant authority. ask Wactorz needs the agent on main: from a node it has no route there, since main does not take tasks from nodes, and Reachy answers from its own commands instead. The final text is returned to chat and spoken through Reachy's speaker. Without the prefix, Reachy handles its own robot, camera, speech, microphone, and Home Assistant commands first; unhandled text can still fall through to main, but ask Wactorz is the deterministic interface route.

The full path is:

text to @reachy-mini -> reachy-mini -> main -> selected Wactorz agent/tool
                    <- spoken and text answer <-

Push-to-talk voice input

Voice input is an explicit, one-shot command. It records a bounded clip, transcribes the WAV, sends the transcript through the same _bridge_to_main interface path above, returns the answer to chat, and speaks it through Reachy:

@reachy-mini listen and ask Wactorz

Or over MQTT:

topic: custom/reachy/cmd/ask_voice
payload: {"duration": 5}

ask_voice remains one-shot. There is deliberately no always-on microphone or wake word. The default backend is hosted Deepgram Nova-3. It needs an API key, see step 5. ask_voice uploads one bounded WAV clip; conversation mode streams Reachy's WebRTC microphone as mono PCM while the user speaks:

# Hosted default
pip install 'deepgram-sdk>=3,<4'
DEEPGRAM_API_KEY=...
REACHY_STT_BACKEND=deepgram
REACHY_STT_MODEL=nova-3

# Local alternative; audio stays on this machine
pip install faster-whisper
REACHY_STT_BACKEND=faster-whisper
REACHY_STT_MODEL=Infomaniak-AI/faster-whisper-large-v3-turbo

# Alternative local implementation
pip install openai-whisper
REACHY_STT_BACKEND=whisper
REACHY_STT_MODEL=base

# Hosted OpenAI transcription (explicit opt-in; audio leaves the host)
pip install 'wactorz[openai]'
REACHY_STT_BACKEND=openai
REACHY_STT_MODEL=gpt-4o-transcribe
OPENAI_API_KEY=...

Optional REACHY_STT_LANGUAGE, REACHY_STT_FALLBACK_LANGUAGE, REACHY_STT_DEVICE, REACHY_STT_COMPUTE_TYPE, and REACHY_STT_HOTWORDS settings tune language, uncertain-language fallback, local inference, and recognition bias. REACHY_STT_TIMEOUT_S bounds hosted calls and defaults to 60 seconds. Use REACHY_STT_LANGUAGE=multi and REACHY_STT_STREAM_LANGUAGE=multi with Nova-3 for English and Greek in one conversation; set either to en or el to constrain a session. Short utterances whose language probability is below stt_min_language_probability (default 0.60) are retried in the configured fallback language; unresolved guesses are silently discarded instead of being routed as commands. The MQTT payload can override these settings with stt_backend, stt_model, language, stt_fallback_language, stt_device, stt_compute_type, stt_hotwords, and stt_min_language_probability. Keys are read from the environment and are never embedded in the recipe.

custom/reachy/events reports transcript, capture_duration_s, transcription_duration_s, response_text, total_duration_s, ok, error, type, and ts. Failures also carry a stage: capture_failed, transcription_failed, empty_transcript, routing_failed, or speech_failed. Completed-stage fields remain present on failures for diagnosis.

Before each clip the recorder drains a short, bounded queued WebRTC pre-roll. It captures for the requested wall-clock duration even if the SDK yields buffered samples faster than real time, and then retains only the newest requested-duration audio. This prevents old queued audio from becoming the start of a new transcription.

Opt-in conversation mode

Start a natural multi-turn session explicitly:

@reachy-mini start conversation

Or over MQTT:

topic: custom/reachy/cmd/conversation_start
payload: {}

Main is the single conversational brain; the optional catalogue agent makes Reachy its embodied microphone, speaker, and gesture surface. Home Assistant actions and normal Wactorz tools follow Main's existing route. The current utterance is sent as plain executable text, while up to four prior turns travel separately as structured reference context. An older command can therefore help resolve "it" without becoming part of the new command.

Reachy declares its available gestures in generic interface metadata. Main may return a validated <interface_action> block for the catalogue agent to execute, so a less-literal embodied request can still move the robot without a Main → Reachy delegation loop. Wactorz core contains no Reachy dependency; without the catalogue agent, Main behaves exactly as before.

With Deepgram selected, each turn streams the PCM frames already being read from Reachy's WebRTC microphone. Local WebRTC VAD remains responsible for confirmed speech onset, motor-noise rejection, cancellation, and inactivity limits. Deepgram endpointing normally closes the turn after 500 ms of silence, with a 1200 ms utterance-end backstop. Interim recognition is published on custom/reachy/events while the user speaks. If the stream cannot start, disconnects, or returns no final transcript, the completed local capture goes through prerecorded Deepgram transcription without asking the user to repeat. The complete reply appears in Reachy's dashboard thread before playback begins, and the same sanitized reply is spoken in sentence-sized chunks without replacing its ending with a "rest in Wactorz chat" notice. Recognized speech stays in the same thread, labelled as an interface-mediated exchange; Main remains internal reasoning metadata. Raw service calls and planner details remain available in conversation diagnostics as raw_response, not ordinary chat. Execution receipts such as ran 4 of 4 are also hidden by default; say enable debug to show them and disable debug to return to the normal user-facing view. Debug always starts off after an agent restart. Punctuation-only recognition noise is ignored.

Prerecorded conversation turns auto-detect the spoken language. Streaming uses stt_stream_language (or REACHY_STT_STREAM_LANGUAGE), which defaults to multi: English and Greek in the same conversation. Set it to en or el to keep a session to one language. Common names and device terms are supplied as hotwords; override them with stt_hotwords or REACHY_STT_HOTWORDS. Common mishearings such as "Richie", "Riti", "Ritzy", and "Lizzy" are corrected to "Reachy" when used as the robot's name. Main is explicitly told that these variants refer to Reachy, never the user, and it addresses the user by name only after a clear naming statement or a durable saved fact. Local Faster Whisper also enables its VAD, disables previous-transcript conditioning, and reports confidence/no-speech scores. Results below stt_min_confidence (default 0.25) or above stt_max_no_speech (default 0.60) are silently discarded without consuming a turn.

Speech comes back out in whatever language the reply is written in. TTS_VOICE sets the voice; a Multilingual edge-tts voice (en-US-BrianMultilingualNeural, en-AU-WilliamMultilingualNeural, ...) pronounces every supported language itself, so Reachy keeps one voice across English and Greek. Any other voice speaks a single language and would read Greek out as Unicode letter names, so Greek text is redirected to TTS_VOICE_EL instead - el-GR-AthinaNeural (female) by default, or el-GR-NestorasNeural (male); edge-tts ships no others. A per-call {"voice": "..."} on say overrides both.

Confident auto-detected languages become a session hint for later ambiguous turns. Voice-originated turns create no durable personal facts unless the user explicitly says to remember or save something. This prevents a bad transcript from becoming the user's name or household profile while preserving intentional voice memory.

Greek and English requests to lower or raise Reachy's own voice are handled locally as robot speaker-volume changes rather than being sent to Home Assistant.

Idle presets

Amplitude, tempo, which joints move and how often attract beats play are five independent settings, and nobody wants to reason about five settings with an audience already in front of the robot. A preset sets all of them at once:

Preset What it looks like
off The default. Completely still. Motors stay live and every command still works — this is stillness, not sleep.
calm Barely moving, and slower as well as smaller. Breathing that is only shallower reads as a robot turned down; breathing that is also slower reads as something at rest.
antennas Antennas alive, head and body held absolutely still. For a plinth where a sweeping head is a hazard, or when he should look like he is listening rather than performing.
alive What you get when you turn ambient motion on without naming a preset. Breathing, gaze drift, an attract beat every half minute or so.
showtime Bigger and quicker, with beats two to three times as often. Too much for a quiet room, and meant to be.

Set it whichever way is nearest to hand:

{"cmd": "life", "preset": "showtime"}
REACHY_IDLE_PRESET=alive                        # .env, at boot
custom/reachy/config {"idle_preset": "calm"}    # persists

Or just say it — this is the control you reach for with people watching, so it works out loud, in English or Greek:

"calm down" · "settle down" · "antennas only" · "showtime" · "show off" · "stop moving" · "alive" · "back to normal" "ηρέμησε" · "μόνο τις κεραίες" · "μη κουνιέσαι" · "πιο ζωηρά" · "κανονικά"

Naming a preset next to any word meaning how you move also works, so "set preset animation alive", "idle showtime" and "motion calm" all land. A bare preset name is matched only as the whole message: "alive" changes the preset, "are you alive?" stays a question.

If ambient motion is ever held down by a flag that outlived whatever set it, it releases itself after 25 seconds and logs which flag it was. Nothing legitimate holds one that long, and the alternative — a robot that stops moving permanently and silently while every command still reports success — is the worst failure this feature has.

{"cmd": "life"} with no arguments reports the current preset and lists the rest with a description of each. Individual settings are applied after a preset, so {"preset": "calm", "attract": true} reads the way it looks: that mood, with one deliberate exception.

Ambient motion

A robot holding one pose perfectly still is hard to tell from a prop, which matters most in a room where people are walking past. REACHY_IDLE_LIFE=1 (or {"cmd": "life", "enabled": true}, or custom/reachy/config {"idle_life": true}) keeps a small amount of motion going: breathing on a 4.3s cycle, a slow weight shift on 11.3s, gaze that settles somewhere for a few seconds and then moves, and an occasional asymmetric antenna flick. The three periods do not divide into each other, so the sum never visibly repeats. Off by default.

It cannot take the robot away from you, because it never names an absolute target. Every offset is added to the pose your last command established, so a pose moves the base and ambient motion breathes around the new one. It also stands down completely while any command is in flight (busy), while Reachy is speaking, and while he is asleep. Scale it with {"cmd": "life", "amplitude": 0.5} or REACHY_IDLE_LIFE_AMPLITUDE — 1.0 is the tuned default and 1.5 the maximum, and the hard ceilings in the code apply on top of whatever you set.

A commanded pose is held and then released. It stays put for about three and a half seconds, then eases back toward neutral over another two and a half. A pose is transient intent, not a new resting posture: without this, aiming his head down for a describe left him breathing politely at the floor until something else moved him. The direction he is facing is never relaxed away — turn him toward the room and he stays turned. Set REACHY_IDLE_RELAX=0 or {"cmd": "life", "relax": false} to pin a pose exactly where you put it.

After look_at, look_pixel or an emotion clip the head pose has no name in pose space, so ambient motion leaves the head alone and keeps only the antennas alive. He holds that gaze for the same few seconds, then makes one smooth interpolated move back to neutral and resumes — a pause, never a dead end.

Attract beats

Breathing stops him reading as switched off. It does not make anyone cross a room. Every 18-45 seconds, when nothing else is happening, Reachy plays one larger move drawn at random without immediate repeats: scan (a slow sweep of the room), perk (head cock, antennas up), double_take (glance away, snap back), stretch, muse. Each runs as a real trajectory under the motion lock with busy set, so it yields to your commands exactly as ambient motion does, and ends at neutral.

They are suppressed while Reachy is mid-turn in a conversation — a big move while someone is being listened to reads as not paying attention. A session that is merely open and waiting is fine. Turn them off with REACHY_ATTRACT=0 or {"cmd": "life", "attract": false}, retime with REACHY_ATTRACT_MIN_GAP / REACHY_ATTRACT_MAX_GAP, or fire one on demand to check it reads from where the audience will stand:

{"cmd": "life", "beat": "perk"}

When ambient motion is on, spoken replies are animated against their own word timings: edge-tts reports the offset and duration of every word it synthesises, so accents land on the words rather than on a timer that would drift against the sentence within a couple of seconds. A small lift at the start of an utterance and a settle at the end give it a beginning and an end. Opt out for one line with {"cmd": "say", "text": "...", "speech_motion": false}.

Emoji never reach the synthesiser. edge-tts does not skip them — it reads their Unicode names aloud, so a cheerful reply ended with Reachy solemnly announcing "smiling face with smiling eyes". They are stripped at synthesis, so every path is covered: a direct say, a spoken vision description, or a reply the planner wrote. Dashes, curly quotes and ellipsis are deliberately kept; they belong in speech.

Audio is intentionally plainer than the dashboard response. Emoji, Markdown role-play directions such as *waves*, links, and raw Home Assistant service/entity syntax stay visual. Reachy speaks a short human acknowledgement instead; for example, Done: light.turn_on -> light.main_light becomes "Okay, the light is on", or "Okay, the light is pink" when that was the request.

Reachy applies the compatible parts of Pollen's conversation tuning to the XVF3800 audio processor. A firmware-owned nonlinear-attenuation flag is intentionally left untouched; the robot can force its readback even after applying all useful echo/noise settings. On some physical robots the microphone still hears the entire speaker utterance, so a simple VAD monitor cannot reliably distinguish Reachy's voice from a human interruption. Automatic barge-in therefore defaults off and normal replies play to completion.

Set "barge_in": true only as an experiment on hardware with verified acoustic echo cancellation. In chat, start conversation with interruption (also start interruptible conversation or start conversation with barge in) sets the same flag without hand-writing JSON; plain start conversation leaves it off. Either way the reply to the start command says which mode you are in, so a robot that will not be talked over is distinguishable from one that is ignoring you. In that mode the monitor ignores the first 450 ms of speaker startup, then requires about 210 ms of sustained voice onset. Onset is treated as a suspicion rather than a verdict: the sentence in progress finishes, and the recording is then checked before it counts. It has to carry at least barge_verify_min_speech_s of voice — defaulting to barge_min_speech_s, the same floor used to call it an utterance in the first place, since a stricter one here only discards real interruptions — transcribe to something the recogniser stands behind, and not repeat the words Reachy was speaking — his own voice satisfies every acoustic test, so the only thing that separates it from a person's is what was said. That check transcribes with the recogniser's own VAD switched off (stt_vad_filter): the clip was recorded while the loudspeaker was playing and has already been gated by Reachy's VAD, and running a second one over it discards the speech it was meant to protect. The check runs alongside the next sentence rather than between sentences: it costs a recogniser pass — seconds on the robot — and Reachy's own voice trips the onset on nearly every sentence, so waiting for it put that pause into every gap. One check runs at a time, and its answer is taken as soon as the sentence in progress ends. A confirmed interruption stops the reply and is routed as the next turn, carrying the transcript already made for the check rather than deriving it twice; an unconfirmed one is discarded and he keeps talking. The cost of a real interruption is the rest of one sentence, which reads as letting him finish rather than as ignoring you. A typed stop, silence, quiet, or shut up still cuts the current reply immediately without ending the conversation. Spoken stop phrases work while Reachy is listening, but reliable spoken interruption during TTS requires a true full-duplex realtime audio pipeline rather than this cascaded STT -> LLM -> TTS path.

Stop with stop conversation, stop the conversation, stop listening, end conversation, end the conversation, goodbye Reachy, goodbye, bye, that's all, σταμάτα, σταμάτα να ακούς, τέλος συζήτησης, or αντίο. You can also stop from chat or MQTT at any stage:

@reachy-mini stop conversation
topic: custom/reachy/cmd/conversation_stop
payload: {}

Only one conversation can run at a time. By default it listens until a spoken stop phrase or conversation_stop; set a positive inactivity_timeout to add an idle timeout. Set a positive max_turns only when a bounded session is wanted. Optional start fields include silence_s, max_utterance_s, min_speech_s, pre_roll_s, flush_s, vad_mode, vad_min_rms, cooldown_s, barge_in, barge_guard_s, barge_onset_s, barge_silence_s, barge_min_speech_s, barge_flush_s, barge_min_rms, barge_verify_min_speech_s, voice_friendly, state_motion, idle_motion, stt_language, stt_streaming, stt_stream_language, stt_endpointing_ms, stt_utterance_end_ms, stt_finalize_timeout_s, stt_hotwords, stt_min_confidence, stt_max_no_speech, and max_turns. Barge-in defaults to false and is enabled only by an explicit barge_in:true; all physical conversation motion defaults to false.

Set state_motion:true (or REACHY_CONVERSATION_STATE_MOTION=1) for subtle listening/speaking antenna cues. These use antenna-only set_target calls and do not command or reset the head. Conversation states are published on custom/reachy/events; events also report session_id, turn_index, interim_transcript, transcript, response, raw_response, spoken_response, interrupted, timings, stop_reason, ok, error, and ts.

Physical listening motion defaults to false because Reachy's antenna servos are audible to its live microphone and can become convincing transcription false positives. The robot stays mechanically still while recording; personality remains in deliberate response gestures and the ambient-life layer. Set idle_motion:true or REACHY_CONVERSATION_IDLE_MOTION=1 only to experiment on hardware with quiet servos. The opt-in motion uses small, eased antenna sweeps, stops when voice activity is confirmed, and never moves the head. Short mechanical bursts that trip VAD are rejected before the recognizer and do not consume a turn or error budget, but keeping motors still is the reliable default.

For bilingual English/Greek use, set both REACHY_STT_LANGUAGE=multi and REACHY_STT_STREAM_LANGUAGE=multi with Nova-3. When local VAD closes a turn, the streaming client sends Deepgram Finalize and waits briefly for the final transcript before falling back to a prerecorded request using the same captured audio. This avoids closing the WebSocket while its final result is still in flight.

Embodied requests stay on the robot. "Turn left" and "turn right" rotate the body 45 degrees relative to its current heading; an explicit angle such as "turn left 90 degrees" overrides the default within Reachy's safe range. "Do a little dance", "turn around", "nod", "shake your head", "wiggle your antennas", and "look curious" run safe, explicit physical poses instead of going to the Wactorz LLM for pretend role-play. "What do you see?" and other room-view questions make Reachy scan with its own camera; requests specifically about the view in front capture a single forward frame. The dance ends with a short spoken "Ta-da!"; the full action result remains visible in chat.

The Reachy playback API remains fire-and-forget, so non-interrupted turns use Edge TTS word-boundary duration plus a tail pad and cooldown. Explicit stop and barge-in both cut playback immediately. A plain chat "stop" is treated as "stop talking" and produces no acknowledgement bubble unless debug mode is enabled. Local transcription already running inside a native STT library cannot be forcibly terminated, but its result is discarded after session cancellation.

Structured commands

Request all help or one help topic without an LLM call or robot connection:

{"cmd": "help"}
{"cmd": "help", "topic": "camera"}

For direct control, send a dict with cmd:

Command Purpose
help All help or one topic: movement, voice, camera, connection, volume, home
wake, sleep, stop Basic robot state
pose Head yaw, pitch, roll, x/y/z
antennas Left and right antenna angles
gesture Physical dance, persistent turn_around, nod, shake, wiggle, or curious choreography
face_forward Return from a rear-facing orientation to the user
look_at, look_pixel Gaze target
camera Capture one still frame from the onboard camera (base64 JPEG/PNG)
describe Look through the camera and speak a description of the scene (vision LLM)
look_around Scan several camera angles and describe the surrounding room
look_behind Turn rearward, describe that camera view, and remain rear-facing
debug Opt in or out of action-sequence receipts (enabled: true/false)
listen Record a short mic-array clip (base64 WAV) with direction of arrival
ask_voice Push-to-talk WAV → STT → main Wactorz route → spoken answer
conversation_start, conversation_stop Opt-in VAD multi-turn Wactorz interface
doa Report the mic array's current direction of arrival, no recording
emotion, list_emotions Recorded gesture clips
say, volume Speech and speaker volume
life Ambient idle motion on/off, and its amplitude
ha Home Assistant request
bind, unbind Persistent reaction to an MQTT/HA event

Examples:

{"cmd": "wake"}
{"cmd": "pose", "yaw": 30, "duration": 0.6, "method": "minjerk"}
{"cmd": "antennas", "left": 45, "right": -45, "duration": 0.3}

Camera and microphone

Reachy's onboard camera and microphone array are exposed as commands. The captured bytes come back in the command result (and, optionally, on a one-shot MQTT topic or saved to a file) — they are never written into the retained custom/reachy/state heartbeat.

Capture a still frame (returns image_b64, plus width/height):

{"cmd": "camera"}
{"cmd": "camera", "format": "png", "path": "/tmp/shot.png", "publish": true}

Record a short mic clip (returns audio_b64 WAV, samplerate, channels, duration_s, and a best-effort doa_deg):

{"cmd": "listen", "duration": 3}

Direction of arrival only, without recording:

{"cmd": "doa"}

These commands require a video/audio-capable media backend and that the daemon holds the camera and microphone (no Hugging Face app running on the robot).

camera does not save the frame anywhere by default — the image comes back as base64 in the command result. Pass path to write it to disk or publish to emit it on custom/reachy/camera.

See and describe

describe captures a frame, sends it to the vision-capable LLM, and speaks the real description — unlike camera + say, which would only capture a frame and then make up a line. Plain English "what do you see?", "what's in front of you?", "describe the scene", and "look around" all route here. "Behind you" and "look behind you" use the dedicated look_behind path: Reachy turns to a mechanically safe 155-degree rear view, captures without recentering, and stays there. Say "face me" or "turn back" to return forward.

{"cmd": "describe"}

Ask a specific question about the view, or get the text without speaking it:

{"cmd": "describe", "question": "how many people are here?"}
{"cmd": "describe", "say": false}

This needs the same video-capable media backend as camera, plus a configured LLM provider (the model must support images).