Simulation installation

Whether you don’t have a Reachy 2 robot yet or you simply want to prototype without using the real robot, the simulation is the perfect place to start.

The simulation environment replicates the behavior of the real Reachy 2 robot, allowing you to prototype and test your programs — even if you don’t have a physical robot.

It behaves similarly to the fake mode of the core service available on a real Reachy 2, meaning you can control the robot as if it were real, but without any hardware dependencies.

What works:

  • Full compatibility with the Python SDK
  • Access to the ROS 2 interface, just like with the real robot
  • Accurate simulation of robot movements and responses

🚫 What’s not included:

  • Camera access is not available in simulation
  • The WebRTC service is not simulated, meaning teleoperation features are not supported

To use it, we provide a preconfigured Docker image that let you explore and develop for Reachy 2 on any operating system. In just a few steps, you’ll be able to interact with a fully simulated robot, ideal for testing behaviors, building applications, or just getting familiar with the platform.

Don’t hesitate to check out the Python SDK section to get started with programming the robot in simulation!

Installation

You can set up the simulation in two ways:

From Docker Hub

1. Install Docker

Download Docker Desktop for your OS and follow the install instructions.

Install Docker Desktop

You don’t need to be logged in, as the image is open.

Additional platform-specific instructions

MacOS (Apple Silicon)

Apple Silicon (M1/M2)
For Apple Silicon Macs, Docker uses Rosetta to run x86_64 images.
Follow these steps after installing Docker Desktop:

  1. Install Rosetta: Run the following command to install Rosetta:
softwareupdate --install-rosetta
  1. Enable Rosetta in Docker:
  • Go to Docker settings > General
  • Check Use Virtualization Framework
  • Check Use Rosetta for x86/amd64 emulation on Apple Silicon
  • Click Apply & Restart

If the Rosetta integration option is not available, update your macOS version (it should be available from macOS Sonoma (v14)).

  1. Check Emulation: To verify that emulation is working, run:
docker run --rm --platform linux/amd64 busybox uname -m

This should output x86_64 if emulation is working.

2. Run the Robot Simulation

Option 1: Via Docker Desktop (GUI)
  1. From Docker Desktop, search for reachy2 image in the search bar (you don’t need to sign in):

    Search for reachy2 image

  2. Click Pull and wait a few minutes for the image to be downloaded:

    Pull reachy2 image

  3. When the download is over, click Run to launch a container of the image via the Docker Desktop GUI. This will open a configuration pop-up.

    Run reachy2 container

  4. Make sure you expand the Optional settings to configure properly the ports, and configure the port as shown below:

    Expand container settings

    Configure settings

  5. Click Run to finally launch the container!

    Finally run the container

  6. After a few seconds, you should have a running container displaying the following elements:

    Container is running

Option 2: Via Command Line Interface (CLI)

If you prefer using the terminal, you can run the following command:

docker run --rm --platform linux/amd64 -p 8888:8888 -p 6080:6080 -p 50051:50051 --name reachy2 docker.io/pollenrobotics/reachy2

This is a one-liner that launches the container with the required ports exposed.

If using an Apple Silicon (aarch64) platform, add --platform linux/amd64 to the command.

Note: you have a terminal accessible from Docker Desktop

Terminal in Docker Desktop

You can simply enable it:

Enable terminal in Docker Desktop

and run the previous command:

Run command line

Running with Gazebo

To launch the simulation with Gazebo and additional configurations, you can add arguments to the CLI command like this:

docker run --rm --platform linux/amd64 -p 8888:8888 -p 6080:6080 -p 50051:50051 --name reachy2 docker.io/pollenrobotics/reachy2 start_rviz:=true start_sdk_server:=true fake:=true orbbec:=false gazebo:=true

3. Access the Displays

Rviz/Gazebo

To access Rviz or Gazebo, open the following URL in your web browser: localhost:6080/vnc.html?autoconnect=1&resize=remote⁠

Jupyter Notebook

To access the notebook interface, go to: localhost:8888/tree

Those two links are available in the logs when the container is launched:

Displays links in the logs

Displays links in the logs zoom

From GitHub (not available yet)

Coming soonWe will thus assume that you already have docker installed and setup.

Clone the sources of our docker, and pull the sources:

git clone git@github.com:pollen-robotics/docker_reachy2_core.git  
cd docker_reachy2_core  
./sources checkout stable  

Then download the configuration files:

git clone git@github.com:pollen-robotics/reachy_config_example.git
cp -r reachy_config_example/.reachy_config ~/

In your docker_reachy2_core folder, compose a container with:

docker compose -f mode/dev.yaml up -d core

This can take a few minutes to compose.

Build:

full_build
cbuilds

In a first terminal, launch the robot server:

# terminal 1
docker exec -it core bash
ros2 launch reachy_bringup reachy.launch.py fake:=true start_sdk_server:=true start_rviz:=true

Keep this terminal open, and in a second terminal:

# terminal 2
docker exec -it core bash
python3 dev/reachy2-sdk/src/example/draw_square.py

If you have the Python SDK installed on your computer, you can launch the example outside the container.