wuji-mjlab

wuji-mjlab is an in-hand cube reorientation RL project for the Wuji Hand. It trains PPO policies in mjlab that cover the full SO(3) goal space, and deploys them on the physical hand through a sim-to-real bridge. The repo ships pretrained checkpoints, deployment scripts, and hardware guides so you can reproduce the demo end to end.

Get started with Quick Start. For detailed documentation, please refer to Wuji MJLab on Wuji Docs Center.

Repository Structure

wuji-mjlab/
├── src/
│   ├── wuji_mjlab/        // task package (tasks/reorient/, assets/, utils/, rl/)
│   └── wuji_rl_libs/      // vendored rsl-rl PPO backend
├── deploy/reorient/       // sim-to-real bridge (vision, ZMQ, hand driver)
├── scripts/               // train / play / tools entry points
├── docs/                  // architecture + sim-to-real setup
├── pixi.toml              // canonical install + task runner
└── pyproject.toml         // package metadata

Quick Start

Installation

Requirements: Linux x86_64, an NVIDIA GPU with CUDA 12.8, and pixi ≥ 0.66.

⚠️ CAUTION: this repo is pixi-only. conda + pip install -e . is not tested and not supported.

# 1. install pixi (one-time)
curl -fsSL https://pixi.sh/install.sh | bash

# 2. clone + resolve environment
git clone https://github.com/wuji-technology/wuji-mjlab
cd wuji-mjlab
pixi install

Running

Train a policy, or skip training and deploy the pretrained checkpoint from Releases:

# Train (GPU, ~20 GB VRAM)
pixi run train --task WujiHand_Reorient --agent.upload-model False

# Replay a trained checkpoint in the interactive viewer
pixi run play --task WujiHand_Reorient --checkpoint-file <path-to-ckpt.pt>

Deploy on the real hand (hardware setup required, see Sim-to-real Deployment on Wuji Docs Center):

pixi run -e deploy home                              # reset hand to home pose
pixi run -e deploy vision                            # launch cube observer (OpenCV preview)
pixi run -e deploy play-real --ckpt <path-to.onnx>   # closed-loop control + mirror viewer

For training variants, evaluation, ONNX export, hardware setup, and architecture details, see the full documentation.

Contributors

• Jielin Wu
• Shenzhe Yao
• Han Yang
• Xiangrui Jiang
• Wentao Zhang
• Li Chengmeng
• Xiaohan Liu
• Guanqi He

Citation

If you find this project useful, please consider citing:

@software{wuji2026mjlab,
  title={Wuji-MJLab: RL Training for Wuji Hand Dexterous Manipulation},
  author={{Wuji Technology}},
  year={2026},
  url={https://github.com/wuji-technology/wuji-mjlab}
}

Appendix

• Documentation: Wuji MJLab on Wuji Docs Center
• Related Projects: wujihandpy (Wuji Hand SDK), wuji-retargeting (hand pose retargeting), wujihandros2 (ROS2 driver for Wuji Hand)
• References: built on mjlab, MuJoCo Warp, MuJoCo, rsl_rl (vendored under src/wuji_rl_libs/), and pupil-apriltags. See NOTICE for third-party attribution
• Contributing: install pre-commit hooks with pixi run pre-commit install before committing

Contact

For any questions, please contact support@wuji.tech.