11 KiB
Command reference
Install this checkout in a Python 3.10–3.13 environment with
python -m pip install -e ".[dev]". See Agent setup for
platform-specific setup. The editable install connects both package roots.
Onboard
python scripts/onboard.py --help
python scripts/onboard.py inspect <model-or-directory> --profile <profile.json>
python scripts/onboard.py build-mjcf <model-mesh-or-directory> --output <robot.xml>
python scripts/onboard.py extract-tier1 env.yaml agent.yaml --model <robot.xml> --output <metadata-dir>
python scripts/onboard.py adapt-tier1 <actor.onnx> --metadata <metadata.json> --model <robot.xml> --output <policy-dir>
python scripts/onboard.py adapt-tier1 <actor.onnx> --config env.yaml --config agent.yaml --overrides reviewed.json --model <robot.xml> --output <policy-dir>
python scripts/onboard.py setup-tier2 --model <robot.xml> --config <controller.json> --output <control-dir>
python scripts/onboard.py calibrate --model <robot.xml> --config <stance.json> --report <calibration.json>
python scripts/onboard.py verify --model <robot.xml> --config <probe.json> --report <verification.json>
python scripts/onboard.py scaffold-tier3 --config <robot.json> --calibration <calibration.json>
Each subcommand has its own --help. inspect accepts optional --policy,
--metadata, and --mesh-root. In an asset directory, build-mjcf searches
recursively for one URDF or MJCF, or one STL, OBJ, or MSH when there is no
model. Pass a file explicitly when the directory has several candidates at
the selected level. The requested output path is excluded from the search.
--floating-base adds a free URDF root, --mesh-root extends URDF asset search,
--mesh-scale scales standalone meshes, and --visual-fallback opts into
approximate URDF collision geometry.
Choose fresh report and output paths unless the command explicitly allows
replacement. Calibration and verification emit JSON and return a failing
status when the requested checks fail.
extract-tier1 reads selected YAML, JSON or static Python training configs.
Use --overrides to supply reviewed JSON or YAML values and --report for a
separate extraction report. The output directory contains metadata.json
and manifest.json, including on an incomplete extraction with exit status
- Review the provenance and unresolved fields. Adapt from a manifest with
ready: true, or supply the same reviewed inputs through repeated--configarguments in place of--metadata. See the Tier 1 walkthrough.
Python API
from mjrl.onboarding import build_mjcf, calibrate_model, inspect_asset, scaffold_task, verify_model
intake = inspect_asset(source, profile=profile)
build = build_mjcf(source, model_path)
calibration = calibrate_model(model_path, stance_config)
verification = verify_model(model_path, probe_config, base_dir=config_directory)
registration = scaffold_task(robot_config, base_dir=config_directory, calibration=calibration)
These functions return report dictionaries. The profiles and configs are
Python mappings. base_dir resolves relative verification configuration paths
and defaults to the model's directory for verification. Scaffolding requires
base_dir for relative model and controls paths. Supply tasks_root to write
the specification into a different task directory.
Use mjrl.onboarding.extract_policy_metadata for programmatic Tier 1 metadata
extraction and readiness diagnostics. Pass a sequence of config paths and, if
available, the compiled MuJoCo model and a mapping of reviewed overrides.
from mjrl.onboarding import extract_policy_metadata
extraction = extract_policy_metadata(
[env_config_path, agent_config_path], overrides=reviewed, model=compiled_model
)
The result contains the canonical draft under metadata and the readiness
and provenance fields written by the CLI.
Robot specification
The calibrated scaffold config names robot_id, family, model_path, and
action_scales keyed by calibrated position-joint name. It can also name
controls_path, velocity_joints, penalized_contact_geoms, and
termination_contact_geoms. Model and controls paths resolve relative to the
input JSON. The calibration must match the model XML and compiled dependencies.
Without --calibration, give a full RobotSpec from verified model facts.
This example shows the file shape:
{
"robot_id": "sample_biped",
"family": "biped",
"model_path": "assets/sample_biped/robot.xml",
"base_body": "base",
"base_height": 0.32,
"foot_geoms": ["left_foot", "right_foot"],
"penalized_contact_geoms": ["left_shin", "right_shin"],
"termination_contact_geoms": ["torso"],
"position_joints": [
{"name": "left_hip", "kp": 20, "kd": 1, "effort_limit": 8, "action_scale": 0.25, "home": 0.1},
{"name": "right_hip", "kp": 20, "kd": 1, "effort_limit": 8, "action_scale": 0.25, "home": 0.1}
]
}
Use calibrated values for the robot. base_height is its standing root
height. Each joint's home supplies its default joint position. Optional
armature is additional inertia at that joint. Supply either foot_geoms
or foot_bodies. Each named foot body needs named collision geoms directly
on it. The minimum support counts are two for biped and wheeled biped, four
for quadruped, and five for multipod. A wheeled biped also needs at least two
named unlimited wheel hinges in velocity_joints, with kp: 0, positive
kd, an effort limit, and a velocity action scale.
Scaffolding writes only tasks/<robot_id>/robot_spec.py in the task tree.
The robot ID is the task ID. Family values are biped, quadruped,
wheeled_biped, and multipod. The controls file for a locomotion policy
uses the body-frame twist term feeding velocity_commands, with
lin_vel_x, lin_vel_y, and ang_vel_z in that order. For operator input,
generate the bindings before
scaffolding and set controls_path in the input JSON. Choose
--profile differential for a wheeled biped to use A/D for yaw.
Train and replay
python scripts/train.py --list
python scripts/train.py --task <robot_id> --dry-run
python scripts/train.py --task <robot_id> --backend native --device cpu --num_envs 64 --headless
python scripts/train.py --task <robot_id> --resume --max-iterations 100
python scripts/play.py --task <robot_id> --checkpoint <model_N.pt> --headless --steps 300 --speed 0 --measure
Use --backend warp --device cuda for the GPU path. Explicit requests fail
when their device is unavailable. Native starts at 64 parallel environments
and Warp at 4096 when no count is set. Start with fewer for an execution smoke
or an asset with high memory use.
Warp constraint and contact capacities can be set with positive integers
using --warp-max-constraints N and --warp-max-contacts N. Constraints
are capped per world. Contacts share a pool sized from the per-world setting
and the environment count. A Warp buffer overflow stops the run before it
uses the affected observations. For example, the G1 flat setup uses
--warp-max-constraints 300.
A Warp run saves selected and effective capacities in warp-allocation.json
beside its checkpoints. Warp resume, replay, and export read this file when
present. Explicit flags take precedence. Otherwise, the larger of the saved
capacity and the task or scene requirement is used. Without a run record or
a configured capacity, Warp chooses the size.
Training logs to logs/<model>/<robot_id>/<timestamp>/. The default
--logger is tensorboard. Use --no-tensorboard to skip starting its
server. --max-iterations caps this invocation. --resume selects the
latest checkpoint and --checkpoint selects a particular one. Both restore
the optimizer, iteration, and curriculum state. On resume,
--max-iterations is the number of additional iterations.
Replay retains actor observation noise by default. Use --no-obs-noise for
a clean comparison. --checkpoint-command-ranges restores the checkpoint's
command curriculum ranges. To evaluate a fixed body command, use
--command VX VY YAW --evaluation-out <metrics.json> with a trained checkpoint
and positive --steps. --measure records joint signals. Use --physics-hz
only when deliberately evaluating a different integration rate. The default
task simulation rate comes from its template. Built-in scenes work in
training and replay. Imported .map scenes are replay-only.
Rough terrain uses explicit nominal dimensions, not a hidden robot model:
--terrain-robot-height 0.25, --terrain-stance 0.40, and
--terrain-foot-lift 0.04 (metres). With --scene rough, set these to the
calibrated asset's dimensions when comparing terrain difficulty. Height and
stance scale vertical and horizontal obstacles independently; foot lift sets
continuous roughness. The Python scene arguments are robot_height, stance,
and foot_lift. All must be finite and positive.
Export and package
python scripts/export.py --task <robot_id> --checkpoint <model_N.pt> --out <policy-dir>
python scripts/deploy.py --robot <robot_id> --model <robot.xml> --bundle <output-parent>
python scripts/play.py --app <output-parent>/<robot_id>.app --headless --steps 100
Export writes the actor, its layout, a checkpoint copy, and a README. It checks
observation and action dimensions, home pose, and ONNX parity. Add
--native-layout to export a replay-ready native model and controller next to
the policy. Hybrid position and velocity actions automatically use the native
layout. Legacy Rust consumers accept their position-action layout. See
Controller setup.
A model-only build creates a viewer app. A controlled native build includes
--control <controller.json>, --verification <verification.json>, and
--controls <controls.yaml> when the report verified operator bindings.
For a compatible ONNX mode, also pass --policy <policy-dir>. For multiple
modes, use --platform-manifest <manifest.json>. See the
bundle format for mode fields and runtime requirements.
The legacy target flags build the separate Rust bundle format.
Defaults
Precedence is command line, shell environment, .env.local, .env, then the
argument default. Copy .env.example to .env to set local defaults. A blank
task means a task is required on task entry points. A blank model selects the
robot's registered model. The effective defaults are:
MJRL_TASK=
MJRL_MODEL=
MJRL_SCENE=
MJRL_TERRAIN_ROW=
MJRL_TERRAIN_COL=
MJRL_BACKEND=auto
MJRL_DEVICE=auto
MJRL_NUM_ENVS=
MJRL_PLAY_NUM_ENVS=1
MJRL_CPU_THREADS=0
MJRL_STRIP_VISUAL=auto
MJRL_TENSORBOARD=on
MJRL_TB_PORT=6006
The terrain row and column select one rough-terrain tile when set. Native
MJRL_CPU_THREADS=0 selects threads automatically. Native visual stripping
can reduce per-environment memory and affects camera sensor appearance.
TensorBoard binds to localhost and skips occupied ports.