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

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

• Heterogeneous RL runtime: CPU-parallel simulation streams transitions through shared memory while policy learning runs on GPU accelerators.
• Two physics backends: MuJoCoUni and MotrixSim are integrated through backend-specific adapters and task owner configs.
• Unified training CLI: uv run train and uv run eval cover PPO, MLX 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. If uv is not installed
curl -LsSf https://astral.sh/uv/install.sh | sh

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

# 2. Install dependencies
# Pick the setup command for your platform.

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

# Linux AMD / ROCm
# make sync-rocm

# Linux Intel Arc / iGPU
# make sync-xpu

# 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.

Mainland China users: motions, scenes, 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.

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 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

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

Join our Discord server to chat with the community and get help.

WeChat Group	Author WeChat
Scan to join the UniLab WeChat group.	If the group is full, add the author and include unilab交流 in your message.

⭐ Star History

🧾 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}
}