7.6 KiB
Environment setup
The simulation/learning sources are vendored in this repository:
rl/mjlab and rl/rsl_rl. G1 and T1 models required by the registered examples are also bundled,
with their licenses. No external mjlab checkout, personal directory layout or asset download is
needed for these examples. See VENDOR.md for exact origins and retained modifications.
Supported reference target
The locked training target is Linux x86-64, Python 3.11–3.13, NVIDIA CUDA 13.0 PyTorch. Python 3.13 is the tested interpreter. A compatible NVIDIA driver is required; the Python lock cannot install a driver or guarantee support for every GPU. EGL is the default offscreen renderer. Other OS/architectures and CUDA builds need a separately validated lock; there is no native-CPU training fallback.
Before installing, the standard-library detector works without simulation packages:
python3 .agents/skills/setup-env/scripts/detect.py
Recommended: locked installation in a new environment
Install uv, then run from the repository root:
uv sync --locked --extra dev --python 3.13
./scripts/uh doctor
./scripts/uh verify-vendor
./scripts/check
uv.lock pins transitive dependencies and artifact hashes, including the PyTorch CUDA index and
NVIDIA Warp index. --locked refuses to silently resolve a changed project. uv sync installs
this project as editable and creates .venv; it does not reuse another project's environment.
Large CUDA wheels may take time to download. Do not interpret a partial download as an installed
runtime.
Standard pip editable installation
The same packaging layout supports pip install -e ., as in Jumper. mjlab and rsl_rl are included
in this distribution, not separately installed PyPI packages. Always use a fresh virtual environment:
python3.13 -m venv .venv
.venv/bin/python -m pip install -e '.[dev]'
This convenient command resolves the declared dependencies but does not enforce the entire transitive lock. For the locked pip alternative, install the exported requirements first:
.venv/bin/python -m pip install --require-hashes -r requirements-linux-cu130.lock \
--extra-index-url https://download.pytorch.org/whl/cu130 \
--extra-index-url https://pypi.nvidia.com/
.venv/bin/python -m pip install --no-deps -e .
The exported file contains exact versions and hashes. It targets the same Linux CUDA environment,
not all platforms. Regenerate it from uv.lock, never edit it by hand:
uv export --locked --extra dev --no-emit-project --format requirements-txt \
--output-file requirements-linux-cu130.lock
Do not install mjlab or rsl-rl-lib separately. doctor checks package origins and detects
conflicting distributions. Repair a polluted environment by creating a new one, not by uninstalling
packages from another project's shared runtime. Installed wheels include the same model resources
and licenses; the source inventory check itself requires a repository checkout.
Lightweight CI environment
.github/workflows/check.yml checks locks, licenses/layout, source inventory, wheel resource
parity, lint/format and core tests on hosted Linux/Python 3.13. Actions use immutable revisions;
the resolver is version-pinned. No GPU runtime is installed by this job, so backend-dependent
tests skip rather than claiming a simulator pass. The GPU gates below remain separate.
The ci dependency group is locked in uv.lock. Its small hashed pip export is
requirements-ci.lock; regenerate it with:
uv export --locked --only-group ci --no-emit-project --format requirements-txt \
--output-file requirements-ci.lock
CI regenerates both exports and rejects Git diffs. To reproduce its environment without replacing
your training .venv, use another directory:
UV_PROJECT_ENVIRONMENT=.venv-ci uv sync --locked --only-group ci --python 3.13
uv pip install --python .venv-ci/bin/python --no-deps --no-build-isolation -e .
PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 .venv-ci/bin/python -m pytest -q
The wheel is built with --no-isolation, using the locked build tools, rather than downloading
an unpinned build environment. CI is triggered by pushes, pull requests and manual dispatch after
this repository is hosted on GitHub; a local Git commit does not itself execute GitHub Actions.
Run the setup gates
.venv/bin/python .agents/skills/setup-env/scripts/check.py \
--config experiments/g1_smoke.json --output runs/setup-g1
.venv/bin/python .agents/skills/setup-env/scripts/check.py \
--config experiments/t1_smoke.json --output runs/setup-t1
The script runs vendor inventory, backend/CUDA/version checks, dependency consistency,
check-robot, and a bounded GPU smoke. It preserves a log for every gate and a JSON summary;
any failed gate gives a nonzero exit. It does not install packages, change gains, repair assets
or weaken checks. Use a new output directory each time.
check-robot validates declared interfaces AND measured contact response; it does not prove
locomotion or physical safety. See NEW_ROBOT.md.
Interpreter and optional asset configuration
scripts/uh chooses an explicit executable UH_PYTHON, otherwise the project .venv/bin/python,
otherwise python3 from PATH. The project must be installed in that interpreter. A bad explicit
path fails; it never falls back to another project's environment. The launcher clears inherited
PYTHONPATH/user-site leakage and does not inject source directories. An installed uh entry
point also works from outside the repository.
scripts/uh rejects legacy MJLAB_ROOT and UH_EXTRA_PYTHONPATH overrides. Unset them when migrating.
The installed Python entry point also enforces vendored import origins; those old variables cannot select a backend.
Use UH_PYTHON only to select another installed, compatible environment.
Optional external asset discovery/override:
export UNITREE_ROBOTS_ROOT=/path/to/unitree_ros/robots
./scripts/uh assets
./scripts/uh inspect-asset "$UNITREE_ROBOTS_ROOT/g1_description/g1_29dof.xml"
# Optional T1 replacement, not required for the bundled example:
export BOOSTER_ASSETS_ROOT=/path/to/booster_assets
An explicit Booster override expects robots/T1/T1_23dof.xml and referenced meshes. An invalid
override fails rather than silently using the bundled asset. G1 training uses the bundled adapted
G1 model, not Unitree ROS XML. External model changes require a new conformance report and source/
asset provenance; an inventory entry is not a registered task.
Lightweight configuration inspection
list and plan do not import the simulation stack. If intentionally inspecting source without
an install, PYTHONPATH=src python -m universal_humanoid list remains a metadata-only convenience;
it is not a supported way to select a training backend.
Troubleshooting
- Backend shadowing: inspect
doctororigins. Both backends must resolve to this checkout'srl/(editable install), or the packages installed by the same built wheel. - Core version mismatch: restore the documented lock in a new environment.
- No CUDA: check driver compatibility and GPU access; CPU discovery is not a training pass.
- Vendor mismatch: inspect the diff against
rl/VENDOR.json/rl/upstream/import.json; do not regenerate the inventory just to hide an unexplained change. - Robot gate failed: read the failed check IDs and actual/declared values. Do not widen a tolerance or remove a foot/sensor requirement merely to turn the report green.
- Historical run rejected: restore its trusted recorded source/assets/dependencies separately; vendoring intentionally changes provenance. Do not rewrite old hashes.