Skip to main content
The hosts array in scenario.json tells the runner which machines the scenario targets. How you define a host depends on the execution mode.

​
Host Mode (--mode host)

In host mode, you reference an existing host already registered in your 2501 deployment. The runner looks it up by ID and leaves the record untouched after the run. 
"hosts": [
  { "host_id": "hst_abc123" }
]
Find host IDs in the Command Center or via the API.

​
VM Mode (--mode incus / --mode lima)

In VM mode, the runner provisions a fresh VM from a template before each scenario run and destroys it afterward. No pre-existing host record is needed — the runner creates and removes it automatically. 
"hosts": [
  {
    "host_name": "web-01",
    "template": "debian-base"
  }
]
What the runner does for each run:
  1. Boots a VM clone from the specified template
  2. Injects the runner’s SSH public key and waits for SSH to become available
  3. Registers a host record in the DB (using the VM’s IP and port)
  4. Runs the scenario (prepare → execute → validate → restore)
  5. Destroys the VM and removes the host record from the DB
The host_name becomes the Ansible inventory hostname and is used by agents to reference this host.

​
Available Templates

TemplateDescription
debian-baseDebian 12 with basic tools (curl, wget, python3, vim, git)
debian-dockerDebian 12 with Docker CE pre-installed
debian-podmanDebian 12 with Podman pre-installed (rootful, cgroupfs)
debian-k3sDebian 12 with k3s (lightweight Kubernetes) pre-installed
debian-localstackDebian 12 with AWS CLI v2 and moto server on port 4566
Templates are VM images the runner clones from. They are initialized automatically on first use. See Templates for the full list and management commands.

​
Multiple Hosts

For multi-host scenarios, define each host separately. Each agent references its host by host_name. 
"hosts": [
  { "host_name": "web-01", "template": "debian-base" },
  { "host_name": "db-01",  "template": "debian-base" }
]

​
Field Reference

FieldModeDescription
host_idhostReuse an existing host from the DB. If provided, all other fields are ignored.
host_nameallIdentifier used to link agents to this host and as the Ansible inventory hostname. Required in VM mode.
templateincus/limaVM template to boot. Required in VM mode.