# Quickstart

> Upload one recording, wait for it to process, and load the result in Python.

Source: https://rayform.world/docs/quickstart
Last updated: 2026-10-18
Status: Rayform is in private preview. APIs, formats and the SDK described here may change before general availability.

This guide takes one recording from your machine to a PyTorch batch. You need Python 3.10 or later and a Rayform API key from the private preview.

## 1. Install the SDK

```bash
pip install rayform
```

The core package depends only on NumPy and PyArrow. Add extras when you need them:

```bash
pip install "rayform[torch]"        # PyTorch datasets
pip install "rayform[lerobot]"      # LeRobot export helpers
pip install "rayform[rerun]"        # open segments in the Rerun viewer
```

## 2. Authenticate

Create a key in the [console](https://console.rayform.world/keys) and export it. The SDK and the CLI both read `RAYFORM_API_KEY`.

```bash
export RAYFORM_API_KEY="rf_live_..."
rayform whoami
```

```text
org_7Hq2 · Acme Robotics · key rf_live_...9c2f (read, write)
```

## 3. Upload a recording

Any MCAP file or ROS 2 bag with at least one camera works. Include joint states if a robot is in the loop. `site` groups recordings made in the same place, so repeat visits are registered into one coordinate frame.

```python
import rayform

client = rayform.Client()
session = client.sessions.upload(
    "recordings/kitchen_2026-10-14.mcap",
    site="lab-2",
    wait=True,          # block until processing finishes
)
print(session.id, session.status)
```

```text
ses_01JA8K2M9Q processed
```

Uploads are resumable: if the connection drops, run the same call again and it continues from the last confirmed part.

## 4. Look at what came back

```python
for seg in session.segments():
    print(seg.id, seg.duration_s, [e.type for e in seg.events()])
```

```text
seg_4f0a 7.45 ['grasp', 'place']
seg_4f0b 5.10 ['open_drawer']
seg_4f0c 9.80 ['grasp', 'handover', 'place']
```

Open one in the Rerun viewer to check the reconstruction against the raw camera frames:

```python
rayform.rerun.show(session.segments()[0])
```

## 5. Freeze a slice and train

```python
from torch.utils.data import DataLoader

slice_ = client.slices.create(segments=session.segments(), name="quickstart")

dataset = rayform.torch.EpisodeDataset(
    slice_,
    obs=["cam0/rgb", "cam0/depth", "joints/position"],
    action="joints/position_delta",
    fps=15,
)
batch = next(iter(DataLoader(dataset, batch_size=8)))
print({k: tuple(v.shape) for k, v in batch.items()})
```

```text
{'cam0/rgb': (8, 3, 480, 640), 'cam0/depth': (8, 1, 480, 640), 'joints/position': (8, 7), 'action': (8, 7)}
```

## Next steps

- [Preparing recordings](https://rayform.world/docs/guides/preparing-recordings): get the best alignment and reconstruction.
- [Search and slices](https://rayform.world/docs/guides/search-and-slices): find the moments that matter across all your data.
- [Exporting to training formats](https://rayform.world/docs/guides/exporting): LeRobot, RLDS, WebDataset, MCAP and USD.