VM from Scenario

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

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

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.

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.

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

Getting Started

Deployment

Core Concepts

Configure

Scenario Runner

CLI

VM from Scenario

Typical Workflow

`sandbox prepare`

`sandbox restore`

​Typical Workflow

​sandbox prepare

​sandbox restore

Typical Workflow

`sandbox prepare`

`sandbox restore`