> ## 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 Quickstart: Build and Run Your First Swarm Task
> Submit your first task to WattSwarm in minutes: start the reference runtime, bring a node up, register an executor, and read a finalized decision.
WattSwarm coordinates multi-agent task execution through a full lifecycle — create, claim, execute, verify, vote, commit, and finalize — all driven from the CLI against a local PostgreSQL store. This guide walks you through the minimum setup to run a real end-to-end task flow on your machine: one kernel process, one reference runtime, and a task contract JSON file.
## Prerequisites
* **Rust toolchain** — stable channel, installed via [rustup](https://rustup.rs). The workspace uses a standard `cargo` build.
* **PostgreSQL** — WattSwarm uses PostgreSQL as its source of truth for the event log, projections, leases, votes, and decision memory. In local development the default connection is `postgres://postgres:postgres@127.0.0.1:55432/wattswarm`. If you run Postgres directly (not via Docker), adjust the `WATTSWARM_PG_URL` environment variable to match your instance.
* **The WattSwarm repo** — clone it and `cd` in:
```bash theme={null}
git clone https://github.com/wattetheria/wattswarm.git
cd wattswarm
```
If you want PostgreSQL managed for you with zero configuration, the [Docker Quickstart](/docker-quickstart) spins up a full stack (PostgreSQL on port `55432`, kernel, runtime, and worker) with a single `docker compose up` command.
## Steps
Compile all workspace binaries in release mode. This produces `wattswarm`, `wattswarm-runtime`, and related tools under `target/release/`.
```bash theme={null}
cargo build --release
```
You can skip the build step and use `cargo run --bin wattswarm -- ` throughout this guide if you prefer incremental dev builds. Both approaches produce identical behavior.
Open a dedicated terminal and start `wattswarm-runtime`. This binary exposes the four HTTP endpoints the kernel calls during task execution: `/health`, `/capabilities`, `/execute`, and `/verify`.
```bash theme={null}
cargo run --bin wattswarm-runtime -- --listen 127.0.0.1:8787
```
You should see:
```text theme={null}
wattswarm-runtime listening on 127.0.0.1:8787
```
Leave this terminal running for the rest of the guide.
The reference runtime echoes your task inputs back as candidate output — it is **not** a real AI agent. Its purpose is to give you a working end-to-end flow so you can observe the full kernel lifecycle (propose → verify → vote → finalize) before wiring up a real model endpoint. See [Building a Runtime](/guides/building-a-runtime) to replace it with your own executor.
In a second terminal, initialize the node. The `--state-dir` flag sets the directory where WattSwarm stores `startup_config.json`, `node_state.json`, and `node_seed.hex`. The `--store` flag is a logical identifier for the local PostgreSQL store binding.
```bash theme={null}
cargo run --bin wattswarm -- \
--state-dir ./.ws-dev \
--store wattswarm.state \
node up
```
Expected output:
```text theme={null}
node is up
```
WattSwarm auto-bootstraps a `local:` network and org on first start, so no prior network configuration is needed for local development.
Tell the kernel where to find the reference runtime you started in Step 2. The name `rt` is used later to select this executor when running a task.
```bash theme={null}
cargo run --bin wattswarm -- \
--state-dir ./.ws-dev \
--store wattswarm.state \
executors add rt http://127.0.0.1:8787
```
Expected output:
```text theme={null}
executor added: rt (local)
```
You can register as many executors as you like. Each is identified by name and base URL and stored in the kernel's local executor registry. To verify the registration is reachable, run:
```bash theme={null}
cargo run --bin wattswarm -- \
--state-dir ./.ws-dev \
--store wattswarm.state \
executors check rt
```
Save the following JSON as `task.json` in your working directory. This is the boundary object between your application and the WattSwarm kernel — it describes what the task is, what a valid response looks like, and the stage budgets that gate execution.
```json task.json theme={null}
{
"protocol_version": "v0.1",
"task_id": "task-1",
"task_type": "swarm",
"inputs": {
"prompt": "Summarize the benefits of swarm coordination for multi-agent systems."
},
"output_schema": {
"type": "object",
"required": ["answer"],
"properties": {
"answer": { "type": "string" },
"confidence": { "type": "number" },
"check_summary": { "type": "string" }
}
},
"budget": {
"time_ms": 30000,
"max_steps": 10,
"cost_units": 1000,
"mode": "LIFETIME",
"explore_cost_units": 350,
"verify_cost_units": 450,
"finalize_cost_units": 200,
"reuse_verify_time_ms": 20000,
"reuse_verify_cost_units": 200,
"reuse_max_attempts": 1
},
"assignment": {
"mode": "CLAIM",
"claim": {
"lease_ms": 5000,
"max_concurrency": { "propose": 1, "verify": 1 }
},
"explore": {
"max_proposers": 1,
"topk": 3,
"stop": { "no_new_evidence_rounds": 3 }
},
"verify": { "max_verifiers": 1 },
"finalize": { "max_finalizers": 1 }
},
"acceptance": {
"quorum_threshold": 1,
"verifier_policy": {
"policy_id": "vp.schema_only.v1",
"policy_version": "1",
"policy_hash": "",
"policy_params": {}
},
"vote": {
"commit_reveal": true,
"reveal_deadline_ms": 10000
},
"settlement": {
"window_ms": 86400000,
"implicit_weight": 0.1,
"implicit_diminishing_returns": { "W": 10, "K": 50 },
"bad_penalty": { "P": 3 },
"feedback": {
"mode": "CAPABILITY",
"authority_pubkey": "ed25519:placeholder"
}
},
"da_quorum_threshold": 1
},
"task_mode": "ONE_SHOT",
"expiry_ms": 9999999999999,
"evidence_policy": {
"max_inline_evidence_bytes": 65536,
"max_inline_media_bytes": 0,
"inline_mime_allowlist": [
"application/json",
"text/plain",
"text/markdown",
"text/csv"
],
"max_snippet_bytes": 8192,
"max_snippet_tokens": 2048
}
}
```
The `expiry_ms` field is an absolute Unix timestamp in milliseconds. Set it far enough in the future that the task does not expire during your test. The `budget.explore_cost_units`, `budget.verify_cost_units`, and `budget.finalize_cost_units` fields act as hard gates — execution is blocked if a stage would exceed its allocation. The `evidence_policy` block controls how much inline evidence the runtime may attach per candidate; the defaults shown above are suitable for local development. The `acceptance.settlement` block is required but has no effect on single-node local runs — leave the placeholder values as-is.
Then submit the contract to the kernel:
```bash theme={null}
cargo run --bin wattswarm -- \
--state-dir ./.ws-dev \
--store wattswarm.state \
task submit ./task.json
```
Expected output:
```text theme={null}
submitted task-1
```
Trigger the complete kernel execution chain. This command drives the task through every lifecycle stage: `TASK_CREATED → TASK_CLAIMED(propose) → CANDIDATE_PROPOSED → TASK_CLAIMED(verify) → EVIDENCE_AVAILABLE → VERIFIER_RESULT_SUBMITTED → VOTE_COMMIT → VOTE_REVEAL → DECISION_COMMITTED → DECISION_FINALIZED`.
```bash theme={null}
cargo run --bin wattswarm -- \
--state-dir ./.ws-dev \
--store wattswarm.state \
task run-real \
--executor rt \
--profile default \
--task-id task-1
```
The `--executor` flag names the registered executor to use. The `--profile` flag maps to the profile declared in the runtime's capabilities (`default` is always available on the reference runtime). The command blocks until the task reaches a terminal state and then prints a JSON result summary.
Once the task is finalized, read the committed and finalized candidate IDs from the kernel's decision memory:
```bash theme={null}
cargo run --bin wattswarm -- \
--state-dir ./.ws-dev \
--store wattswarm.state \
task decision task-1
```
You will see output similar to:
```text theme={null}
task=task-1 committed=Some("cand-") finalized=Some("cand-")
```
Both `committed` and `finalized` fields being populated confirms the task completed the full consensus cycle. The candidate ID links back to the output the reference runtime produced during the `execute` call — in this case `"default::Summarize the benefits of swarm coordination for multi-agent systems."` echoed through the `answer` field.
## What to expect
After `task run-real` completes, the structured result printed to stdout looks like this:
```json theme={null}
{
"task_id": "task-1",
"status": "FINALIZED",
"committed_candidate_id": "cand-a3f8...",
"finalized_candidate_id": "cand-a3f8...",
"candidate_output": {
"answer": "default::Summarize the benefits of swarm coordination for multi-agent systems.",
"confidence": 0.93,
"check_summary": "stage=explore attempt=attempt-1"
}
}
```
The `answer` value reflects the reference runtime's echo behavior: it concatenates your `--profile` value with the `inputs.prompt` string. When you replace the reference runtime with a real agent executor, this field will contain your model's actual response.
## Next steps
Replace the echo executor with a real model endpoint by implementing `/health`, `/capabilities`, `/execute`, and `/verify`.
Run the full stack — PostgreSQL, kernel, runtime, and worker — with a single `docker compose up` command.
Orchestrate multiple agents in parallel using the run queue, with quorum and aggregation policies applied across all results.
Connect nodes over Iroh QUIC, gossip events, and sync decisions across a p2p swarm.