> ## Documentation Index
> Fetch the complete documentation index at: https://rapidreview.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Sandboxes

> Ephemeral machines the brain provisions on your provider account: leases, long runs that survive disconnects, and why nothing is copied back for you.

An SSH-reachable machine (GPU or CPU) the brain provisions on demand from a provider you've configured, hands to the agent for one experiment, and destroys when the lease ends. It bills while it exists.

The brain owns the lifecycle — request, lease, expiry, termination. The agent owns the SSH key, the commands, and retaining every valuable output.

## Lifecycle

| Step                            | Tool                                 | Notes                                                                                                                                                                                                                             |
| ------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| See what's available            | `sandbox.options`                    | Hardware options tagged with the provider that serves them and a price where the provider exposes one                                                                                                                             |
| Ask for a machine               | `sandbox.request`                    | The option's provider-shaped values and the agent's **public** key. `needs_selection` → choose; `provisioning` → poll `sandbox.get` at the advised interval. `additional: true` asks for a second machine for the same experiment |
| Use it                          | SSH from the returned host/port/user | Response hints give the remote experiment directory and expiry                                                                                                                                                                    |
| Reuse it for another experiment | `sandbox.attach`                     | Associates a running sandbox with another experiment                                                                                                                                                                              |
| Watch long runs                 | `sandbox.runs`                       | Durable receipts of `merv_run` launches                                                                                                                                                                                           |
| Peek                            | `sandbox.terminal`                   | Concise diagnosis only, not a monitor                                                                                                                                                                                             |
| Get files back                  | `sandbox.pull_outputs`               | Returns a command the agent runs locally with its private key                                                                                                                                                                     |
| Keep it longer                  | `sandbox.extend`                     | Support and limits are provider-dependent                                                                                                                                                                                         |
| Destroy it                      | `sandbox.release`                    | Two-step — see below                                                                                                                                                                                                              |

## Long runs: `merv_run`

Anything longer than a few minutes runs through the wrapper installed at bootstrap:

```sh theme={"theme":{"light":"github-light","dark":"dark-plus"}}
merv_run <unique-label> -- <command>
```

Detaches from SSH, survives disconnects, records a durable receipt. Labels are one-shot. The agent watches the receipt (`sandbox.runs`, or a watcher armed from the returned `wait_url`) and reads both `status` and `exit_code` — finished is not succeeded.

`unknown`: the machine died before its receipts were read (retained evidence may still settle it; otherwise rerun). `lost`: receipts were read and no completion sentinel existed.

## Where files go, and what survives

| Path                   | For                                                                |
| ---------------------- | ------------------------------------------------------------------ |
| `$MERV_EXPERIMENT_DIR` | Scripts, configs, compact results, reports, figures — the evidence |
| `$RP_DATASET_DIR`      | Disposable datasets, caches, bulky checkpoints                     |

Nothing is copied automatically; release and expiry destroy anything not retained.

<Warning>
  `sandbox.release` is deliberately two-step: the first call returns a retention checklist and destroys nothing; the second, with `confirm_retained: true`, terminates. Retention: [Working with sandboxes](/docs/merv/guides/working-with-sandboxes).
</Warning>

## Providers

Eleven, from Lambda Labs to AWS, GCP, and Azure — ten configured per project in **Settings → Compute** (credentials, verify, enable, daily USD limit); Modal by environment variables on the brain. [Sandbox providers](/docs/merv/reference/sandbox-providers)

<Warning>
  On every VM provider a stopped machine still bills its disks. Only termination stops charges — which is what release does.
</Warning>

How-to: [Working with sandboxes](/docs/merv/guides/working-with-sandboxes).