# Configuring a rig

> Describe cameras, joint-state sources, clocks and frames in one rig.toml file.

Source: https://rayform.world/docs/engine/rig-config
Last updated: 2026-10-19
Status: Rayform is in private preview. The edge engine is in development with preview teams, and commands, formats and APIs described here may change before general availability.

A rig file tells the engine what to read, how fast, and how the devices relate in space and time. Keep one file per physical rig under version control; every run records a copy of the file it used.

## Example

```toml title="rig.toml"
[rig]
name = "lab-2-bimanual"
base_frame = "base_link"
clock = "ptp"                 # "ptp", "trigger" or "host"

[[camera]]
name = "front"
driver = "ros2:/front/camera"
streams = ["rgb", "depth"]
fps = 30
resolution = [640, 480]

[[camera]]
name = "wrist_left"
driver = "ros2:/left/wrist_camera"
streams = ["rgb"]
fps = 50
mount = "left_arm/tool0"      # the camera moves with this link

[[joints]]
name = "left_arm"
source = "ros2:/left/joint_states"
rate_hz = 200

[[joints]]
name = "left_gripper"
source = "ros2:/left/gripper/state"
rate_hz = 100

[episodes]
split_on = "key"              # "key", "gripper" or "idle"
idle_seconds = 4

[storage]
path = "/data/runs"
reserve_gb = 50               # stop cleanly before the disk fills
```

## Keys

| Key | Meaning |
| --- | --- |
| `rig.base_frame` | The frame all cameras and point clouds are expressed in |
| `rig.clock` | How devices share time: `ptp`, `trigger` (common hardware trigger) or `host` |
| `camera.driver` | `ros2:<namespace>` to read a camera published on ROS 2; native drivers are confirmed with each preview team |
| `camera.streams` | Any of `rgb`, `depth`, `ir` |
| `camera.mount` | Link the camera is attached to; omit for static cameras |
| `joints.source` | `ros2:<topic>`; native vendor drivers are confirmed with each preview team |
| `episodes.split_on` | End episodes on a key press, on gripper open after a close, or after idle time |
| `storage.reserve_gb` | Free space the engine keeps; capture stops cleanly before crossing it |

## Check a rig before recording

```bash
rayform rig check rig.toml          # devices found, rates, clocks
rayform capture --rig rig.toml --bench --seconds 60
```

The bench run captures without saving and reports sustained rates, drops and back-pressure per device.