Files
2026-11-03 19:46:08 +08:00

7.6 KiB
Raw Permalink Blame History

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

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 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.