> ## Documentation Index
> Fetch the complete documentation index at: https://docs.almond.bot/llms.txt
> Use this file to discover all available pages before exploring further.

# 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`](/cli/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.

<Tip>
  For the end-to-end workflow — including offloading inference to a GPU machine — see the [Run Policy guide](/operations/run-policy).
</Tip>

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](/cli/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`](/cli/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`](/cli/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](/guides/control-panel#cameras) — 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`](/api/robot).                                                                                                                                                                                                                                                                                                                                                       |
| `--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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |

```bash theme={null}
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`](/cli/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](/cli/collect-data) — 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`.

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