wattswarm executors — Register Runtime Executors

Reference for wattswarm executors add, list, and check: register HTTP runtime executors, inspect the registry, and verify connectivity.

The executors command group manages the local executor registry. An executor is a named pointer to an HTTP runtime service that implements the WattSwarm runtime API (/health, /capabilities, /execute, /verify). You register executors by name so you can reference them by that name when submitting task runs.

---

executors add

Register a new executor runtime in the local registry.

Synopsis

wattswarm [--state-dir <path>] [--store <name>] executors add \
  <name> \
  <base_url> \
  [--remote] \
  [--target-node <id>] \
  [--scope <scope>]

Arguments

Argument	Description
<name>	Unique name for the executor in the local registry (for example, rt, core-agent, analyst).
<base_url>	Base HTTP URL of the executor runtime (for example, http://127.0.0.1:8787 or https://agent.example.com). WattSwarm appends /health, /execute, and /verify to this URL.

Flags

Flag	Default	Description
--remote	false	Register as a remote executor. See the note below on remote dispatch.
--target-node	—	For remote executors: the node_id of the target node that owns the runtime. Used to direct dispatch via network gossip.
--scope	—	For remote executors: a scope hint (for example, region:eu-west-1) used for announcement routing across the network overlay.

Local vs remote executors

By default, WattSwarm calls the executor’s base_url directly over HTTP from the local process. This is the standard mode for all executors on the same machine or reachable over a private network.

Pass --remote to register a remote executor. Remote executors are dispatched via WattSwarm’s network gossip layer instead of direct HTTP. The kernel sends an ExecutorDispatchRequest event over the configured scope and routes it to the target node. Use --target-node to direct the dispatch to a specific node and --scope to hint the routing scope. This lets you register executor runtimes that run on other nodes in the swarm without requiring direct HTTP reachability.

Description

Adds the executor to the local executor registry file in the state directory. If an executor with the same name already exists, it is replaced. The registry is stored locally per state directory.

Examples

# Register a local runtime
wattswarm --state-dir ./.ws-dev executors add rt http://127.0.0.1:8787

# Register a remote cloud runtime
wattswarm --state-dir ./.ws-dev executors add cloud-agent https://api.example.com/runtime

# Register a remote executor dispatched via network gossip
wattswarm --state-dir ./.ws-dev executors add eu-agent https://eu.agent.example.com \
  --remote \
  --target-node node-eu-001 \
  --scope region:eu-west-1

Multi-executor registration example

You can register as many executors as you need and reference them by name per task or per run step:

# Register three separate runtimes
wattswarm --state-dir ./.ws-dev executors add screener     http://127.0.0.1:8787
wattswarm --state-dir ./.ws-dev executors add reviewer     http://127.0.0.1:8788
wattswarm --state-dir ./.ws-dev executors add summariser   https://summariser.example.com

# Select executor per task run
wattswarm --state-dir ./.ws-dev task run-real \
  --executor screener \
  --profile default \
  --task-id task-screen-001

wattswarm --state-dir ./.ws-dev task run-real \
  --executor reviewer \
  --profile default \
  --task-id task-review-001

In a RunSubmitSpec you specify the executor per agent step:

{
  "agents": [
    { "agent_id": "a1", "executor": "screener",   "task_type": "swarm", ... },
    { "agent_id": "a2", "executor": "reviewer",   "task_type": "swarm", ... },
    { "agent_id": "a3", "executor": "summariser",  "task_type": "swarm", ... }
  ]
}

Every executor must expose the four required endpoints: /health, /capabilities, /execute, and /verify. One executor can be a single model endpoint or a gateway that fans out to many internal agents — the kernel interface is the same either way.

---

executors list

List all registered executors.

Synopsis

wattswarm [--state-dir <path>] [--store <name>] executors list

Description

Reads the local executor registry and prints one line per executor showing the name, base URL, kind (local or remote), and — for remote executors — the target node ID and scope hint.

Example

wattswarm --state-dir ./.ws-dev executors list
# Output:
# rt            http://127.0.0.1:8787   [local]
# cloud-agent   https://api.example.com [local]
# eu-agent      https://eu.agent.example.com [remote target=node-eu-001 scope=region:eu-west-1]

---

executors check

Verify that a registered executor is reachable and healthy.

Synopsis

wattswarm [--state-dir <path>] [--store <name>] executors check <name>

Arguments

Argument	Description
<name>	The executor name to check.

Description

Looks up the executor’s base_url from the registry and sends a GET /health request. Prints ok if the runtime responds with a successful HTTP status. Returns a non-zero exit code on connection failure or non-2xx response.

Example

wattswarm --state-dir ./.ws-dev executors check rt
# Output: ok

wattswarm --state-dir ./.ws-dev executors check cloud-agent
# Output: ok

Always run executors check before calling task run-real or starting the run worker. A runtime that is registered but unreachable will cause task execution to fail immediately.