An open-source harness for real-world manipulation inference and experiment management.
Website · Documentation · Quick start · Try GUI · 中文
Dream-1 on YAM, through RoboGUI. Watch a real-robot run with live camera views, robot state and predicted action chunks in one workspace.
-
2026-10-30 — Added ChunkTrust AHS for adaptive action-chunk execution horizons, with backend capability checks for RTC+AHS (PR #25). Added Poke-Aurora API support, including a calibrated YAM example; no local model service is required.
-
2026-10-22 — Support for Franka FR3 with Robotiq gripper and the RPent agent.
- One deployment workflow. Connect supported policies and robot stations through shared configuration, then inspect and control runs in RoboGUI.
- Inference as an experiment variable. Compare serial, asynchronous and model-supported sampling strategies while recording their configurations and execution traces.
- Records you can revisit. Keep trajectories, camera recordings and task-defined human evaluations together for replay, analysis and comparison.
ManiMux sits between policy servers and robot hardware, coordinating observation/action adaptation, scheduling, execution, and experiment records. Model frameworks own inference; RoboGUI provides the operator workspace.
View the static diagram
Architecture and extension protocols · Inference guide
| Embodiments | Policy & Harness & API | Inference |
|---|---|---|
Arm
|
Policy
|
|
✅ Integrated. Models are listed under their serving framework; station support varies. Unmarked hardware entries are experimental. See the support catalog and supported combinations for compatibility and validation scope.
Requires Python 3.11 or 3.12 and uv.
Launch the operator GUI with synthetic data — no robot, camera, or model server required.
The key flags are --robot yam --demo.
git clone https://github.com/SII-LiuLab/manimux.git
cd manimux
uv sync --dev
uv run manimux-robogui --robot yam --demo --host 127.0.0.1 --port 8086Then open http://127.0.0.1:8086 in your browser.
| Flag | Meaning |
|---|---|
--robot yam |
Use the YAM RoboGUI preset (also piper, aloha, franka_fr3_robotiq; --list-robots lists all; tianji needs its vendor SDK) |
--demo |
Drive the UI with synthetic joint/camera streams; no hardware I/O |
--host / --port |
Bind address for the local web UI |
Other presets (same environment, different port if needed):
uv run manimux-robogui --robot piper --demo --host 127.0.0.1 --port 8087
uv run manimux-robogui --robot aloha --demo --host 127.0.0.1 --port 8088The hardware-free example study adds the runtime: a synthetic robot and policy, so Prepare, Start, Finish, scoring, counted trials and recordings all work without a station file. Run the two commands in separate terminals (stop the demo above first; both use port 8086):
uv run manimux-robogui --robot yam --host 127.0.0.1 --port 8086
uv run manimux run --config-list manimux/configs/lists/example-synthetic.yamlModel environments and checkpoints are needed only for real-robot deployment below.
Real-robot commands read a private station file that binds CAN/IP addresses, camera serials, service endpoints and the checkpoint root. Create it once from the matching template, then fill it in (station guide):
cp manimux/configs/local/yam_example.yaml manimux/configs/local/station.yaml # Git-ignored
git submodule update --init third_party/XPolicyLab # local XPolicyLab models (Pi05, DP, ...)
uv run manimux inspect --config <experiment.yaml> # read-only: resolved config, no hardwareA deployment is four services: the camera server, the model server (none for hosted
APIs such as Dream-1), RoboGUI and the runtime that drives the robot. manimux up
starts all of them at once, each in its own tmux session, and holds the terminal.
Ctrl-C stops all of them at once, runtime first, so the robot is cleaned up before the
cameras and model go away.
uv run manimux doctor --config <experiment.yaml> \
--runtime-python envs/yam/.venv/bin/python --policy-python <model-env>/bin/python # read-only
uv run manimux up --config <experiment.yaml> \
--runtime-python envs/yam/.venv/bin/python --policy-python <model-env>/bin/python --open
# ... operate in RoboGUI (Prepare, Start, Finish) ...
# Ctrl-C -> stops runtime, model, cameras and RoboGUI- Hosted model APIs such as Dream-1 have no model server: omit
--policy-pythonand export their API key in this terminal first. - If runtime cleanup blocks (for example while waiting for hardware recovery), the terminal says so and keeps everything alive. Use RoboGUI recovery, or support all arms and payloads and press Ctrl-C again to force-kill every service.
- Lost the
upterminal? Rerun the sameupcommand; it attaches to the running services, and Ctrl-C stops them. - From another terminal:
uv run manimux status(service health) anduv run manimux attach --service runtime(runtime terminal; detach with Ctrl-B, then D).
The same four services, one terminal each, started in this order. Stop them with Ctrl-C in each terminal, runtime first.
# 1. Camera server
envs/yam/.venv/bin/python -m manimux.servers.camera.server \
--config <experiment.yaml> --local manimux/configs/local/station.yaml
# 2. Model server (XPolicyLab recipes; skip for hosted APIs such as Dream-1)
<model-env>/bin/python -m manimux.servers.policy \
--config <experiment.yaml> --local manimux/configs/local/station.yaml
# 3. RoboGUI
envs/yam/.venv/bin/python -m manimux.robogui.dashboard --robot yam --host 127.0.0.1 --port 8086
# 4. Runtime: connects robot, cameras and model, then waits for Prepare in RoboGUI
envs/yam/.venv/bin/python -m manimux run \
--config <experiment.yaml> --local manimux/configs/local/station.yamlSee managed deployment for external model/camera services, separate trial roots and Franka.
Next, choose your workflow:
| I want to… | Start here |
|---|---|
| Deploy a model on a real robot | Station setup → Deployment recipes |
| Run Dream-1 through its cloud API | Dream-1 on YAM |
| Run Pi05 through XPolicyLab | Pi05 on YAM |
| Let an agent plan with a VLA (RPent) | RPent variant of either example: Dream-1 · Pi05 |
| Compare methods and evaluate runs | Experiment workflow · Records & replay |
Contributions to robot and policy integrations, inference strategies, RoboGUI, and documentation are welcome. Start with the contribution guide. For agent-assisted development, use the development skill.
Latest update · 2026-10-18: The ManiMux website and dedicated user guide are live.
Join the ManiMux developer WeChat group to discuss integrations, experiments, and contributions. Scan the invitation below in WeChat.
This invitation is valid until November 5, 2026. If it has expired, please open a GitHub issue to request an updated invitation.
If ManiMux supports your research, please cite this repository. The paper link is forthcoming.
@misc{manimux2026,
title = {{ManiMux}: An Open-Source Harness for Real-World Manipulation Inference and Experiment Management},
year = {2026},
howpublished = {GitHub repository},
url = {https://github.com/SII-LiuLab/manimux}
}Please also cite the components, models and methods used in your work: XPolicyLab, StarVLA and PRM-as-a-Judge.
ManiMux sends commands to physical robots. It is research software provided "as is",
without warranty (see LICENSE); you are responsible for the safety of your
station. Start every new configuration with execute: false and the read-only checks in
its runbook, keep an emergency stop within reach, clear the workspace before Prepare,
Warmup and Start, and never leave an executing robot unattended. Command bounds and motion
limits in ManiMux reduce risk but do not replace the robot's own safety functions.
ManiMux is licensed under MIT. Third-party frameworks, SDKs and assets retain their own licenses; see third-party notices. Model weights and datasets are not distributed with ManiMux and keep their own terms.