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

# From a Scenario

> Step into a broken scenario environment to inspect state and iterate on playbooks

`sandbox prepare` sets up the full scenario environment (provisions VMs and runs `prepare.yml` to introduce the failure condition, and registers hosts and agents in the DB) but stops before dispatching the task to any agent. This lets you SSH in, inspect the state, and experiment freely.

When you're done, `sandbox restore` tears everything down.

***

## Typical Workflow

```bash theme={null}
# 1. Prepare the environment
2501 runner sandbox prepare -s nginx/001-broken-config -m lima

# 2. SSH in using the printed credentials
ssh -i ~/.ssh/runner_key debian@10.0.0.5 -p 22

# 3. Inspect the broken state, test fixes, iterate
nginx -t
cat /etc/nginx/sites-available/default

# 4. Tear down when done
2501 runner sandbox restore -s nginx/001-broken-config -m lima
```

After `prepare`, the runner prints everything you need:

```
[nginx/001-broken-config] Environment ready
SSH:      ssh -i ~/.ssh/runner_key debian@10.0.0.5 -p 22
Agents:   agt_...
Hosts:    hst_...
Restore:  2501 runner sandbox restore -s nginx/001-broken-config -m lima
```

***

## `sandbox prepare`

```bash theme={null}
2501 runner sandbox prepare -s <scenarios> [options]
```

| Option                        | Default       | Description                                                  |
| ----------------------------- | ------------- | ------------------------------------------------------------ |
| `-s, --scenarios <list>`      | required      | Scenarios to prepare: comma-separated tags or explicit keys. |
| `-m, --mode <mode>`           | `host`        | Execution mode: `host` \| `incus` \| `lima`.                 |
| `-p, --scenarios-path <path>` | auto-detected | Path to scenarios directory.                                 |
| `--vm-templates-path <path>`  | auto-detected | Path to VM templates directory.                              |
| `--specialty <key>`           |               | Override specialty for all agents.                           |
| `--env-file <path>`           | auto-detected | Path to env file.                                            |

If `prepare.yml` exits non-zero, the runner prints a warning but still finishes setting up the environment and reports it as ready, so you can SSH in and investigate why the playbook failed.

***

## `sandbox restore`

Tears down environments created with `sandbox prepare`: destroys VMs (incus/lima), runs `restore.yml` (host mode), and removes registered hosts and agents from the DB.

```bash theme={null}
2501 runner sandbox restore -s <scenarios> [-m <mode>]
```

| Option                        | Default       | Description                                                      |
| ----------------------------- | ------------- | ---------------------------------------------------------------- |
| `-s, --scenarios <list>`      | required      | Scenarios to restore: comma-separated tags or explicit keys.     |
| `-m, --mode <mode>`           | `host`        | Execution mode used during prepare: `host` \| `incus` \| `lima`. |
| `-p, --scenarios-path <path>` | auto-detected | Path to scenarios directory.                                     |
| `--env-file <path>`           | auto-detected | Path to env file.                                                |

<Warning>
  Always restore after preparing. If you interrupt a session without restoring, use `sandbox purge-vms` (see [Templates](/0.8/benchmark/sandbox-templates)) to clean up stale VMs, then manually remove orphaned host/agent records from the DB if needed.
</Warning>