> ## 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.

# VM from Scenario

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

`sandbox prepare` sets up the full scenario environment — provisions VMs, runs `prepare.yml` to introduce the failure condition, 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.                                            |

Prepare fails fast if `prepare.yml` exits non-zero. Fix the playbook and re-run.

***

## `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.4/scenario-runner/sandbox-templates)) to clean up stale VMs, then manually remove orphaned host/agent records from the DB if needed.
</Warning>