Holosoma

Holosoma (Greek: "whole-body") is a comprehensive humanoid robotics framework for training and deploying reinforcement learning policies on humanoid robots, as well as motion retargeting. Supports locomotion (velocity tracking) and whole-body tracking tasks across multiple simulators (IsaacGym, IsaacSim, MJWarp, MuJoCo) with algorithms like PPO and FastSAC.

Features

• Multi-simulator support: IsaacGym, IsaacSim, MuJoCo Warp (MJWarp), and MuJoCo (inference only)
• Multiple RL algorithms: PPO and FastSAC
• Robot support: Unitree G1 and Booster T1 humanoids
• Task types: Locomotion (velocity tracking) and whole-body tracking
• Sim-to-sim and sim-to-real deployment: Shared inference pipeline across simulation and real robot control
• Motion retargeting: Convert human motion capture data to robot motions while preserving interactions with objects and terrain
• Wandb integration: Video logging, automatic ONNX checkpoint uploads, and direct checkpoint loading from Wandb

Repository Structure

src/
├── holosoma/              # Core training framework (locomotion & whole-body tracking)
├── holosoma_inference/    # Inference and deployment pipeline
└── holosoma_retargeting/  # Motion retargeting from human motion data to robots

Documentation

• Training Guide - Train locomotion and whole-body tracking policies in IsaacGym/IsaacSim
• Inference & Deployment Guide - Deploy policies to real robots or evaluate in MuJoCo simulation
• Retargeting Guide - Convert human motion capture data to robot motions

Quick Start

Setup

Choose the appropriate setup script based on your use case:

# For IsaacGym training
bash scripts/setup_isaacgym.sh

# For IsaacSim training
# Requires Ubuntu 22.04 or later due to IsaacSim dependencies
bash scripts/setup_isaacsim.sh

# For MJWarp training and MuJoCo simulation (inference) — conda
bash scripts/setup_mujoco.sh

# For MJWarp training and MuJoCo simulation (inference) — uv (alternative)
bash scripts/setup_mujoco_via_uv.sh

# For inference/deployment
bash scripts/setup_inference.sh

# For motion retargeting
bash scripts/setup_retargeting.sh

Training

Train a G1 robot with FastSAC on IsaacGym:

source scripts/source_isaacgym_setup.sh
python src/holosoma/holosoma/train_agent.py \
    exp:g1-29dof-fast-sac \
    simulator:isaacgym \
    logger:wandb \
    --training.seed 1

Note: For headless servers, see the training guide for video recording configuration.

See the Training Guide for more examples and configuration options.

Quick Demo

We provide scripts to run the complete pipeline: (data downloading and processing for LAFAN), retargeting, data conversion, and whole-body tracking policy training.

# Run retargeting and whole-body tracking policy training using OMOMO data
bash demo_scripts/demo_omomo_wb_tracking.sh

# Run retargeting and whole-body tracking policy training using LAFAN data
bash demo_scripts/demo_lafan_wb_tracking.sh

Deployment & Evaluation

After training, deploy your policies:

• Real Robot: See Real Robot Locomotion or Real Robot WBT
• MuJoCo Simulation: See Sim-to-Sim Locomotion or Sim-to-Sim WBT

Or browse all deployment options in the Inference & Deployment Guide.

Demo Videos

Watch real-world deployments of Holosoma policies (click thumbnails to play)

G1 Locomotion	T1 Locomotion	G1 Dancing

Issue Reporting

We welcome feedback and issue reports to help improve holosoma. Please use issues to:

• Report bugs and technical issues
• Request new features

Support

If you need help with anything aside from issues feel free to join our discord server.

Use the discord to discuss larger plans and other more involved problems.

Security

See CONTRIBUTING for more information.

Citation

If you use Holosoma in your research, please cite it according to the "Cite this repository" panel on the right sidebar of the Github repo.

License

This project is licensed under the Apache-2.0 License.