InstinctMJ

Overview

This repository is the mjlab-native port of InstinctLab, serving as the environment side of Project-Instinct.

We aim to industrialize Reinforcement Learning for humanoid whole-body control, with task families implemented on top of mjlab and integrated into the Project-Instinct training workflow.

Key Features:

• Standalone package Work outside the core mjlab repository while keeping task development self-contained.
• Task suite Provide locomotion, shadowing, perceptive, and parkour task families for humanoid control on mjlab.
• Unified ecosystem Integrate directly with instinct_rl for train / play / export workflows.
• Structured outputs Keep experiment logs under logs/instinct_rl/<experiment_name>/<timestamp_run>/ to match the Project-Instinct workflow.

Keywords: mjlab, mujoco-warp, instinct_rl, humanoid

Warning

This codebase is under CC BY-NC 4.0 license. You may not use the material for commercial purposes, for example to advertise commercial products or redistribute the code as part of a commercial offering.

Attention

Do not directly use checkpoints trained outside InstinctMJ with InstinctMJ.

• InstinctMJ loads the robot from XML / MJCF, and the resulting joint order is not the same as the joint order used in IsaacLab.
• Policy inputs / outputs tied to joint ordering are therefore not directly checkpoint-compatible across different simulator setups.
• Please release and use weights trained in InstinctMJ for InstinctMJ tasks.

Contributing

See CONTRIBUTING.md and CONTRIBUTOR_AGREEMENT.md for contribution requirements.

Installation

• Recommended Python range: 3.10 to 3.13 (requires-python = ">=3.10,<3.14").
• Current runtime matrix locked by pyproject.toml / uv.lock:
  • mjlab==1.4.0, resolved from the editable sibling checkout at ../mjlab when using uv.
  • mujoco==3.10.0.dev925204136, resolved from the MuJoCo nightly index through the uv override.
  • mujoco-warp==3.9.0.1, sourced from google-deepmind/mujoco_warp commit e65a72e49a978a3051e7942bc5591df355ba0b5c.
  • warp-lang==1.14.0.
  • mjviser==0.0.14 and rsl-rl-lib==5.4.0 via the current mjlab dependency set.
• Other non-release sources in the resolved environment:
  • instinct_rl is sourced from Git, currently locked to commit 3a2844890387eda6d93a4465cdef9e767aba8546.

Workspace install with uv (recommended)

Use this path if you want the environment that matches the checked-in lock file. The uv source table points mjlab to ../mjlab, so keep mjlab, instinct_rl, and InstinctMJ as sibling checkouts.

mkdir -p <workspace_dir>
cd <workspace_dir>

git clone https://github.com/mujocolab/mjlab.git
git clone https://github.com/project-instinct/instinct_rl.git
git clone https://github.com/project-instinct/InstinctMJ.git

cd InstinctMJ
uv sync

Editable multi-repo workspace (optional)

Use this path if you want to explicitly reinstall the sibling checkouts into the InstinctMJ environment after uv sync.

mkdir -p <workspace_dir>
cd <workspace_dir>

# Option 1: HTTPS
git clone https://github.com/mujocolab/mjlab.git
git clone https://github.com/project-instinct/instinct_rl.git
git clone https://github.com/project-instinct/InstinctMJ.git
cd InstinctMJ
uv sync
uv pip install --python .venv/bin/python --no-deps -e ../mjlab -e ../instinct_rl

# Option 2: SSH
# git clone [email protected]:mujocolab/mjlab.git
# git clone [email protected]:project-instinct/instinct_rl.git
# git clone [email protected]:project-instinct/InstinctMJ.git

If you skip the final editable reinstall, uv still uses the editable ../mjlab source recorded in pyproject.toml / uv.lock; only instinct_rl remains pinned to the Git commit in the lock file.

pip alternative

If you prefer pip, keep the same top-level sources explicitly:

pip install "mujoco~=3.8.0" "warp-lang>=1.14.0" "mjlab==1.4.0"
pip install "mujoco-warp @ git+https://github.com/google-deepmind/mujoco_warp.git@e65a72e49a978a3051e7942bc5591df355ba0b5c"
pip install -e "git+https://github.com/project-instinct/instinct_rl.git@3a2844890387eda6d93a4465cdef9e767aba8546#egg=instinct_rl"
pip install -e .

• After installation, you can run the training workflow directly with instinct_rl-style commands:

  instinct-train Instinct-Locomotion-Flat-G1-v0
  instinct-play Instinct-Locomotion-Flat-G1-Play-v0 --load-run <run_name>

Set up IDE (Optional)

If VSCode / Pylance misses local imports in a multi-repository workspace, add these paths to .vscode/settings.json:

{
  "python.analysis.extraPaths": [
    "<workspace_dir>/InstinctMJ/src",
    "<workspace_dir>/mjlab/src",
    "<workspace_dir>/instinct_rl"
  ]
}

Task Suite

Registered task IDs:

• Instinct-Locomotion-Flat-G1-v0
• Instinct-Locomotion-Flat-G1-Play-v0
• Instinct-BeyondMimic-Plane-G1-v0
• Instinct-BeyondMimic-Plane-G1-Play-v0
• Instinct-Shadowing-WholeBody-Plane-G1-v0
• Instinct-Shadowing-WholeBody-Plane-G1-Play-v0
• Instinct-Perceptive-Shadowing-G1-v0
• Instinct-Perceptive-Shadowing-G1-Play-v0
• Instinct-Perceptive-HOI-Shadowing-G1-v0
• Instinct-Perceptive-HOI-Shadowing-G1-Play-v0
• Instinct-Perceptive-Vae-G1-v0
• Instinct-Perceptive-Vae-G1-Play-v0
• Instinct-Parkour-Target-Amp-G1-v0
• Instinct-Parkour-Target-Amp-G1-Play-v0

Use the CLI to inspect the full list at any time:

instinct-list-envs
instinct-list-envs shadowing

Quick Start

Train:

instinct-train Instinct-Locomotion-Flat-G1-v0
instinct-train Instinct-Perceptive-Shadowing-G1-v0

Play (--load-run is required):

instinct-play Instinct-Locomotion-Flat-G1-Play-v0 --load-run <run_name>
instinct-play Instinct-Perceptive-Shadowing-G1-Play-v0 --load-run <run_name>

Play perceptive shadowing with released weights:

instinct-play Instinct-Perceptive-Shadowing-G1-Play-v0 \
  --load-run <downloaded_run_dir> \
  --checkpoint-file <checkpoint_file>

Pretrained weights:

• Google Drive: Pretrained weights

Export ONNX for parkour:

instinct-play Instinct-Parkour-Target-Amp-G1-Play-v0 --load-run <run_name> --export-onnx

Play parkour with released weights:

instinct-play Instinct-Parkour-Target-Amp-G1-Play-v0 \
  --load-run <downloaded_run_dir> \
  --checkpoint-file <checkpoint_file>

Parkour pretrained weights:

• Google Drive: Parkour pretrained weights

Before training or playing parkour tasks, update the local dataset root in src/instinct_mj/tasks/parkour/config/g1/g1_parkour_target_amp_cfg.py:

_PARKOUR_DATASET_DIR = os.path.expanduser("~/your/path/to/parkour_motion_reference")

If your filtered motion list is stored elsewhere, also update filtered_motion_selection_filepath in the same file. See src/instinct_mj/tasks/parkour/README.md for the task-specific notes.

Module form is also available when console scripts are not on PATH:

python -m instinct_mj.scripts.instinct_rl.train Instinct-Locomotion-Flat-G1-v0
python -m instinct_mj.scripts.instinct_rl.play Instinct-Locomotion-Flat-G1-Play-v0 --load-run <run_name>
python -m instinct_mj.scripts.list_envs

Code Formatting

We use pre-commit for formatting and hygiene checks.

Install pre-commit:

pip install pre-commit

Run all checks:

pre-commit run --all-files

Or use the local helper command:

instinct-format

To enable hooks on every commit:

pre-commit install

Train Your Own Projects

To preserve your own experiments and logs, it is usually better to create your own task package or repository and reuse the task patterns from InstinctMJ.

If you want to add a new task directly in this repository:

• Create a new folder under src/instinct_mj/tasks/<your_project>/.
• Add __init__.py at each package level.
• Register tasks with register_instinct_task().
• Keep the environment config and instinct_rl config colocated in the task package.

Example registration pattern:

from instinct_mj.tasks.registry import register_instinct_task

from .my_env_cfg import MyEnvCfg, MyEnvCfg_PLAY
from .rl_cfgs import my_instinct_rl_cfg

register_instinct_task(
    task_id="Instinct-My-Task-v0",
    env_cfg_factory=MyEnvCfg,
    play_env_cfg_factory=MyEnvCfg_PLAY,
    instinct_rl_cfg_factory=my_instinct_rl_cfg,
)