Skip to content

Strands Robots

API Reference

strands-labs/robots

API reference¶

`strands_robots`¶

import strands_robots

Symbol	What	More
`Robot(name, mode='sim', ...)`	Factory → `Simulation` or `HardwareRobot`	Robot factory
`Teleoperator(name, **kwargs)`	Factory → LeRobot teleoperator (leader arm, gamepad, keyboard, …)	Teleoperation
`list_robots(mode='all')`	Catalog query, filtered on backend support	Robot catalog
`Policy`	Policy ABC	Policies
`MockPolicy`	Sinusoidal mock	Policies
`create_policy(provider, **kw)`	Policy factory	Policies
`register_policy(name, loader, aliases=None)`	Runtime registration	Custom policies
`list_providers()`	Known policy providers	Policies
`list_policy_types()` (lazy)	Resolvable `lerobot_local` `policy_type` strings	LeRobot local
`Simulation` (lazy)	MuJoCo-backed AgentTool	Simulation overview
`Gr00tPolicy` (lazy)	NVIDIA GR00T client	GR00T

`strands_robots.registry`¶

from strands_robots.registry import (
    list_robots, resolve_name, get_robot, has_sim, has_hardware, get_hardware_type,
    list_robots_by_category, list_aliases, normalize_robot_name, format_robot_table,
    register_robot, unregister_robot, list_user_robots,
    user_registry_source, parse_user_robots,
    list_policy_providers, resolve_policy, import_policy_class, build_policy_kwargs,
)

Symbol	What
`list_robots(mode)`	Robots filtered on backend support, not on category: `"all"`, `"sim"` (has a simulation asset), `"real"` (has a hardware backend) or `"both"`. An unrecognized mode raises rather than returning the unfiltered list. To group by category use `list_robots_by_category()`.
`resolve_name(name)`	Alias → canonical name. The query is folded by `normalize_robot_name` first, so any spelling of a name or alias reaches the same robot.
`get_robot(name)`	Full registry entry dict.
`has_sim(name)` / `has_hardware(name)`	Sim / real support flags.
`get_hardware_type(name)`	LeRobot type string for `mode="real"`.
`list_robots_by_category()`	Group name to the `list_robots()` records in it. Every robot is in exactly one group, so the group sizes sum to `len(list_robots())`. `category` is optional, so a robot that declares none is grouped under `"other"` rather than under a nameless group, and a declared name is stripped of surrounding whitespace so a padded spelling joins its own group. `list_robots()` still reports each robot's own `category` exactly as its entry declares it.
`list_aliases()`	All 121 aliases, keyed by `normalize_robot_name` (so every key is a spelling a folded query can produce), including every GR00T `data_config` spelling (so `data_config` names resolve as robot names).
`normalize_robot_name(name)`	The fold every registry lookup applies: lowercase, trimmed, dashes as underscores. Canonical names, aliases and the uniqueness constraints over both are all keyed by it, so this is the rule that predicts which robot a name reaches.
`format_robot_table()`	Pretty-printed robot table.
`register_robot(name, *, model_xml, ...)`	Add user-defined robot at runtime. Every field after `name` is keyword-only. `model_xml`/`scene_xml` must name a file inside `asset_dir`. Values must be JSON types (a `Path` or a numpy scalar in `hardware` is refused, naming the offending type).
`unregister_robot(name)`	Remove a runtime-registered robot.
Both write the whole overlay	`user_robots.json` is read, changed and stored back in one atomic commit, so a refused or failed write leaves every previously registered robot exactly as it was rather than truncating the document they all share.
`list_user_robots()`	Names from `register_robot`.
`user_registry_source()`	Raw bytes of `user_robots.json`, or `None` when absent. What the loader keys its hot-reload cache on, so an edit by another writer is seen even when it lands inside one filesystem timestamp tick.
`parse_user_robots(source)`	Robot definitions held in those bytes; empty when absent or malformed. Parsing the bytes the cache was keyed on is what keeps the cached merge and the key describing the same overlay.
`list_policy_providers()`	Providers from `policies.json`, canonical names only.
`list_policy_aliases()`	Alias/shorthand -> canonical provider, from `policies.json`. Peer of `list_aliases()` for robots.
`resolve_policy(uri)`	URI → provider name.
`import_policy_class(provider)`	Lazy import of provider class.
`build_policy_kwargs(provider, **kw)`	Normalise + validate kwargs. An explicit value beats the provider's registry default; the provider's own key (`host=`) beats the generic parameter (`policy_host=`). Every generic parameter defaults to `None`, meaning "unset", so an omitted one leaves the provider's own default -- registry, else constructor -- in place.

`strands_robots.simulation`¶

from strands_robots.simulation import (
    Simulation, SimWorld, SimRobot, SimObject, SimCamera,
    create_simulation, list_backends, register_backend,
)
from strands_robots.simulation.base import SimEngine

Symbol	What
`Simulation`	MuJoCo backend - 60+ agent actions.
`SimWorld`, `SimRobot`, `SimObject`, `SimCamera`	Shared dataclasses.
`create_simulation(backend='mujoco')`	Factory for non-`Robot()` construction.
`list_backends()` / `register_backend(name, loader)`	Backend registry. `loader` is a zero-arg callable returning the class (`lambda: MyEngine`), so the import stays deferred.
`SimEngine`	ABC custom backends implement.

Selected actions:

Action	What
`run_policy(robot_name, ...)`	Blocking policy rollout.
`start_policy(robot_name, ...)`	Rollout in a background thread on MuJoCo; a blocking passthrough to `run_policy` on the other backends. `describe()['methods']['start_policy']` states which one the engine you hold implements.
`stop_policy(robot_name)`	Cooperatively stop a rollout; the `json` block reports `was_running`. Refused (naming the class) by a backend with no durable per-robot claim.
`run_multi_policy(policies, ...)`	Synchronized multi-robot rollout, one merged frame per step.
`eval_policy(robot_name, n_episodes, ...)`	Multi-episode evaluation.
`evaluate_benchmark(benchmark_name, ...)`	Run registered benchmark.
`list_benchmarks()` / `register_benchmark_from_file(name, spec_path)`	Benchmark registry.
`replay_episode(repo_id, robot_name, ...)`	Replay a recorded episode.

`strands_robots.hardware_robot`¶

from strands_robots.hardware_robot import Robot, TaskStatus, RobotTaskState

Symbol	What
`Robot`	Real-hardware AgentTool.
`TaskStatus`	Enum: `IDLE` / `CONNECTING` / `RUNNING` / `COMPLETED` / `STOPPED` / `ERROR`.
`RobotTaskState`	Dataclass: status, step count, error.

Method	What
`start_task(instruction, policy_port, ...)`	Async task start.
`stop_task()`	Halt the current task, including one still in `CONNECTING`.
`get_task_status()`	Return `RobotTaskState`.
`cleanup()`	Stop tasks, disconnect the motors bus and cameras, stop mesh.

`strands_robots.policies`¶

from strands_robots.policies import (
    Policy, MockPolicy, create_policy, register_policy, list_providers, UntrustedRemoteCodeError,
)
from strands_robots.policies.groot import Gr00tPolicy
from strands_robots.policies.lerobot_local import LerobotLocalPolicy
from strands_robots.policies.cosmos3 import Cosmos3Policy

Symbol	What
`Policy`	ABC: `get_actions`, `set_robot_state_keys`, `requires_images`, `provider_name`.
`MockPolicy`	Sinusoidal mock. `requires_images=False`.
`create_policy(provider, **kw)`	Resolve + construct. Accepts `zmq://`, `cosmos3://`, HF `org/model`.
`register_policy(name, loader, aliases)`	Runtime registration.
`list_providers()`	Sorted canonical names of every JSON-registered provider, plus any runtime `register_policy` names and their aliases. Canonical names only for the JSON registry: pair it with `list_aliases()` for the rest.
`list_aliases()`	Every provider alias and the canonical name it resolves to, across both registries. Together with `list_providers()` they are every registered spelling - not every spelling `create_policy` resolves. A module under `strands_robots.policies` exporting a `Policy` subclass also resolves under its own module name: `composite` (builds through the factory) and `persistent` (resolves; constructed directly).
`list_policy_types()`	`policy_type` strings the installed lerobot resolves; `[]` without lerobot. Discovery peer of `list_providers`.
`UntrustedRemoteCodeError`	Raised when `STRANDS_TRUST_REMOTE_CODE` is required but unset.
`Gr00tPolicy`	GR00T N1.5/N1.6/N1.7 via ZMQ (service) or in-process.
`LerobotLocalPolicy`	HF LeRobot inference (ACT, Pi0, Pi0.5, SmolVLA, …). Needs `STRANDS_TRUST_REMOTE_CODE=1`.
`Cosmos3Policy`	NVIDIA Cosmos 3 VLA over WebSocket.

`strands_robots.tools`¶

from strands_robots import (
    download_assets, gr00t_inference, lerobot_camera, lerobot_teleoperate,
    lerobot_train, pose_tool, robot_mesh, run_policy,
    serial_tool, train_policy, use_lerobot, use_ros, use_rtps,
)
# Each tool lives in a submodule of the same name (strands_robots.tools.use_ros),
# so read it off the package root as above or off its own submodule
# (from strands_robots.tools.use_ros import use_ros); never off strands_robots.tools,
# where the name is the submodule once anything has imported it.
# All return {"status": "...", "content": [{"text": "..."}]}

See Hardware tools.

`strands_robots.dataset_recorder`¶

from strands_robots.dataset_recorder import DatasetRecorder, has_lerobot_dataset

Symbol	What
`DatasetRecorder.create(repo_id, fps, ...)`	New dataset.
`DatasetRecorder.resume(repo_id, root, task, ...)`	Append to existing (`lerobot>=0.5.2`).
`recorder.add_frame(observation, action, task=...)`	Append one frame.
`recorder.save_episode()`	Finalise episode.
`recorder.clear_episode_buffer()`	Discard buffer.
`recorder.finalize()`	Flush and close.
`recorder.push_to_hub(tags=None, private=False)`	Upload to HuggingFace. `private` must be a boolean — it selects the repo's visibility.
`has_lerobot_dataset()`	Cached import check (True if `LeRobotDataset` imports).
`lerobot_dataset_import_error()`	`None` if it imports, else why not - names the missing package and the install that supplies it. Use this when reporting to a human.

`strands_robots.mesh`¶

from strands_robots.mesh import init_mesh, Mesh, InputPublisher, InputReceiver

Symbol	What
`init_mesh(robot, peer_id=None, ...)`	Attach mesh to a robot instance.
`Mesh`	`peer_id`, `peers`, `alive`, `send`, `broadcast`, `tell`, `emergency_stop`.
`InputPublisher`	Stream teleoperator actions over mesh.
`InputReceiver`	Receive + apply remote teleoperator actions.

See Multi-robot mesh.

Environment variables¶

Variable	Purpose	Default
`STRANDS_ASSETS_DIR`	Robot model asset cache	`~/.strands_robots/assets/`
`STRANDS_ROBOT_MODE`	Force `Robot()` mode	(kwarg honoured)
`STRANDS_TRUST_REMOTE_CODE`	Allow HF `trust_remote_code=True`	unset → blocked
`STRANDS_MESH`	`true` opts a bare `Robot()` into the mesh; `false` is a hard kill switch	unset (mesh off)
`STRANDS_MESH_AUDIT_DIR`	Safety event audit log	`~/.strands_robots/`
`MUJOCO_GL`	GL backend for MuJoCo	auto
`GROOT_API_TOKEN`	GR00T cloud inference token	(unset)
`STRANDS_GROOT_WIRE_LOG`	Directory to dump pre/post-inference payloads to, e.g. `/tmp/groot-wire`; covers the in-process path as well as the service path, capped by `STRANDS_GROOT_WIRE_LOG_MAX_CALLS`	(unset)

See also¶

Architecture - module map + ABC contracts.
Robot factory - full factory signature.
Quickstart - concept walkthroughs.