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").
• Stable top-level runtime matrix currently locked by pyproject.toml / uv.lock:
  • mjlab==1.3.0
  • mujoco==3.7.0
  • mujoco-warp==3.7.0.1
• Current non-release exceptions in the resolved environment:
  • instinct_rl is still sourced from Git, currently locked to commit 3a2844890387eda6d93a4465cdef9e767aba8546.
  • Upstream mujoco-warp==3.7.0.1 currently pulls warp-lang==1.13.0.dev20260225 as a transitive dependency.
• This means InstinctMJ no longer pins nightly mjlab / mujoco artifacts, but the full dependency graph is not yet “all release tags only”.

Stable install with uv (recommended)

Use this path if you want the environment that matches the checked-in lock file.

git clone https://github.com/project-instinct/InstinctMJ.git
cd InstinctMJ
uv sync

This installs the locked release stack from pyproject.toml / uv.lock and does not require a local mjlab checkout.

Editable multi-repo workspace (optional)

Use this path only if you want to develop against local sibling checkouts of mjlab and instinct_rl.

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 mjlab
git checkout v1.3.0
cd ../InstinctMJ
uv sync
uv pip install --python .venv/bin/python --no-deps -e ../mjlab -e ../instinct_rl

# Option 2: SSH
# git clone git@github.com:mujocolab/mjlab.git
# git clone git@github.com:project-instinct/instinct_rl.git
# git clone git@github.com:project-instinct/InstinctMJ.git

If you skip the final editable reinstall, uv will keep using the version-pinned sources recorded in pyproject.toml / uv.lock.

pip alternative

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

pip install "mujoco>=3.7.0,<3.8" "mjlab==1.3.0"
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-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,
)