This repository is the environment side of Project-Instinct.

We aim at industralize Reinforcement Learning for Humanoid (legged robots) whole-body control.

Key Features:

• Isolation Work outside the core Isaac Lab repository, ensuring that your development efforts remain self-contained.
• Flexibility This template is set up to allow your code to be run as an extension in Omniverse.
• Unified Ecosystem This repository is a part of the Project-Instinct ecosystem, which includes the instinct_rl and instinct_onboard repositories.
  • The core design of this ecosystem is to treat each experiment as a standalone structured folder, which start with a timestamp as a unique identifier.
  • Adding --exportonnx flag to the play.py script will export the policy as an ONNX model. After that, you should directly copy the logdir to the robot computer and use the instinct_onboard workflow to run the policy on the real robot.

Keywords: extension, template, isaaclab

This codebase is under CC BY-NC 4.0 license, with inherited license in IsaacLab. You may not use the material for commercial purposes, e.g., to make demos to advertise your commercial products or wrap the code for your own commercial purposes.

See our Contributor Agreement for contribution guidelines. By contributing or submitting a pull request, you agree to transfer copyright ownership of your contributions to the project maintainers.

See CONTRIBUTORS.md for a list of acknowledged contributors.

• Install Isaac Lab by following the installation guide and Switch to 4.5.0 version. We recommend using the conda installation as it simplifies calling Python scripts from the terminal. At the time of release, the IsaacLab commit we are using is 9be0de5f6196374fa793dc33978434542e7a40d3 on May 5 2025.

• Install Instinct-RL by following the installation guide. TL; DR;

  git clone https://github.com/project-instinct/instinct_rl.git
  python -m pip install -e instinct_rl

• Clone this repository separately from the Isaac Lab installation (i.e. outside the IsaacLab directory):

  # Option 1: HTTPS
  git clone https://github.com/project-instinct/instinctlab.git
  
  # Option 2: SSH
  git clone git@github.com:project-instinct/instinctlab.git

• Using a python interpreter that has Isaac Lab installed, install the library

  python -m pip install -e source/instinctlab

• To run with instinct-rl, you can use the following command after installing instinct-rl:

  python scripts/instinct_rl/train.py --task=Instinct-Shadowing-WholeBody-Plane-G1-Play-v0 --headless

• Instinct-RL Documentation
• InstinctLab Documentation

To setup the IDE, please follow these instructions:

• Run VSCode Tasks, by pressing Ctrl+Shift+P, selecting Tasks: Run Task and running the setup_python_env in the drop down menu. When running this task, you will be prompted to add the absolute path to your Isaac Sim installation.

If everything executes correctly, it should create a file .python.env in the .vscode directory. The file contains the python paths to all the extensions provided by Isaac Sim and Omniverse. This helps in indexing all the python modules for intelligent suggestions while writing code.

We have a pre-commit template to automatically format your code. To install pre-commit:

pip install pre-commit

Then you can run pre-commit with:

pre-commit run --all-files

To make the pre-commit run automatically on every commit, you can use the following command in your repository:

pre-commit install

To preserve your code development and progress. PLEASE create your own repository as an individual project by referring to https://isaac-sim.github.io/IsaacLab/main/source/overview/own-project/index.html

And copy scripts/instinct_rl to your own repository.

• Please create a new folder in the source/instinctlab/instinctlab/tasks directory. The name of the folder should be your project name. Inside the folder, DO add __init__.py in each level of the subfolders. (Many people tend to forget this step and could not find the supposely registered tasks.)

• We inherit the manager based RL env from IsaacLab to add new features. DO use instinctlab.envs:InstinctRlEnv as the entry_point in the gym.register call. For example, if you want to add a new task, you can use the following code:

import gymnasium as gym
from . import agents
task_entry = "instinctlab.tasks.shadowing.perceptive.config.g1"
gym.register(
    id="Instinct-Perceptive-Shadowing-G1-Play-v0",
    entry_point="instinctlab.envs:InstinctRlEnv",
    disable_env_checker=True,
    kwargs={
        "env_cfg_entry_point": f"{__name__}.perceptive_shadowing_cfg:G1PerceptiveShadowingEnvCfg_PLAY",
        "instinct_rl_cfg_entry_point": f"{agents.__name__}.instinct_rl_ppo_cfg:G1PerceptiveShadowingPPORunnerCfg",
    },
)

In some VsCode versions, the indexing of part of the extensions is missing. In this case, add the path to your extension in .vscode/settings.json under the key "python.analysis.extraPaths".

{
    "python.analysis.extraPaths": [
        "<path-to-ext-repo>/source/instinctlab"
    ]
}