Quickstart | PeppySkip to content

Quickstart

Three steps take you from nothing installed to a bimanual OpenArm you can drive from your browser. There is no repository to clone and no robot hardware to plug in: the arms, the grippers, and the physics all run in a MuJoCo simulation on your machine.

This page is a demo, not a tutorial. It exists so you can watch a peppy stack work end to end before you learn how one is put together. To learn how one is put together, start at Installation and work through the guides, which build a stack up node by node from an empty directory.

Peppy runs on Linux (x86_64/aarch64, tested on Ubuntu 24.04, Fedora, and Arch Linux) and macOS (aarch64).

Watch it instead<br>Section titled “Watch it instead”

The video below is this page in video form: the same three steps, run start to finish on a real machine. It starts a simulation of the OpenArm 2.0 robot in MuJoCo and teleoperates it from the browser. Watch it first if you would rather see where you are headed, then follow the written steps to do it yourself.

Step 1: Install peppy<br>Section titled “Step 1: Install peppy”

Run the installer:

Terminal windowcurl -fsSL https://peppy.bot/install.sh | sh

It drops the peppy CLI on your PATH, registers the background service that builds and supervises nodes, and configures the Apptainer container runtime the simulation nodes are built on.

Confirm the CLI and the service are both there:

Terminal windowpeppy info

It prints the CLI version and container setup, then a Daemon Info block. That block is the background service answering, so seeing it means everything is up.

To read just the CLI version without contacting the daemon, run peppy --version (or -V); it prints the version alone from the binary itself.

If your shell reports peppy: command not found, apply the PATH update the installer printed (source ~/.bashrc, or whichever file it named) and run it again. Shells opened afterwards pick it up on their own.

Installation covers version pinning, skipping the service, and managing it afterwards.

Step 2: Launch the simulated robot<br>Section titled “Step 2: Launch the simulated robot”

A launcher is one file listing the nodes that make up a robot, with the parts that vary (which robot fills the arms, which control surface drives them) selected at launch time with --with. The OpenArm launchers ship with peppy and the installer indexed them, so you can start openarm_v2 by name, picking the MuJoCo simulation and the browser control panel:

Terminal windowpeppy stack launch openarm_v2 --with=mujoco,web_commander

That single command adds, builds, and starts every node in the selection, in dependency order: eight instances across six node types. The cast is the MuJoCo engine, one relay per limb (two arms, two grippers), the readiness aggregator that waits for every limb’s physics to come alive, the backbone that coordinates both arms, and the browser control panel. It prints Launch complete when the stack is up.

The command then returns; it is not a foreground supervisor. The nodes keep running under the peppy background service, so you can close that terminal without stopping them.

This is the node stack you just launched<br>Every circle is one instance the launcher started, and every arrow a link between two of them. Together they are the node stack: the set of nodes the background service is running for you. peppy stack list prints the same set as a table.<br>commander_instbackbone_instleft_arm_instright_arm_instleft_grip_instright_grip_instrobot_init_instsim_instcommandsreadinessengine linksEach pairing streams measured state back the other way; the panel also observes the four relays.

Note<br>The first launch pulls the MuJoCo simulation image (a few hundred megabytes) and converts it into a local Apptainer image, so expect it to take a while; later launches reuse the cached image. Download and image-assembly progress counts as build output, so a slow connection won’t trip the build idle timeout on its own. If a build of yours genuinely goes quiet for minutes (no output and no bytes written to disk), raise the window with --node-build-idle-timeout-secs.

Step 3: Drive the arms<br>Section titled “Step 3: Drive the arms”

Once the launcher prints Launch complete, open two browser tabs:

AddressWhat it ishttp://localhost:8080 the MuJoCo viewer, showing both arms in the simulated worldhttp://localhost:8765 the openarm_commander control panel<br>Put them side by side. The panel opens in Streaming mode, with a card per arm: press Enable on one, drag any of its joint sliders or its gripper slider, and that side follows your input live in the viewer. The mode switch has three more modes to try once the arms move: Actions for one governed move to a target you compose, Gestures for a baked choreography, and Motors for a read-only view of every motor’s health.

To shut things down, stop instances one at a time:

Terminal windowpeppy node stop commander_inst

Or tear the whole stack down at once, which stops...