ReachyPi

Run the Reachy Mini Lite wirelessly

Reachy Mini Lite USB without cable and the official app, via a Raspberry Pi 5 running reachy-mini-os.

The Lite normally tethers to a computer over USB. ReachyPi gives you a Pi 5 SD-card image so the robot runs standalone — motors, camera, sound, and the official app over Bluetooth all work (tested on a Pi 5, daemon v1.8.4).

Getting started

1. Download the image: ⬇ latest build (.zip, ~1.6 GB) — or build it.
2. Flash it to an SD card, then boot it (now wireless).

_{🛠️ Flash with Raspberry Pi Imager — "Use custom" → the .zip
⚠️ In the customization, don't set a user (it renames pollen and breaks the robot); wifi is fine.}

Build

The build runs in Docker, so any OS works (a Raspberry Pi builds it natively).

Install Docker and start it

OS	Docker
Ubuntu / Debian / Raspberry Pi OS	sudo apt install docker.io
Arch	sudo pacman -S docker
Fedora	sudo dnf install docker
macOS	Docker Desktop (or brew install --cask docker)
Windows	Docker Desktop with the WSL2 backend
other Linux	curl -fsSL https://get.docker.com | sudo sh

On Linux, start it with sudo systemctl enable --now docker. On macOS/Windows, just launch Docker Desktop (on Windows, run the build from a WSL2 terminal).

Build the image

sudo modprobe loop      # often already loaded (Ubuntu) — needed on Arch
docker build -t reachy-pi5 .
docker run --rm --privileged -v "$PWD/deploy:/pi-gen/deploy" reachy-pi5

Image lands in ./deploy/*.zip, then flash it (see Getting started).

Override the daemon version with docker build --build-arg DAEMON_VERSION=v1.8.4 -t reachy-pi5 .

CM5 variant (Wireless carrier)

The Reachy Mini Wireless ships a CM4; a CM5 pops right into the carrier (see the community swap thread). Dockerfile.cm5 builds the image for that swap: motor UART on uart2-pi5 with the same udev alias, external antenna kept, the CSI camera keeps libcamera (do not use the Pi 5 image there, its camera fix targets the Lite's USB camera), and the WebRTC stream encodes with x264 in software since the CM5 has no hardware encoder (docker/stage-cm5-fixes.sh).

docker build -f Dockerfile.cm5 -t reachy-cm5 .
docker run --rm --privileged -v "$PWD/deploy:/pi-gen/deploy" reachy-cm5

An eMMC CM5 flashes through rpiboot/usbboot rather than an SD card. ⚠️ Not yet tested on hardware: the CM5 camera timeout reported by the community is an open question this image may still hit.

First boot & SSH if needed

The image ships the pollen user with SSH enabled — nothing to set up in Imager.

ssh pollen@reachy-mini.local      # password: root
passwd                            # change it

• Web UI / API: http://reachy-mini.local:8000/
• Pair from the app's BLE SETUP → ReachyMini

Everything (services, the venv, sudo) is built around pollen — that's why you must not set a user in Imager.

How it works

The Dockerfile downloads reachy-mini-os, patches config.txt (Pi 5 motor UART, antenna), pins the daemon, and bakes the fixes from docker/stage-pi5-fixes.sh. Each fix lives in /etc, /usr/local, or sitecustomize.py, so it survives reboots and daemon self-updates.

Changelog

Each release and what it brought is in CHANGELOG.md.