# 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](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: ```bash python3 .agents/skills/setup-env/scripts/detect.py ``` ## Recommended: locked installation in a new environment Install `uv`, then run from the repository root: ```bash 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: ```bash 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: ```bash .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: ```bash 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: ```bash 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: ```bash 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 ```bash .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](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: ```bash 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 `doctor` origins. Both backends must resolve to this checkout's `rl/` (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.