> ## Documentation Index
> Fetch the complete documentation index at: https://docs.2501.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Hosts

> Target host configuration for host mode and VM mode

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.

```json theme={null}
"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.

```json theme={null}
"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)
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

| 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](/0.8/benchmark/sandbox-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`.

```json theme={null}
"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.                                                               |