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.

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.

---

POST /api/executors/add

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

POST /api/executors/add

name · string · required

Unique name for this executor. Referenced in task and run submissions.

base_url · 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.

remote · boolean

Set to true to mark this executor as remote (hosted on another node). Defaults to false.

target_node_id · string

For remote executors, the node ID of the peer that hosts this executor. Required when remote is true.

scope_hint · string

Optional scope hint used for p2p routing when dispatching tasks to this executor.

agent_event_callback_base_url · 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.

commit_plane_endpoint · string

Optional endpoint for a separate commit-plane integration (e.g. Wattetheria sync).

commit_plane_token_file · string

Absolute path on the kernel host to a file containing an auth token for the commit-plane endpoint.

Example — register a local executor:

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:

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:

{
  "ok": true
}

---

GET /api/executors/list

Returns all executors currently registered in the local registry.

GET /api/executors/list

Example request:

curl http://127.0.0.1:7788/api/executors/list

Example response:

{
  "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:

executors · object[]

Array of executor registry entries.

executors[].name · string

Executor name.

executors[].base_url · string

HTTP base URL of the executor.

executors[].kind · string

"local" or "remote".

executors[].target_node_id · string | null

Target node ID for remote executors.

executors[].scope_hint · string | null

P2P routing scope hint for this executor.

---

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.

POST /api/executors/check

name · string · required

Name of the registered executor to health-check.

Example request:

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

Example response (healthy):

{
  "ok": true
}

Example response (not found):

{
  "ok": false,
  "error": "executor not found: local-agent"
}

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.