Agents

The agents array in scenario.json tells the runner which agents execute the scenario. Like hosts, how you define an agent depends on the execution mode.

Host Mode (`--mode host`)

In host mode, you reference an existing agent already registered in your 2501 deployment. The runner flushes the agent’s memory before execution to ensure a clean slate, then leaves the record untouched after the run.

"agents": [
  {
    "agent_id": "agt_xyz789",
    "host_name": "web-01"
  }
]

Find agent IDs in the Command Center or via the API. host_name must match a host_name defined in the hosts array (or use host_id directly if preferred).

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

In VM mode, hosts are ephemeral VMs created fresh for each run, so agents are also defined inline and created from scratch. The runner injects SSH credentials automatically — you don’t need to provide them.

"agents": [
  {
    "agent_name": "web-agent",
    "host_name": "web-01",
    "specialty_key": "SERVICES_MANAGER"
  }
]

What the runner does for each run:

Creates a new agent record in the DB with the provided fields
Injects SSH credentials for the provisioned VM automatically
Flushes memory at run start
Removes the agent record from the DB after the run

The host_name must match a host_name defined in the hosts array.

Multiple Agents

"agents": [
  { "agent_name": "web-agent", "host_name": "web-01", "specialty_key": "SERVICES_MANAGER" },
  { "agent_name": "db-agent",  "host_name": "db-01",  "specialty_key": "DATABASE_MANAGER" }
]

Field Reference

Field	Mode	Description
`agent_id`	host	Reuse an existing agent from the DB. If provided, the agent is not re-created.
`agent_name`	VM / new	Display name for the agent. Required when creating a new agent.
`host_name`	all	Links this agent to a host defined in the `hosts` array.
`host_id`	host	Alternative to `host_name`: link to a host by its DB ID.
`specialty_key`	VM / new	Specialty key for the agent (e.g. `SERVICES_MANAGER`, `KUBERNETES_OPERATOR`).

Getting Started

Deployment

Core Concepts

Configure

Scenario Runner

CLI

Host Mode (`--mode host`)

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

Multiple Agents

Field Reference

​Host Mode (--mode host)

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

​Multiple Agents

​Field Reference

Host Mode (`--mode host`)

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

Multiple Agents

Field Reference