Skip to main content
Most deployments use --mode host with pre-provisioned VMs. VM sandbox mode is for teams that want the runner to provision and destroy VMs automatically — no manual VM management, no lingering state between runs.

​
Why VM Mode

In --mode host, the runner connects to existing hosts already registered in your 2501 deployment. The host persists between runs and must be manually reset. In --mode incus or --mode lima, the runner creates a fresh VM clone for each run and destroys it afterward. Every scenario starts from an identical, known-good state. This is useful for:
  • Reproducible benchmarks: no leftover state from previous runs that can affect results
  • Parallel runs: multiple VMs can run simultaneously without interfering (--parallel)
  • Playbook development: iterate on scenarios without having to manually reset a shared host

​
Prerequisites

​
Both modes

Ansible must be installed and available in PATH: 
# macOS
brew install ansible

# Debian/Ubuntu
apt-get install ansible

​
--mode lima (macOS)

Lima runs VMs using Apple’s Virtualization framework. Networking requires socket_vmnet. 
# 1. Install Lima and socket_vmnet
brew install lima
brew install socket_vmnet

# 2. Copy socket_vmnet to the expected system path
sudo mkdir -p /opt/socket_vmnet/bin
sudo cp /opt/homebrew/opt/socket_vmnet/bin/socket_vmnet /opt/socket_vmnet/bin/socket_vmnet
sudo chown root:wheel /opt/socket_vmnet/bin/socket_vmnet

# 3. Install Lima sudoers config (allows Lima to manage networking without sudo prompts)
limactl sudoers | sudo tee /private/etc/sudoers.d/lima

# 4. Create the Lima runtime directory
sudo mkdir -p /private/var/run/lima
sudo chown root:daemon /private/var/run/lima
sudo chmod 775 /private/var/run/lima

​
--mode incus (Linux)

Incus manages system containers and VMs. Install it following the official guide for your distribution, then initialize: 
# See: https://linuxcontainers.org/incus/docs/main/installing/

# After installation, initialize Incus (run once)
incus admin init

​
How Templates Work

VM modes use templates: stopped VM instances pre-provisioned with the required software (Docker, k3s, etc.). When a scenario runs, the runner clones the template, starts the clone, runs the scenario, and destroys the clone afterward. The template itself is never modified. Templates are created automatically the first time a scenario references them. See Templates for the full list and management commands.

​
What’s in This Section

  • Templates — available templates, resources, and how to manage them
  • VM from Scenario — step into a scenario environment to inspect state and iterate on playbooks
  • VM for Testing — provision standalone VMs for ad-hoc agent testing