# Environments

Versioned catalogue scenes, from a bare bench cell to an instrumented surgical replica — with the reset problem handled for you.

An environment is the other half of a result's address. `kitchen-std@v1.2`
names a specific catalogue scene at a specific revision: the same 214
objects, the same layout envelope, the same instrumentation. When the scene
changes — an object swapped, a fixture moved — the revision changes, and
results across revisions stop being silently comparable.

## The catalogue

*Example: roborama.environments.list()*

**Python**

```python
import roborama  # reads ROBORAMA_API_KEY from the environment

robots = roborama.robots.list()
print(robots)
# [{id:"g1-edu-pro", class:"humanoid", dof:37, hands:"dex3-1",
#   firmwares:["2.3","2.4"], cells:6, duty_cycle_pct:71, tier:"verify"}]

environments = roborama.environments.list(cls="kitchen")
print(environments)
# [{id:"kitchen-std", rev:"v1.2", instrumentation:["mocap","ft"],
#   objects:214, reset:"scripted", adder_tier:"replica"}]
```

**TypeScript**

```typescript
import Roborama from "@roborama/sdk"; // reads ROBORAMA_API_KEY

const roborama = new Roborama();

const robots = await roborama.robots.list();
console.log(robots);
// [{ id: "g1-edu-pro", class: "humanoid", dof: 37, hands: "dex3-1",
// firmwares: ["2.3", "2.4"], cells: 6,
//   duty_cycle_pct: 71, tier: "verify" }]

const environments = await roborama.environments.list({ cls: "kitchen" });
console.log(environments);
// [{ id: "kitchen-std", rev: "v1.2", instrumentation: ["mocap", "ft"],
//    objects: 214, reset: "scripted", adder_tier: "replica" }]
```

**cURL**

```bash
curl https://api.roborama.com/v1/robots \
  -H "Authorization: Bearer $ROBORAMA_API_KEY"

curl "https://api.roborama.com/v1/environments?cls=kitchen" \
  -H "Authorization: Bearer $ROBORAMA_API_KEY"
```

**Agent (tool-use payload)**

```json
[
  {
    "type": "tool_use",
    "name": "roborama_list_robots",
    "input": {}
  },
  {
    "type": "tool_use",
    "name": "roborama_list_environments",
    "input": { "cls": "kitchen" }
  }
]
```

| Field | Type | Notes |
| --- | --- | --- |
| `id` | `str` | catalogue id; pin a revision with `@`, e.g. `kitchen-std@v1.2` |
| `rev` | `str` | scene revision; bumped whenever objects, layout envelope, or instrumentation change |
| `class` | `str` | `bench`, `kitchen`, `warehouse`, `surgical` — filter with `list(cls=...)` |
| `instrumentation` | `str[]` | `mocap` (6-DoF ground-truth poses), `ft` (wrist force-torque), `overhead-cam`, `high-speed-cam` |
| `objects` | `int` | catalogued objects in the scene's manifest |
| `reset` | `"scripted" \| "teleop-assisted"` | how the scene returns to initial conditions between episodes |
| `adder_tier` | `str` | pricing tier: `bare`, `standard`, `replica`, `instrumented-replica` |

The current catalogue spans the ladder: `cell-a` (a bare bench, 24 objects,
one overhead camera), `warehouse-std@v2.0` (388 objects under mocap),
`kitchen-std@v1.2` (a replica kitchen with mocap and force-torque sensing),
and `surgical-replica@v3` (61 objects, mocap, force-torque, and high-speed
cameras, with teleop-assisted resets).

## Instrumentation is what you're buying

The environment-hour meter prices what the scene can *measure*, which is why
`adder_tier` exists. A bare cell tells you whether the episode succeeded. An
instrumented replica also tells you *why*: mocap gives 6-DoF ground-truth
object poses on `/gt/object_poses`, force-torque gives contact evidence on
`/ft_wrist`. Those channels are what make failure clusters diagnosable and
what [verify()](/docs/primitives/verify/) returns to recalibrate a simulator.
Rates per tier are on [/pricing/](/pricing/).

## Resets are the throughput

Between every episode the scene has to return to initial conditions — objects
back on their marks, within the perturbation schedule's declared jitter. In
un-automated labs this is where the time goes: Physical Intelligence's
published online-RL result puts it at 7 of every 8 wall-clock minutes
(detailed on [/research/](/research/)). Catalogue scenes are built for scripted resets, so
episodes stream instead of trickle; `surgical-replica@v3` is the exception
where a human assists, and its `queue_eta` and adder tier reflect that.

> **Perturbation lives on the run, not the scene:** The revision pins what the scene *is*. How much each episode deviates —
> layout jitter, lighting, distractors — is the run's
> [perturbation schedule](/docs/primitives/run/), seeded and recorded per
> episode. Same scene revision + same schedule + same seed = the same
> distribution of initial conditions, replayable.

## Where next

- [Robots & firmware](/docs/concepts/robots-and-firmware/) — the embodiment half of the address.
- [quote](/docs/api-reference/quote/) — what a robot × environment × episodes job costs before you run it.
- [Data contract](/docs/concepts/data-contract/) — what the instrumentation records, channel by channel.