Skip to main content
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.