Robotics Quickstart

Get the AutonomyOps ROS2 governance demo running in 10 minutes.

This quickstart targets the Community Edition distribution of the autonomy CLI on a single-node setup. (autonomy-ce-<os>-<arch> is the release artifact prefix; once installed it is on PATH simply as autonomy.) No orchestrator, fleet, or paid-tier deployment is required to complete every step on this page. Advanced flows that depend on a running autonomy-orchestrator are called out explicitly under “Advanced”.

What you will do

1. Build the demo ROS2 image

2. Run the governed arm-demo stack

3. Watch PASS markers to confirm governance checkpoints

4. Query the /arm/get_status service through the container

5. Inspect the demo bundle that carries the safety policy

Prerequisites

Tool	Version	Purpose
Docker	24+	Container execution path
autonomy CLI	latest	Governance and bundle commands
ROS2 Humble	optional	Native fallback path only

Install the autonomy CLI:

bash scripts/install-ce.sh

Verify:

autonomy version

Step 1 — Build the demo image

From the repository root:

docker build -t ghcr.io/autonomyops/adk-ros2-runtime:local demo/ros2-runtime/

The Dockerfile uses ghcr.io/autonomyops/adk-runtime:latest as the base and builds the demo_robot workspace via colcon build at image-build time. The entrypoint adk_ros2_entrypoint.sh sources both the Humble base overlay and the workspace overlay.

Expected: Successfully tagged ghcr.io/autonomyops/adk-ros2-runtime:local

Step 2 — Run the governed arm demo

Both tiers require --image whenever Docker is available on the host. The container path is selected automatically when the Docker daemon is reachable; without --image the container path returns ErrImageRequired. Pass --image to both commands below:

CE-tier (dispatch via autonomy run)

autonomy run \
    --image ghcr.io/autonomyops/adk-ros2-runtime:local \
    ros2.launch launch demo_robot arm_demo.launch.py

On a host without Docker and with ros2 in PATH, the native fallback path is taken and --image may be omitted. The governance posture is reduced in that case (see ROS2 Governance).

Step 3 — Watch PASS markers

The governance stack emits PASS markers to stdout at each checkpoint. You should see all five within the first 5–10 seconds:

PASS ros2-telemetry-active context=container
PASS ros2-runtime-container-ready context=container
PASS ros2-stack-start context=container
PASS ros2-policy-enforced context=container
PASS ros2-wal-recording context=container

If any marker is missing, check the Markers and Observability guide for diagnostic steps.

Shortly after, the demo nodes start logging:

[arm_demo] launching in mode=sim — governed by AutonomyOps ROS2 policy
[distance_sensor]: distance_sensor ready — rate=10.0 Hz  range=[0.05, 2.0] m
[arm_controller]: arm_controller ready — max_velocity=1.0 m/s  safety_stop_distance=0.3 m
...
[arm_controller]: PROXIMITY STOP — obstacle at 0.192 m (threshold=0.3 m)
...
[arm_controller]: proximity cleared — obstacle at 0.352 m, resuming

The proximity stop fires once per 8-second obstacle cycle generated by the distance_sensor sine-wave model. No hardware is required.

Step 4 — Query the arm status service

While the stack is running, open a second terminal and run:

container=$(docker ps -q -f ancestor=ghcr.io/autonomyops/adk-ros2-runtime:local)

docker exec "$container" bash -c "
  source /opt/ros/humble/setup.bash
  source /opt/ros2_ws/install/setup.bash
  ros2 service call /arm/get_status std_srvs/srv/Trigger
"

The response depends on where the 8-second proximity-stop cycle is when you call. success is True when the arm is idle or moving and False when in the e_stopped state (proximity stop active). Both are valid outputs during a normal demo run:

# Idle or moving — no active stop
response: std_srvs.srv.Trigger_Response(
  success=True,
  message='state=idle  joint[0]=0.000 rad  e_stop=False'
)

# During a proximity stop
response: std_srvs.srv.Trigger_Response(
  success=False,
  message='state=e_stopped  joint[0]=0.000 rad  e_stop=True'
)

Wait a few seconds and call again if the first response shows success=False; the proximity stop clears automatically when the simulated obstacle recedes.

The /arm/get_status service is the only service permitted by the demo policy; any other service call is denied by the fail-closed default.

Step 5 — Inspect the demo bundle

The demo bundle (demo/bundles/ros2.tar) carries the safety policy that governs this run. Inspect it without a registry:

autonomy bundle inspect demo/bundles/ros2.tar --local

Expected output (key fields):

name:       ros2-demo
version:    0.1.0
channel:    dev
entrypoint: ros2 launch demo_robot arm_demo.launch.py
policy_ref: policies/ros2_safety.rego

To view the policy itself:

autonomy bundle inspect demo/bundles/ros2.tar --local --show-policy

Step 6 — Stop the demo and inspect the local WAL

Press Ctrl-C in the terminal running autonomy run ros2.launch (or autonomy ros2 run).

The governance stack flushes the local WAL before exit. To inspect what was recorded — every PASS marker, every policy decision — read the local WAL directly. No orchestrator required:

autonomy wal status
autonomy wal inspect --limit 20
autonomy wal inspect --kind PASS --limit 20

autonomy wal inspect reads the local telemetry WAL on this machine. The output includes the five ros2-* PASS markers plus any policy-evaluation events that occurred during the run.

Troubleshooting

No PASS markers appear

• Confirm Docker is running: docker info

• Confirm the image was built: docker image inspect ghcr.io/autonomyops/adk-ros2-runtime:local

• If Docker is absent the native fallback path is taken; ros2-runtime-container-ready will not appear.

ErrImageRequired

Both autonomy ros2 run and autonomy run ros2.launch require --image when the Docker daemon is reachable. If --image is omitted on a Docker-capable host you will see:

ros2: container path selected but no image specified

Pass --image ghcr.io/autonomyops/adk-ros2-runtime:local to either command.

ErrNeitherAvailable

Docker is absent and ros2 is not in PATH. Install Docker for full governance or install ROS2 Humble for the native fallback path.

Next steps

CE-tier follow-ups (single-node, no orchestrator):

I want to …	Read
Understand policy governance	ROS2 Governance
Run the Gazebo simulation stack	Gazebo Simulation
Use NVIDIA GPU inference	NVIDIA GPU Integration
Inspect, stage, and verify bundles offline	Bundle Workflows
Understand PASS markers and the local WAL	Markers and Observability
Adapt the demo to real hardware	Hardware Adaptation