Skip to main content
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

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