Skip to main content
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]
OptionDefaultDescription
-s, --scenarios <list>requiredScenarios to prepare: comma-separated tags or explicit keys.
-m, --mode <mode>hostExecution mode: host | incus | lima.
-p, --scenarios-path <path>auto-detectedPath to scenarios directory.
--vm-templates-path <path>auto-detectedPath to VM templates directory.
--specialty <key>Override specialty for all agents.
--env-file <path>auto-detectedPath 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>]
OptionDefaultDescription
-s, --scenarios <list>requiredScenarios to restore: comma-separated tags or explicit keys.
-m, --mode <mode>hostExecution mode used during prepare: host | incus | lima.
-p, --scenarios-path <path>auto-detectedPath to scenarios directory.
--env-file <path>auto-detectedPath 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.