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

# Executor Registry API — Register and Manage Runtimes

> Register local and remote executor runtimes with the WattSwarm kernel, list the executor registry, and health-check individual executors by name.

Executors are the runtime processes that WattSwarm dispatches tasks to for execution. An executor exposes a simple HTTP interface that the kernel calls to run agent steps, and it must implement a `/health` endpoint that returns `200 OK` when healthy. The Executor Registry API lets you register executors by name, list all registered entries, and verify that a named executor is reachable and healthy.

***

## Executor Naming

Each executor must be registered with a unique `name`. Names are opaque strings — use descriptive slugs that reflect the agent type or deployment environment (e.g. `"local-llm"`, `"gpt-4-remote"`, `"verifier-strict"`). The name is the identifier you reference in `RunSubmitSpec` agent entries, `POST /api/task/run-real`, and the `core_agent` startup configuration.

If you register an executor with a name that already exists in the registry, the existing entry is **replaced**.

***

## Multi-Executor Patterns

You can register multiple executors to serve different agent roles:

* **Proposal executor** — a capable LLM or reasoning agent used as the primary proposer.
* **Verification executor** — a lighter-weight or rule-based agent used only for verification steps.
* **Remote executor** — an executor running on a different node, dispatched via the p2p overlay.

Reference executors by name in `RunSubmitSpec.agents[].executor` to route individual steps to specific runtimes.

***

## Remote Executor Dispatch

Set `"remote": true` and provide a `target_node_id` to register an executor that lives on a remote WattSwarm node. When the kernel dispatches a step to a remote executor, it routes the request over the p2p network to the target node. The target node must have a local executor registered under the same `base_url`.

<Note>
  Remote executor dispatch requires the background network service to be running on both nodes. Ensure both nodes are online and connected before submitting tasks that reference remote executors.
</Note>

***

## POST /api/executors/add

Registers a new executor in the local registry, or replaces an existing entry with the same name.

```bash theme={null}
POST /api/executors/add
```

<ParamField body="name" type="string" required>
  Unique name for this executor. Referenced in task and run submissions.
</ParamField>

<ParamField body="base_url" type="string" required>
  Base URL of the executor's HTTP API (e.g. `"http://127.0.0.1:8080"`). The kernel appends `/health` for health checks and executor-specific paths for task dispatch.
</ParamField>

<ParamField body="remote" type="boolean">
  Set to `true` to mark this executor as remote (hosted on another node). Defaults to `false`.
</ParamField>

<ParamField body="target_node_id" type="string">
  For remote executors, the node ID of the peer that hosts this executor. Required when `remote` is `true`.
</ParamField>

<ParamField body="scope_hint" type="string">
  Optional scope hint used for p2p routing when dispatching tasks to this executor.
</ParamField>

<ParamField body="agent_event_callback_base_url" type="string">
  Optional URL the kernel uses to push agent event callbacks to this executor. Useful when the executor needs to react to swarm events asynchronously.
</ParamField>

<ParamField body="commit_plane_endpoint" type="string">
  Optional endpoint for a separate commit-plane integration (e.g. Wattetheria sync).
</ParamField>

<ParamField body="commit_plane_token_file" type="string">
  Absolute path on the kernel host to a file containing an auth token for the commit-plane endpoint.
</ParamField>

**Example — register a local executor:**

```bash theme={null}
curl -X POST http://127.0.0.1:7788/api/executors/add \
  -H "Content-Type: application/json" \
  -d '{
    "name": "local-agent",
    "base_url": "http://127.0.0.1:8080",
    "remote": false
  }'
```

**Example — register a remote executor:**

```bash theme={null}
curl -X POST http://127.0.0.1:7788/api/executors/add \
  -H "Content-Type: application/json" \
  -d '{
    "name": "remote-verifier",
    "base_url": "http://10.0.1.5:8080",
    "remote": true,
    "target_node_id": "node-abc123def456",
    "scope_hint": "lan:cluster-a"
  }'
```

**Example response:**

```json theme={null}
{
  "ok": true
}
```

***

## GET /api/executors/list

Returns all executors currently registered in the local registry.

```bash theme={null}
GET /api/executors/list
```

**Example request:**

```bash theme={null}
curl http://127.0.0.1:7788/api/executors/list
```

**Example response:**

```json theme={null}
{
  "ok": true,
  "executors": [
    {
      "name": "local-agent",
      "base_url": "http://127.0.0.1:8080",
      "agent_event_callback_base_url": null,
      "kind": "local",
      "target_node_id": null,
      "scope_hint": null,
      "commit_plane_endpoint": null,
      "commit_plane_token_file": null
    },
    {
      "name": "remote-verifier",
      "base_url": "http://10.0.1.5:8080",
      "agent_event_callback_base_url": null,
      "kind": "remote",
      "target_node_id": "node-abc123def456",
      "scope_hint": "lan:cluster-a",
      "commit_plane_endpoint": null,
      "commit_plane_token_file": null
    }
  ]
}
```

**Response fields:**

<ResponseField name="executors" type="object[]">
  Array of executor registry entries.
</ResponseField>

<ResponseField name="executors[].name" type="string">
  Executor name.
</ResponseField>

<ResponseField name="executors[].base_url" type="string">
  HTTP base URL of the executor.
</ResponseField>

<ResponseField name="executors[].kind" type="string">
  `"local"` or `"remote"`.
</ResponseField>

<ResponseField name="executors[].target_node_id" type="string | null">
  Target node ID for remote executors.
</ResponseField>

<ResponseField name="executors[].scope_hint" type="string | null">
  P2P routing scope hint for this executor.
</ResponseField>

***

## POST /api/executors/check

Performs a live health check against the named executor by issuing a `GET` request to `<base_url>/health`. Returns `{"ok": true}` if the executor responds with a `2xx` status code.

```bash theme={null}
POST /api/executors/check
```

<ParamField body="name" type="string" required>
  Name of the registered executor to health-check.
</ParamField>

**Example request:**

```bash theme={null}
curl -X POST http://127.0.0.1:7788/api/executors/check \
  -H "Content-Type: application/json" \
  -d '{ "name": "local-agent" }'
```

**Example response (healthy):**

```json theme={null}
{
  "ok": true
}
```

**Example response (not found):**

```json theme={null}
{
  "ok": false,
  "error": "executor not found: local-agent"
}
```

<Tip>
  Run `/api/executors/check` before submitting tasks that depend on a specific executor to catch connectivity issues early, especially for remote executors that may be temporarily unreachable.
</Tip>