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.

• 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

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

• 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

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)
bash scripts/setup_mujoco.sh

# For inference/deployment
bash scripts/setup_inference.sh

# For motion retargeting
bash scripts/setup_retargeting.sh

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

See the Training Guide for more examples and configuration options.

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.

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

G1 Locomotion	T1 Locomotion	G1 Dancing

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

• Report bugs and technical issues
• Request new features

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.

See CONTRIBUTING for more information.

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.

This project is licensed under the Apache-2.0 License.