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. LeRobot policy types use LeRobot’s async inference (lerobot.async_inference): a PolicyServer child process runs locally unless --server_host selects a remote inference-server. --policy_type custom connects to an existing endpoint through the custom policy interface, using compressed observations and accepted-plan continuation. The Rust core exclusively owns arm CAN during execution.

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.

Load only policy checkpoints and existing rollout datasets that you created or obtained from a trusted source. Upstream model deserialization and dataset parsing are not sandboxed.

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 for the syntax and Run Policy Config Parameters for every field with its default.

Flag	Description
--policy_type {act,smolvla,diffusion,tdmpc,vqbet,pi0,pi05,groot,custom}	Policy type (required). LeRobot types must match --policy_path; custom selects the custom policy interface — see Run Your Own Policy
--policy_path PATH_OR_REPO	Local checkpoint path or HuggingFace repo ID (required for LeRobot policy types). Unused for custom; model selection belongs to the endpoint
--task TEXT	Natural language task description (required). With custom, labels the dataset and is not sent to the endpoint
--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: 30). Must match the fps the policy was trained on (a checkpoint trained on 60 fps data needs --fps 60)
--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 LeRobot policy inference (default: cuda; unused with custom). The hosted aarch64/Jetson dependency set has CPU-only PyPI Torch 2.10; use cpu, remote inference, or an explicitly managed JetPack-compatible Torch + Torchvision build
--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). With --policy_type custom, the address of your policy server (default null = 127.0.0.1, nothing is spawned); a ws:// / wss:// URL is also accepted
--server_port INT	Policy server port — for the localhost child process, the remote server, or your custom policy server (default: 8765)
--actions_per_chunk INT	Maximum action horizon per inference call (default: 50). Custom endpoints may return from one row up to this limit; the remaining rows must still cover the adoption point. LeRobot policies cap the request by their supported horizon
--plan_config.request_interval INT	Custom policies: request a new plan after this many dispatched rows (default: 5)
--plan_config.max_adoption_offset_steps INT	Custom policies: largest permitted reply age in control steps from its saved request origin (default: 6); must be inside the action horizon
--plan_config.late_policy {abort,blocking_refresh}	Custom policies: abort, or hold and obtain fresh reset plans when a reply is too late or the accepted horizon expires (default: blocking_refresh)
--chunk_size_threshold FLOAT	LeRobot policies only: trigger a fresh observation when the queue drops to this fraction of a chunk (default: 0.9)
--aggregate_fn {temporal_ensemble,weighted_average,latest_only,average,conservative}	LeRobot policies only: action chunk aggregation strategy (default: temporal_ensemble, ACT Algorithm 2; gripper indices take the newest chunk). Custom-policy ensembling belongs to the endpoint
--temporal_ensemble_coeff K	LeRobot policies only: 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	LeRobot policies only: horizon fade for temporal_ensemble (default: 0.2 s). Each chunk’s weight tapers over the last this-many seconds so coverage expiry does not step the ensemble. 0 disables
--align_fade_s FLOAT	LeRobot policies only: chunk-alignment offset fade (default: 1.0 s). An incoming chunk’s offset from the executing trajectory is cancelled on arrival and faded back in over this window. 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
--max_first_action_offset_rad FLOAT	Start check for joint-space policies (default: 0.15 rad). If the episode’s first action puts any arm joint further than this from the measured pose, nothing is sent, the episode is discarded (nothing is saved), and the log and panel name the joint and the offset; continue to start the next attempt. Demonstrations start from rest, so a large first offset usually means the policy is seeing inputs it was not trained on (a different scene, camera backend, or state normalization). Grippers are exempt and Cartesian actions are not checked. The execution filter is also seeded at the measured pose each episode, so any accepted first target is ramped in rather than sent as one step. 0 disables the check
--reset_torque_threshold FLOAT	Contact watchdog for the between-episode return-to-rest (default: 6.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 (default: auto, the same as collect-data). The gst and SDK paths deliver visibly different frames, so run the policy through the path its dataset was recorded through: a mismatch shows the policy images it was never trained on. The backend in use is logged at startup (Cameras: gst pipeline / Cameras: ZED SDK).
--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 blend for the left arm in [0, 1]. Scalar or 7-element list (one per arm joint, in Joint enum order). 1 (default) = the tuned production gains; lower only adds compliance. 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.
--settings_path PATH / --no_settings	Read another shared settings file / ignore it (~/.almond/settings.json applies by default, beneath --config_path and the flags).

Every policy observation is assembled around image exposure time: all cameras must provide a fresh timestamped frame, their median exposure selects the nearest sample from the Rust core’s 240 Hz telemetry history, and only then are joint/Cartesian features built. A stale camera, missing state bracket, or excessive timestamp skew stops the rollout instead of silently feeding a train/inference-misaligned observation. The default SDK backend derives exposure time from TIME_REFERENCE.IMAGE; the optional GStreamer backend is accepted only when the exact timestamp-patched plugin binary installed by gst.build-zed is verified.

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.

Stopping parks the arms. Ending a run — Ctrl+C, q, or Stop in the control panel — plays that same return to rest and only then torques the motors off, so raised arms no longer drop under gravity on the way out. The teardown move is capped at 6 s; if it runs out of time or hits something, the arms are torqued off where they are. It is skipped when there is nothing to park or no safe way to park it: when the arms are already at rest, when a limp gravity-comp hold has left them in the operator’s hands, when the IK worker that plans the path never came up, when the CAN bus has stopped reporting positions, or when an episode worker has not proved it left the robot. A second Ctrl+C cannot interrupt it.

LeRobot action chunk aggregation defaults to ACT’s Algorithm 2 (temporal_ensemble): every future timestep covered by buffered chunks is the exponentially-weighted average across those chunks, with gripper indices snapped to the newest contributing chunk. Custom policies publish their final plan directly and bypass this aggregation. Both paths keep observation/network work outside the periodic control thread.

Custom policy interface

--policy_type custom selects compressed observations, accepted-plan continuation and confirmed dispatch references. The robot executes one unchanged plan suffix while inference runs remotely; it skips elapsed rows of an arriving plan instead of retiming row zero. No protocol-selection flag is needed. The handshake uses version: 2 to reject endpoints using the original custom-policy protocol, with no automatic fallback.

axol run-policy --policy_type custom --server_host 192.0.2.10 \
    --task "Pick the red cube" --actions_per_chunk 30 \
    --robot_config.cameras "{overhead: {serial: 41234567}}"

Write the endpoint with the almond_axol.policy SDK (Policy + serve()) and test it without the robot using policy.check. See the custom policy interface documentation for setup, timing, continuity, recovery and DAgger semantics.