# Record robot run provenance

Keep telemetry and captured software, hardware, and model evidence together in comparable robot episodes.

Canonical: https://oorb.io/docs/robot-run-provenance/
Maintained by: OORB
Updated: 2026-10-14

## What an episode records

An OORB episode keeps a robot run's MCAP timeline with captured provenance. Depending on the capture path and available evidence, that includes software state, hardware observations, robotics configuration, interface information, and the model record.

Evidence availability varies. A recorded artifact is not a guarantee that every dependency, physical condition, or model input was observed. Inspect the episode before using it as a release reference.

## Capture from a recording

Initialize the workspace in your robot project first, as shown in [getting started](/docs/getting-started/). Then import a recording:

```sh
runfp snapshot recordings/run.mcap --label pick-place --json
runfp episodes list --label pick-place
```

Use one label for repeated trials of the same task. Store the task definition and controlled conditions alongside your experiment so labels do not silently combine unrelated workloads.

For a team-defined comparison protocol, attach the protocol file during capture:

```sh
runfp snapshot recordings/run.mcap --label pick-place --protocol protocols/pick-place.yaml
```

Protocols can specify required topics, schemas, duration requirements, and comparison tolerances. Use a protocol prepared for your application; this guide does not prescribe universal robot tolerances.

## Preserve the difference between code and outcomes

Run history includes available commit information. A dirty workspace marker means local changes existed at capture time; a commit identifier alone therefore may not reproduce the exact run.

```sh
runfp history pick-place
runfp episodes list --commit <commit-prefix>
```

Some capture paths record process exit codes or SDK completion statuses. An imported MCAP may have neither. A process returning zero establishes the recorded process outcome; your application must make that outcome correspond to a meaningful task result.

## Share the same evidence

Export an episode to exchange the artifact with a teammate:

```sh
runfp episodes export <episode-id>
```

On the receiving installation, import the resulting archive:

```sh
runfp episodes import <episode-id>.oorb-episode.tar.gz
```

Episode identity is content-addressed. Importing the same capture again does not create a new independent physical trial for reliability statistics.

Next, [compare a baseline with a candidate run](/docs/compare-robot-runs/).