UniLab

A Heterogeneous Architecture for Robot RL Beyond GPU-Dominant Paradigms

Languages: English | 简体中文

Train robot RL without a GPU simulation backend. Teaser rendered with MotrixSim.

Start with the Quick Demo below to run the primary training command. The recommended setup uses uv; Conda and pip users should still follow the uv workflow for now. Platform-specific notes and current boundaries are in the installation guide.

✨ Highlights

┌────────────────────┐                            ┌─────────────────────────┐
│   Uni Physics Sim  │   Unified Shared Memory    │   GPU Policy Training   │
│   Motrix / MuJoCo  │ ─────────────────────────▶ │     PPO / SAC / TD3     │
│   MjWarp / Drake   │    SharedReplayBuffer      │ CUDA / MPS / ROCm / XPU │
└────────────────────┘                            └─────────────────────────┘

• Heterogeneous RL runtime: CPU-parallel simulation streams transitions through shared memory while policy learning runs on GPU accelerators.
• Unified physics package: all seven physics identities (MuJoCo, Motrix, Drake, MJWarp, Genesis, IsaacGym, IsaacSim) are exposed through the independent unisim-core package; UniLab keeps task owner configs and lifecycle orchestration.
• Unified training CLI: uv run train and uv run eval cover PPO, APPO, SAC, TD3, and FlashSAC; additional HORA and HIM-PPO paths are documented as script-level workflows.
• Config-owned tasks: Hydra owner YAML files select task, reward, backend, and algorithm settings together; backend switching is expressed as task=<task>/<backend>.
• Cross-platform setup paths: The repository tracks Linux CUDA, Linux ROCm, Linux XPU, and Apple Silicon / macOS setup flows.

🚀 Quick Demo

dance G1 motion tracking	wallflip G1 wall flip	teaser MotrixSim teaser
boxtracking G1 box tracking	inhandgrasp Sharpa in-hand	locomani Go2 loco-manipulation

# 0. Install uv if needed
# Linux / macOS:
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows:
# powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
# choco install make -y

# 1. Clone the repository
git clone https://github.com/unilabsim/UniLab.git
cd UniLab

# 2. Install dependencies
# Pick the setup command for your platform.
#
# Prerequisite: the `mujoco` extra compiles a native extension during `uv sync`
# and needs Python development headers when using a system Python:
#   Ubuntu / Debian: sudo apt-get install build-essential python3-dev
#   macOS:           xcode-select --install
#   Windows:         MSVC Build Tools
# (uv-managed Pythons from `uv python install` already bundle the headers.)

# Linux CUDA, macOS, or Windows
make setup

# Linux AMD / ROCm
# make sync-rocm

# Linux Intel Arc / iGPU
# make sync-xpu

# Without shell completion setup:
# uv sync --extra mujoco --extra motrix
# If `make` is not installed or unavailable:
# uv sync --extra mujoco --extra motrix && uv run --no-sync unilab-complete install

# 3. Pre-trained checkpoint playback (downloads from Hugging Face on first run)
uv run demo dance

Available demo names: teaser, dance, wallflip, boxtracking, locomani, inhandgrasp. See the Unified CLI page for the full list and flags.

Physics adapters are installed from the production PyPI release unisim-core>=0.1.14; its public Python import namespace is unisim.

Mainland China users: motions, scenes, robot meshes, and demo checkpoints are pulled from Hugging Face on first run. If huggingface.co is unreachable, point the client at the community mirror before running demo commands:

export HF_ENDPOINT=https://hf-mirror.com

For training and evaluation:

uv run train --algo appo --task go2_joystick_flat --sim motrix

uv run eval --algo appo --task go2_joystick_flat --sim motrix --load-run -1

# Headless Motrix video export for Linux/server runs
uv run eval --algo appo --task go2_joystick_flat --sim motrix --load-run -1 --render-mode record

This routes through the go2_joystick_flat/motrix task owner config and keeps backend selection explicit. Each backend owner carries an optional play_profile block that layers render-only overrides at eval time (training.play_only=true) without affecting training.

On macOS / MacBook, the UniLab CLI routes Motrix interactive playback through mxpython when needed. Motrix defaults to interactive playback; use --render-mode record for headless video export or --render-mode none to skip playback. Detailed script-level commands are in the Training Guide.

🏃 Example Runs

uv run train --algo sac --task g1_walk_flat --sim mujoco
uv run train --algo flashsac --task g1_walk_flat --sim mujoco

uv run train --algo sac --task g1_motion_tracking --sim motrix

uv run train --algo appo --task sharpa_inhand --sim mujoco --profile hora

Grasp caches auto-download from Hugging Face (unilabsim/unilab-caches) on first run into src/unilab/assets/caches/; no manual step is needed. To regenerate locally for custom scales (slow):

bash scripts/sharpa_collect_grasps.sh 0.8 0.9 1.0 1.1 1.2 1.3 1.4 1.5

uv run train --algo ppo --task go2_arm_manip_loco --sim motrix
uv run eval --algo ppo --task go2_arm_manip_loco --sim motrix --load-run -1

uv run train --algo ppo --task go2_joystick_flat --sim mujoco 'training.devices=[0,1]'
uv run train --algo flashsac --task g1_walk_flat --sim mujoco training.devices="[0,1,2,3]"
uv run train --algo sac --task g1_motion_tracking --sim mujoco training.devices="[0,1,2,3,4,5,6,7]"

Use uv run train for training, uv run eval for checkpoint playback, and uv run demo for the local demo preset. These commands keep algorithm, task, and backend selection explicit.

More training commands, script-level entrypoints, algorithm matrix, resume flow, and W&B details are in the Training Guide.

📚 Documentation

Use the published UniLab documentation; start at the English documentation index. High-signal entrypoints:

• Getting Started: installation, Docker runtime, dependency setup, and first-run commands
• Training Guide: training, playback, resume flow, Hydra overrides, and W&B
• Simulation Backends: generated MuJoCo / Motrix support matrix
• Development Standard: contracts, layering, and validation boundaries
• ADR Index: accepted architecture decisions

💬 Community

Add the assistant on WeChat to join the group. Please include UniLab community in your request.

🧾 Citation

UniLab

@article{jia2026unilab,
  title         = {UniLab: A Heterogeneous Architecture for Robot RL Beyond GPU-Dominant Paradigms},
  author        = {Yufei Jia and Zhanxiang Cao and Mingrui Yu and Heng Zhang and Shenyu Chen and Dixuan Jiang and Meng Li and Xiaofan Li and Yiyang Liu and Junzhe Wu and Zheng Li and XiLin Fang and Tingyu Cui and Shengcheng Fu and Haoyang Li and Anqi Wang and Zifan Wang and Dongjie Zhu and Chenyu Cao and Zhenbiao Huang and Ziang Zheng and Jie Lu and Xin Ma and Zhengyang Wei and Xiang Zhao and Tianyue Zhan and Ye He and Yuxiang Chen and Yizhou Jiang and Yue Li and Haizhou Ge and Yuhang Dong and Fan Jia and Ziheng Zhang and Meng Zhang and Xiwa Deng and Zhixing Chen and Hanyang Shao and Chenxin Dong and Yixuan Li and Yizhi Chen and Bokui Chen and Kaifeng Zhang and Hanqing Cui and Yusen Qin and Ruqi Huang and Lei Han and Tiancai Wang and Xiang Li and Yue Gao and Guyue Zhou},
  journal       = {arXiv preprint arXiv:2605.30313},
  year          = {2026},
  url           = {https://arxiv.org/abs/2605.30313}
}

Physics Backends

@article{jia2026mujocouni,
  title  = {MuJoCoUni: Persistent Batched Runtime Primitives for MuJoCo},
  author = {Jia, Yufei and Wu, Junzhe},
  journal = {arXiv preprint arXiv:2605.24922},
  year   = {2026}
}

@software{motrixsim2026,
  title  = {MotrixSim: A Physics Simulation Engine for Robotics and Embodied AI},
  author = {{Motphys Team}},
  year   = {2026},
  url    = {https://motrixsim.readthedocs.io/},
  note   = {Python binary package}
}