Skip to main content
Booster Docs

booster_gym User Guide

Project Overview​

booster_gym is Booster Robotics' reinforcement learning (RL) framework for humanoid robot locomotion development. Using Booster T1 as the main example, it covers policy training, simulation validation, model export, and deployment preparation, helping developers complete the workflow from algorithm training to robot application validation.

💡

Booster Robotics also provides open-source components for K1 and newer training/deployment workflows. For K1 or the newer RL workflow, use Booster Train, Booster Deploy, and Booster Assets.

When to Use It​

  • Train locomotion policies for the T1 humanoid robot.
  • Train and replay policies in Isaac Gym with parallel environments.
  • Run cross-simulation validation in MuJoCo to check generalization.
  • Export a trained *.pth checkpoint to a JIT-optimized *.pt model for deployment workflows.

Workflow​

  1. Prepare the environment: create a Python 3.8 Conda environment, then install PyTorch, Isaac Gym, and project dependencies.
  2. Train a policy: run train.py. Logs and checkpoints are saved under logs/<date-time>/.
  3. Replay in simulation: run play.py to evaluate the policy in Isaac Gym.
  4. Cross-check in MuJoCo: run play_mujoco.py to test cross-simulation generalization.
  5. Export the model: run export_model.py to generate a deployment-ready model.
  6. Continue deployment: follow deploy/README.md in the repository for Webots or physical-robot deployment.

Set Up the Environment​

1. Create a Conda Environment and Install PyTorch​

conda create --name <env_name> python=3.8
conda activate <env_name>
conda install numpy=1.21.6 pytorch=2.0 pytorch-cuda=11.8 -c pytorch -c nvidia

2. Install Isaac Gym​

Download Isaac Gym Preview 4 from NVIDIA Isaac Gym, then extract and install the Python package:

tar -xzvf IsaacGym_Preview_4_Package.tar.gz
cd isaacgym/python
pip install -e .

3. Configure Shared Library Paths​

If the system cannot find shared libraries such as libpython3.8, configure LD_LIBRARY_PATH in Conda activation/deactivation scripts:

cd $CONDA_PREFIX
mkdir -p ./etc/conda/activate.d
vim ./etc/conda/activate.d/env_vars.sh
# Add:
export OLD_LD_LIBRARY_PATH=${LD_LIBRARY_PATH}
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$CONDA_PREFIX/lib

mkdir -p ./etc/conda/deactivate.d
vim ./etc/conda/deactivate.d/env_vars.sh
# Add:
export LD_LIBRARY_PATH=${OLD_LD_LIBRARY_PATH}
unset OLD_LD_LIBRARY_PATH

4. Install Project Dependencies​

pip install -r requirements.txt

Train a Policy​

Run the default T1 task:

python train.py --task=T1

Training logs and saved models are written to logs/<date-time>/. Training settings are loaded from envs/<task>.yaml.

Common Arguments​

  • --checkpoint: model checkpoint to load; set it to -1 to use the latest model.
  • --num_envs: number of parallel environments.
  • --headless: run without a viewer window.
  • --sim_device: physics simulation device, such as cuda:0 or cpu.
  • --rl_device: RL algorithm device, such as cuda:0 or cpu.
  • --seed: random seed.
  • --max_iterations: maximum number of training iterations.

Add a New Task​

To add a new task, create a config file under envs/ and register the environment in envs/__init__.py.

Track Training Progress​

Use TensorBoard for training curves, or Weights & Biases for experiment tracking. To disable W&B, set use_wandb to false in the config file.

tensorboard --logdir logs
wandb login

Test a Policy​

Replay in Isaac Gym​

python play.py --task=T1 --checkpoint=-1

Evaluation videos are saved to videos/<date-time>.mp4. To disable recording, set record_video to false in the config file.

Cross-Simulation Test in MuJoCo​

python play_mujoco.py --task=T1 --checkpoint=-1

Export and Deploy​

After training and simulation validation, export the model:

python export_model.py --task=T1 --checkpoint=-1

After export, continue with deploy/README.md in the repository for Webots or physical-robot deployment. Before deploying to real hardware, validate in simulation and make sure the robot is in a safe environment.

Key Files and Directories​

  • train.py: training entry point.
  • play.py: Isaac Gym replay entry point.
  • play_mujoco.py: MuJoCo cross-simulation test entry point.
  • export_model.py: model export entry point.
  • envs/<task>.yaml: task configuration.
  • envs/__init__.py: environment registration.
  • logs/: training logs and checkpoints.
  • videos/: replay video outputs.
  • deploy/README.md: deployment guide.

Related Open-Source Projects​

  • Booster Train: RL task training for Booster robots using Isaac Lab.
  • Booster Deploy: deployment framework for running trained policies in simulation and on real robots.
  • Booster Assets: Booster robot descriptions and example motion data.

Recommendations​

  • Complete training and simulation replay before moving to physical-robot deployment.
  • When customizing tasks, start with config files before changing the training entry points.
  • Before real-robot deployment, verify the model, robot firmware, network, and safety area.
  • For K1 or newer projects, evaluate Booster Robotics' newer RL pipeline first.