Agents And Coordinator
Learn how coordinator and agent nodes split, execute, and merge one clustered LoadStrike run.
Matching docs
Search across docs titles, summaries, groups, and section headings.
Use Up and Down Arrow to move through results, then press Enter to open the active page.
No indexed docs matched that search. Try a broader term or open the docs hub.
What this page helps you do
What this page helps you do
Learn how coordinator and agent nodes split, execute, and merge one clustered LoadStrike run.
Who this is for
Teams moving from one machine to coordinator-and-agent execution or tighter workload targeting.
Prerequisites
- A scenario that already works in a single-node run
By the end
A clearer cluster topology and the fields that must line up across nodes.
Use this page when
Use this page when execution topology, partitioning, or targeting changes how the run should be distributed.
Visual guide
Guide
Two ways to run cluster mode
EnableLocalDevCluster(true) starts child agents in-process for local development. Distributed mode uses NodeType plus NatsServerUrl so separate coordinator and agent processes can communicate over NATS.
What the coordinator controls
The coordinator sets ClusterId, AgentGroup, AgentsCount, optional coordinator or agent target lists, and ClusterCommandTimeout. It is also the node that produces the final merged report.
What agents need
Agents need NodeType.Agent, the same ClusterId, the same AgentGroup if one is used, and the NATS server URL. They usually do not need a runner key in example docs unless the selected deployment path requires it on that process.
How scenario targeting works
TargetScenarios applies a shared filter, AgentTargetScenarios narrows agent-side work, and CoordinatorTargetScenarios narrows coordinator-side work. Use these lists when different nodes should own different parts of the transaction.
Cluster setup samples
Register the same scenarios on both roles, then use coordinator and agent targeting to decide which role executes which scenario name. Start agents first, then trigger the coordinator.
If you run these examples locally, add a valid runner key before execution starts. Set it with WithRunnerKey("...") or the config key LoadStrike:RunnerKey.
Coordinator + Agent Configuration
using LoadStrike;
var clusterId = "orders-cluster";
var natsUrl = "nats://nats.example.internal:4222";
var publishOrdersScenario = LoadStrikeScenario.Create(
"publish-orders",
_ => Task.FromResult(LoadStrikeResponse.Ok(statusCode: "202")))
.WithLoadSimulations(LoadStrikeSimulation.IterationsForConstant(1, 2));
var observeCompletionScenario = LoadStrikeScenario.Create(
"observe-completion",
_ => Task.FromResult(LoadStrikeResponse.Ok(statusCode: "200")))
.WithLoadSimulations(LoadStrikeSimulation.IterationsForConstant(1, 2));
var agentContext = LoadStrikeRunner
.RegisterScenarios(publishOrdersScenario, observeCompletionScenario)
.WithNodeType(LoadStrikeNodeType.Agent)
.WithClusterId(clusterId)
.WithAgentTargetScenarios("observe-completion")
.WithNatsServerUrl(natsUrl);
// Each agent process listens for the scenario names assigned to agents.
agentContext.Run();
var coordinatorContext = LoadStrikeRunner
.RegisterScenarios(publishOrdersScenario, observeCompletionScenario)
.WithNodeType(LoadStrikeNodeType.Coordinator)
.WithClusterId(clusterId)
.WithAgentsCount(2)
.WithCoordinatorTargetScenarios("publish-orders")
.WithAgentTargetScenarios("observe-completion")
.WithNatsServerUrl(natsUrl)
.WithRunnerKey("rkr_your_remote_runner_key");
// The coordinator triggers only its own scenarios and routes agent work by scenario name.
coordinatorContext.Run();package main
import loadstrike "loadstrike.com/sdk/go"
func main() {
loadstrike.RegisterScenarios(loadstrike.Empty("cluster-routing")).
WithClusterId("cluster-orders-prod").
WithAgentGroup("brokers").
WithNatsServerUrl("nats://127.0.0.1:4222").
WithTargetScenarios("source", "destination").
WithAgentTargetScenarios("destination").
WithCoordinatorTargetScenarios("source").
Run()
}import com.loadstrike.runtime.LoadStrikeRuntime.LoadStrikeResponse;
import com.loadstrike.runtime.LoadStrikeRuntime.LoadStrikeNodeType;
import com.loadstrike.runtime.LoadStrikeRuntime.LoadStrikeRunner;
import com.loadstrike.runtime.LoadStrikeRuntime.LoadStrikeScenario;
import com.loadstrike.runtime.LoadStrikeRuntime.LoadStrikeSimulation;
String clusterId = "orders-cluster";
String natsUrl = "nats://nats.example.internal:4222";
var publishOrdersScenario = LoadStrikeScenario
.create("publish-orders", ignoredContext -> LoadStrikeResponse.ok("202"))
.withLoadSimulations(LoadStrikeSimulation.iterationsForConstant(1, 2));
var observeCompletionScenario = LoadStrikeScenario
.create("observe-completion", ignoredContext -> LoadStrikeResponse.ok("200"))
.withLoadSimulations(LoadStrikeSimulation.iterationsForConstant(1, 2));
var agentRunner = LoadStrikeRunner
.registerScenarios(publishOrdersScenario, observeCompletionScenario)
.withNodeType(LoadStrikeNodeType.Agent)
.buildContext()
.withClusterId(clusterId)
.withAgentTargetScenarios("observe-completion")
.withNatsServerUrl(natsUrl);
// Each agent process listens for the scenario names assigned to agents.
agentRunner.run();
var coordinatorRunner = LoadStrikeRunner
.registerScenarios(publishOrdersScenario, observeCompletionScenario)
.withNodeType(LoadStrikeNodeType.Coordinator)
.buildContext()
.withClusterId(clusterId)
.withAgentsCount(2)
.withCoordinatorTargetScenarios("publish-orders")
.withAgentTargetScenarios("observe-completion")
.withNatsServerUrl(natsUrl)
.withRunnerKey("rkr_your_remote_runner_key");
// The coordinator triggers only its own scenarios and routes agent work by scenario name.
coordinatorRunner.run();from loadstrike_sdk import LoadStrikeResponse, LoadStrikeRunner, LoadStrikeScenario, LoadStrikeSimulation
cluster_id = "orders-cluster"
nats_url = "nats://nats.example.internal:4222"
publish_orders_scenario = (
LoadStrikeScenario.create("publish-orders", lambda _: LoadStrikeResponse.ok("202"))
.with_load_simulations(LoadStrikeSimulation.iterations_for_constant(1, 2))
)
observe_completion_scenario = (
LoadStrikeScenario.create("observe-completion", lambda _: LoadStrikeResponse.ok("200"))
.with_load_simulations(LoadStrikeSimulation.iterations_for_constant(1, 2))
)
agent_runner = (
LoadStrikeRunner.register_scenarios(publish_orders_scenario, observe_completion_scenario)
.with_node_type("Agent")
.with_cluster_id(cluster_id)
.with_agent_target_scenarios("observe-completion")
.with_nats_server_url(nats_url)
)
# Each agent process listens for the scenario names assigned to agents.
agent_runner.run()
coordinator_runner = (
LoadStrikeRunner.register_scenarios(publish_orders_scenario, observe_completion_scenario)
.with_node_type("Coordinator")
.with_cluster_id(cluster_id)
.with_agents_count(2)
.with_coordinator_target_scenarios("publish-orders")
.with_agent_target_scenarios("observe-completion")
.with_nats_server_url(nats_url)
.with_runner_key("rkr_your_remote_runner_key")
)
# The coordinator triggers only its own scenarios and routes agent work by scenario name.
coordinator_runner.run()import {
LoadStrikeResponse,
LoadStrikeRunner,
LoadStrikeScenario,
LoadStrikeSimulation
} from "@loadstrike/loadstrike-sdk";
const clusterId = "orders-cluster";
const natsUrl = "nats://nats.example.internal:4222";
const publishOrdersScenario = LoadStrikeScenario
.create("publish-orders", async () => LoadStrikeResponse.ok("202"))
.withLoadSimulations(LoadStrikeSimulation.iterationsForConstant(1, 2));
const observeCompletionScenario = LoadStrikeScenario
.create("observe-completion", async () => LoadStrikeResponse.ok("200"))
.withLoadSimulations(LoadStrikeSimulation.iterationsForConstant(1, 2));
const agentRunner = LoadStrikeRunner
.registerScenarios(publishOrdersScenario, observeCompletionScenario)
.withNodeType("Agent")
.withClusterId(clusterId)
.withAgentTargetScenarios("observe-completion")
.withNatsServerUrl(natsUrl);
// Each agent process listens for the scenario names assigned to agents.
await agentRunner.run();
const coordinatorRunner = LoadStrikeRunner
.registerScenarios(publishOrdersScenario, observeCompletionScenario)
.withNodeType("Coordinator")
.withClusterId(clusterId)
.withAgentsCount(2)
.withCoordinatorTargetScenarios("publish-orders")
.withAgentTargetScenarios("observe-completion")
.withNatsServerUrl(natsUrl)
.withRunnerKey("rkr_your_remote_runner_key");
// The coordinator triggers only its own scenarios and routes agent work by scenario name.
await coordinatorRunner.run();const {
LoadStrikeResponse,
LoadStrikeRunner,
LoadStrikeScenario,
LoadStrikeSimulation
} = require("@loadstrike/loadstrike-sdk");
(async () => {
const clusterId = "orders-cluster";
const natsUrl = "nats://nats.example.internal:4222";
const publishOrdersScenario = LoadStrikeScenario
.create("publish-orders", async () => LoadStrikeResponse.ok("202"))
.withLoadSimulations(LoadStrikeSimulation.iterationsForConstant(1, 2));
const observeCompletionScenario = LoadStrikeScenario
.create("observe-completion", async () => LoadStrikeResponse.ok("200"))
.withLoadSimulations(LoadStrikeSimulation.iterationsForConstant(1, 2));
const agentRunner = LoadStrikeRunner
.registerScenarios(publishOrdersScenario, observeCompletionScenario)
.withNodeType("Agent")
.withClusterId(clusterId)
.withAgentTargetScenarios("observe-completion")
.withNatsServerUrl(natsUrl);
// Each agent process listens for the scenario names assigned to agents.
await agentRunner.run();
const coordinatorRunner = LoadStrikeRunner
.registerScenarios(publishOrdersScenario, observeCompletionScenario)
.withNodeType("Coordinator")
.withClusterId(clusterId)
.withAgentsCount(2)
.withCoordinatorTargetScenarios("publish-orders")
.withAgentTargetScenarios("observe-completion")
.withNatsServerUrl(natsUrl)
.withRunnerKey("rkr_your_remote_runner_key");
// The coordinator triggers only its own scenarios and routes agent work by scenario name.
await coordinatorRunner.run();
})();Coordinator and agent settings
Coordinator merges results and assigns work. Agent executes assigned scenarios and returns partial stats.
Must line up between the participating processes so they join the same run and, optionally, the same agent pool.
Coordinator expectation for how many agents should participate.
Transport used for distributed coordinator-agent communication.
Scenario filters used when different roles should own different parts of the workload.
Coordinator wait budget for cluster coordination commands and result collection.
Development-only convenience mode that removes the need for separately managed agent processes.
{
"LoadStrike": {
"NodeType": "Coordinator",
"ClusterId": "orders-cluster",
"AgentGroup": "perf-agents",
"AgentsCount": 3,
"RunnerKey": "rkr_your_remote_runner_key",
"NatsServerUrl": "nats://localhost:4222",
"TargetScenarios": "http-source,kafka-consumer",
"AgentTargetScenarios": "kafka-consumer",
"CoordinatorTargetScenarios": "http-source",
"ClusterCommandTimeoutMs": 120000,
"EnableLocalDevCluster": false
}
}