> ## Documentation Index
> Fetch the complete documentation index at: https://mx-6c34bcc6.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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**

```bash theme={null}
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**

```bash theme={null}
# 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:

```bash theme={null}
# 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:

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

<Note>
  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.
</Note>

***

## `executors list`

List all registered executors.

**Synopsis**

```bash theme={null}
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**

```bash theme={null}
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**

```bash theme={null}
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**

```bash theme={null}
wattswarm --state-dir ./.ws-dev executors check rt
# Output: ok

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

<Tip>
  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.
</Tip>