srb real_agent — Sim-to-Real Bridge

The srb real_agent family inspects simulated Gymnasium environments from the Space Robotics Bench, generates their lightweight real-world counterparts (registered under srb_real/), and exposes the same agent verbs (zero, rand, teleop, ros, train, eval, collect) for hardware execution. The generated environments do not depend on Isaac Sim and can be installed on the deployment target alongside the user’s chosen hardware backends.

Sub-Subcommands

srb real_agent <action> [options]

srb real_agent gen

srb real_agent gen --env ENV_ID [options]

The command inspects the Gymnasium spec of ENV_ID, asks the RealEnvGenerator for a real-world counterpart, and writes the resulting Python module to srb/interfaces/sim_to_real/env/<env_id>.py. From that point on, the same --env ID is recognised by every other srb real_agent subcommand.

Example

srb real_agent gen --env waypoint_navigation env.robot=leo_rover \
  --hardware ros_cmd_vel ros_tf ros_mw

If the environment passed to a non-gen subcommand has not yet been registered under srb_real/, the runner triggers the generation step automatically (in a sub-process) and asks you to re-run the original command.

--check — the freshness gate

--check never writes. It renders a fresh candidate beside the target, formats it, byte-compares it against the checked-in module, prints a unified diff, and exits non-zero on drift. Because the comparison is against a formatted file, it requires the repository’s pinned formatter (ruff) on PATH; without one it raises a typed FormatterUnavailableError naming the pinned formatter rather than reporting drift that an unformatted candidate would manufacture.

--env ALL --check runs the gate across every cached environment and exits non-zero if any has drifted — or if the environment cache is empty, since a gate that inspected nothing is not a pass. Generated modules whose task is no longer registered are absent from the cache and therefore outside the batch’s reach.

Landscaping task IDs

Terrain landscaping has two task IDs, and each generates its own module. They must never be conflated: the general task has no fixed target manifest and must never be relabelled with the crater’s hash.

srb real_agent gen --env terrain_landscaping_crater
srb real_agent gen --env terrain_landscaping

srb real_agent gen --env terrain_landscaping_crater --check
srb real_agent gen --env terrain_landscaping --check

Both run unqualified — no env.particles_height override belongs in them. Generating a bridge module does not make either task deployable: construction of the landscaping RealEnv still fails closed on missing hardware capability tags. See Terrain Landscaping Training Readiness.

Shared Options for the Other Sub-Subcommands

The non-gen real_agent subcommands accept the same baseline options:

Additional groups depend on the subcommand:

• teleop and collect accept the standard teleop arguments (--teleop_device, --pos_sensitivity, --rot_sensitivity, --invert_controls). Teleop devices include keyboard, spacemouse, ros, gamepad, and haptic.
• collect accepts the standard collection arguments (--collector, --num_episodes, --horizon, --success_only). --collector can be human, policy, random, or zero.
• train requires --algo (RL). Supported RL choices include dreamer, tdmpc2, and sbx_ppo; training also supports --continue_training / --model.
• eval requires --algo and/or --model. Evaluation choices include dreamer, tdmpc2, sbx_ppo, robomimic_bc, and robomimic_cql.
• teleop and collect also accept the optional Teleop Policy group (--algo, --model) for policy-driven rollouts.

eval and policy-driven collect accept SRB model artifact directories as --model values, not only raw checkpoint files. The manifest supplies the algorithm when --algo is omitted, and bundled framework config is reused by adapters that need the original restore context. Real collection records datasets with split=real while keeping the source as controller=human, controller=policy, controller=random, or controller=zero; artifact-backed policy collection records both the resolved checkpoint path and the source model artifact path.

Real Validation

srb real_agent validate --spec SPEC_PATH [options]

--dry-run never passes. It skips environment and policy instantiation, then finalizes the session with exit_code: 4 (preflight_fail), pass_overall: false, hardware_evidence: false, metrics.n_episodes: 0, and a red badge.json of {"label": "real-eval", "message": "non-hardware evidence", "color": "red"}. All three criteria are reported with status skipped. A dry-run artifact is a wiring smoke test, never a validation result. See Sim-to-Real Transfer for the full exit-code table.

Validation runs the generated real environment, creates telemetry in logs/real_validation/, and calls a policy reset hook at the start of every episode when the loaded policy exposes one. --checkpoint can point to a raw checkpoint or an SRB model artifact; artifact checkpoints reuse the same policy-loading path as eval and collect, including bundled framework config for Dreamer, TD-MPC2, and RSL-RL. When the validation spec omits algo or uses REQUIRED_AT_RUNTIME, an artifact checkpoint supplies the algorithm from its manifest; an explicit conflicting spec algorithm is rejected.

srb real_agent rebuild-summary

Rebuild the summary.json and report.md artifacts for an existing real validation session directory. This is useful when the validation spec has changed, or you wish to adjust metrics or post-processing without re-running the physical hardware validation.

srb real_agent rebuild-summary SESSION_DIR

• SESSION_DIR: Path to the validation session directory (which must contain a spec.yaml and logged .jsonl / .rrd telemetry).

srb real_agent replay-twin

Open a local Rerun viewer showing a time-aligned comparison of a real hardware validation rollout side-by-side with a simulated baseline rollout (“sim ghost” vs. “real solid”).

srb real_agent replay-twin --session SESSION_DIR --baseline BASELINE_RRD_PATH

• --session SESSION_DIR: Path to the validation session directory containing rollout.rrd.
• --baseline BASELINE_RRD_PATH: Path to the baseline .rrd file captured from a Phase 0 simulation run.

See Also

• Sim-to-Real Transfer Workflow — end-to-end example, ROS 2 hardware bridges, mission rehearsal
• srb agent — the simulation-side counterparts of the same verbs