Hosts

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:

Boots a VM clone from the specified template
Injects the runner’s SSH public key and waits for SSH to become available
Registers a host record in the DB (using the VM’s IP and port)
Runs the scenario (prepare → execute → validate)
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

Template	Description
`debian-base`	Debian 12 with basic tools (curl, wget, python3, vim, git)
`debian-docker`	Debian 12 with Docker CE pre-installed
`debian-podman`	Debian 12 with Podman pre-installed (rootful, cgroupfs)
`debian-k3s`	Debian 12 with k3s (lightweight Kubernetes) pre-installed
`debian-localstack`	Debian 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

Field	Mode	Description
`host_id`	host	Reuse an existing host from the DB. If provided, all other fields are ignored.
`host_name`	all	Identifier used to link agents to this host and as the Ansible inventory hostname. Required in VM mode.
`template`	incus/lima	VM template to boot. Required in VM mode.

Get Started

Authoring

Running

VM Sandbox

Host Mode (`--mode host`)

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

Available Templates

Multiple Hosts

Field Reference

​Host Mode (--mode host)

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

​Available Templates

​Multiple Hosts

​Field Reference

Host Mode (`--mode host`)

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

Available Templates

Multiple Hosts

Field Reference