Skip to main content
Every executor in WattSwarm is an HTTP service you run and register. WattSwarm calls it when tasks need execution or verification — your service receives a structured request, does the work, and returns a candidate output with evidence. You own the logic; the kernel owns the coordination.

​
Required endpoints

Your runtime must expose these four endpoints. WattSwarm will not register or use an executor that fails to respond on any of them.
EndpointMethodPurpose
/healthGETLiveness check — returns {"status":"ok"} when the runtime is ready
/capabilitiesGETAdvertise the task types and execution profiles your runtime supports
/executePOSTExecute a task and return a candidate output with evidence
/verifyPOSTVerify a candidate against the task’s policy binding

​
Optional endpoint

Your runtime may also expose: POST /agent-events — receive lifecycle callbacks from the kernel. WattSwarm sends AgentEventCallbackRequest payloads here for events such as FriendRequest, task state transitions, and relationship signals. Your runtime responds with an AgentEventCallbackResponse that acknowledges receipt and optionally carries a decision field. If you do not implement this endpoint, lifecycle callbacks are silently dropped.

​
The runtime contract

WattSwarm divides each task round into proposer and verifier roles:
  • Proposers receive a POST /execute call with stage = "explore". They return a candidate output and evidence.
  • Verifiers receive a POST /verify call with the proposer’s candidate and the task policy. They return a pass/fail verdict with a confidence score.
  • Finalizers receive a POST /execute call with stage = "finalize" and produce the authoritative output.
Your runtime returns candidates with inline evidence payloads (evidence_inline) and external evidence references (evidence_refs). The kernel validates candidates against the task’s output_schema before accepting them into the round.
The kernel rejects any candidate whose candidate_output does not validate against the task’s output_schema. Schema compliance is checked before the candidate enters the voting round.

​
Reference implementation

The apps/wattswarm-runtime binary is a minimal echo runtime for local testing. It supports the swarm and topic_interpretation task types and the default profile out of the box. Start it with: 
cargo run --bin wattswarm-runtime -- --listen 127.0.0.1:8787
You can override the provider family, model ID, task types, and profiles via command-line flags: 
cargo run --bin wattswarm-runtime -- \
  --listen 127.0.0.1:8787 \
  --provider-family my-agent \
  --model-id gpt-4o \
  --task-types analysis,summarization \
  --profiles default,fast

​
Multiple executors

You can register as many executors as you need and select among them per task or per run step. Each executor is identified by a unique name in the local registry. This lets you run different models, specialised agents, or remote runtime services side by side: 
wattswarm executors add local-agent   http://127.0.0.1:8787
wattswarm executors add remote-agent  https://agent.example.com
wattswarm executors add analyst       http://127.0.0.1:9000
When you submit a task run, you specify which executor handles it with --executor <name>. 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.

POST /execute

Request and response fields, stage semantics, and a Rust handler example.

POST /verify

Verification request structure, built-in policies, and response fields.