run-policy

Run a trained policy autonomously on the robot with async inference.

Runs a trained policy autonomously on the robot using locally attached ZED cameras and LeRobot’s async inference (lerobot.async_inference). By default a PolicyServer is launched in a child process on localhost; pass --server_host to use a remote inference-server on a more powerful machine instead. Either way the parent drives a thin RobotClient subclass that streams observations (joint positions + camera frames) to the server and consumes the returned action chunks. Type s on stdin to save the rollout and end the episode, r to discard it — the arms drop limp for hand-repositioning (a failed rollout usually leaves them somewhere they shouldn’t be); clear them, then press Enter to return to rest and re-record — or q to discard and quit. --episode_time_s is a safety cap that falls back to the same [Enter]=save / r / q prompt when no key has been pressed.

For the end-to-end workflow — including offloading inference to a GPU machine — see the Run Policy guide.

This command is configured via draccus. The robot subsystem is exposed as the nested robot_config (cameras, per-joint gains) — nest into it with dots or pass a whole-config file. See Command configuration.

Flag	Description
--policy_path PATH_OR_REPO	Local checkpoint path or HuggingFace repo ID (required)
--policy_type {act,smolvla,diffusion,tdmpc,vqbet,pi0,pi05,groot}	Policy architecture; must match the checkpoint at --policy_path (required)
--task TEXT	Natural language task description (required)
--episode_time_s INT	Safety cap on episode duration in seconds (default: 120). Episodes normally end on operator keypress
--fps INT	Control loop frame rate (default: 60). Must match the fps the policy was trained on
--repo_id <user>/<dataset>	Optional dataset repo ID to save rollouts
--root PATH	Local dataset root (default: $HF_LEROBOT_HOME)
--push_to_hub true	Push rollout dataset to HuggingFace Hub when done
--vcodec STR	Video codec recorded for saved rollout datasets (default: per-platform — h264 on Jetson/aarch64, auto elsewhere). Only used with --repo_id.
--device STR	PyTorch device for policy inference (default: cuda)
--server_host HOST	Address of a remote inference-server. Default null: a PolicyServer child process is spawned on localhost. When set, --policy_path must be reachable from the server (e.g. a HF Hub repo ID)
--server_port INT	Policy server port — for the localhost child process or the remote server (default: 8765)
--actions_per_chunk INT	Number of actions returned per inference call (default: 50); capped by the policy’s max action horizon
--chunk_size_threshold FLOAT	Trigger a fresh observation when the action queue drops to this fraction of a chunk (default: 0.9)
--aggregate_fn {temporal_ensemble,weighted_average,latest_only,average,conservative}	Action chunk aggregation strategy (default: temporal_ensemble, ACT Algorithm 2; gripper indices take the newest chunk). The other choices are upstream scalar blends
--temporal_ensemble_coeff K	Decay coefficient for temporal_ensemble (default: 0.01, ACT paper). wᵢ = exp(-K·i), i=0 oldest chunk; K>0 smoother, K=0 uniform, K<0 more reactive
--ensemble_blend_s FLOAT	Horizon fade for temporal_ensemble (default: 0.2 s). Each chunk’s weight tapers to near-zero over the last this-many seconds of its prediction horizon, so the ensemble doesn’t step when the oldest chunk’s coverage expires mid-queue. 0 disables
--align_fade_s FLOAT	Chunk-alignment offset fade (default: 1.0 s). Each incoming chunk’s offset from the currently executing trajectory — the stale-observation re-anchor disagreement, which grows with inference latency — is cancelled on arrival and faded back in over this window, removing the ~5 Hz advance/pull-back oscillation while absolute corrections still land. Shape corrections (the actual policy behavior) pass through unfaded. 0 disables
--exec_max_vel FLOAT	Per-joint velocity limit (rad/s) for the execution filter that shapes every command sent to the arms (default: teleop’s velocity ceiling). Legitimate policy motion passes through untouched while chunk-boundary snaps are spread over the ticks the arm needs anyway — a late chunk decelerates to a hold and ramps back out instead of freeze-then-lurch, keeping the arm smooth on any inference platform
--exec_max_accel FLOAT	Per-joint acceleration limit (rad/s²) for that execution filter (default: teleop’s acceleration limit). Set --exec_max_vel or --exec_max_accel to 0 to disable the filter
--reset_torque_threshold FLOAT	Contact watchdog for the between-episode return-to-rest (default: 4.0 Nm). A joint torque residual (measured minus modeled gravity) sustained above this means the move hit something — it stops and the arms drop into a limp gravity-compensation hold. Free them by hand, then continue (Enter / the panel’s Return to rest) to replan from wherever they were left. 0 disables the watchdog
--reset_gravity_comp_kd FLOAT	Velocity damping (Nm·s/rad) for that contact-fallback hold (default: 0.25); same semantics as gravity-comp --kd
--policy_torque_threshold FLOAT	Contact watchdog for the rollout phase — while the policy is driving the arms — separate from the between-episode return-to-rest guard above. Off by default (0), since a policy pushes on the scene on purpose; set a threshold (the control panel suggests 16.0) and a sustained torque residual past it aborts the episode (nothing is saved) and drops the arms into the limp gravity-comp hold — clear them by hand, then continue (Enter / the panel’s Return to rest) to return to rest and start the next attempt
--robot_config.cameras DICT	The camera slots (overhead / left_arm / right_arm) to use, with each ZED camera’s serial number, as one inline YAML/JSON value: --robot_config.cameras "{overhead: {serial: 41234567}, left_arm: {serial: 41234568}, right_arm: {serial: 41234569}}". At least one slot must be assigned (assign the cameras the policy was trained on); unassigned slots are dropped.
↳ stereo (auto-detected)	Stereo ZED X cameras are detected from their serial — on the CLI and the control panel — so you never flag it by hand. Auto-detection applies the head/wrist eye convention: a stereo overhead feeds the policy the overhead_left / overhead_right observation keys, while a stereo wrist (left_arm / right_arm) feeds a single left eye under the plain slot name, exactly like a mono camera. Setting stereo: true by hand skips auto-detection and uses the eyes field instead (default both → X_left / X_right; left / right → a single eye under the plain name X). Either way, configure the cameras to match the dataset the policy was trained on.
--robot_config.video_backend {auto,gst,sdk}	Camera capture backend. Defaults to sdk here: inference streams no headset video, so the GPU-resident gst encode branch would be wasted. Pass gst (or auto) to opt into the zed-gstreamer pipeline anyway.
--robot_config.axol_config.<side>.gripper.torque_limit FLOAT	Max torque (Nm) for a gripper in POSITION_FORCE mode (default: 0.5); <side> is left/right
--robot_config.axol_config.left_stiffness S	Compliance↔stiffness blend for the left arm in [0, 1]. Scalar or 7-element list (one per arm joint, in Joint enum order). 0 = fully compliant; 1 = pre-tuning industrial gains; 0.5 (default) is the geometric mean. Should match the value used at data collection time. Use right_stiffness for the right arm. See AxolConfig.left_stiffness.
--rerun_ip IP	IP of a Rerun viewer on your local machine for live visualization
--rerun_port INT	Rerun viewer port (default: 9876); only used when --rerun_ip is set
--log_level {DEBUG,INFO,WARNING,ERROR}	Default: INFO
--config_path PATH	Load a whole-config JSON/YAML file; CLI overrides layer on top.

axol run-policy --policy_path myorg/pick-place-policy --policy_type act --task "Pick the red cube" \
    --robot_config.cameras "{overhead: {serial: 41234567}, left_arm: {serial: 41234568}, right_arm: {serial: 41234569}}"
axol run-policy --policy_path ./checkpoints/epoch_100 --policy_type smolvla --task "Stack blocks" \
    --device cpu \
    --robot_config.cameras "{overhead: {serial: 41234567}, left_arm: {serial: 41234568}, right_arm: {serial: 41234569}}"
axol run-policy --policy_path myorg/pick-place-policy --policy_type act --task "Pick the red cube" \
    --server_host 192.168.1.99 \
    --robot_config.cameras "{overhead: {serial: 41234567}, left_arm: {serial: 41234568}, right_arm: {serial: 41234569}}"

If --repo_id is supplied, each saved episode is appended to a LeRobot-format dataset using the same resume/repair/wipe semantics as collect-data (resume a complete dataset, auto-repair a crash-inconsistent one by truncating to the intact episodes — see the collect-data crash-consistency check — refuse an incomplete one, wipe a leftover empty directory), and with the same per-episode durability: each episode’s parquet footers are flushed to disk the moment it saves, so a killed process costs at most the episode in flight. Between episodes the arms return to the rest pose via a collision-aware IK trajectory planned in a worker subprocess, mirroring the reset path used by collect-data.

Action chunk aggregation defaults to ACT’s Algorithm 2 (temporal_ensemble): every future timestep covered by the buffered chunks is the exponentially-weighted average across those chunks, with the gripper indices snapped to the newest contributing chunk so bang-bang grasp commands aren’t smeared. The control loop and observation send run on separate threads — decoupling the ~60-70 ms ZED-read + gRPC send from the 60 Hz action stream that would otherwise collapse to ~27 Hz on the upstream single-threaded design.