> ## 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.
# Run Your First WattSwarm Task End-to-End with the CLI
> Submit a task contract to WattSwarm, execute it through the real runtime flow, and retrieve the finalized decision — all from the CLI.
Running your first task teaches you the complete WattSwarm lifecycle: you define a task contract, submit it to the kernel, trigger the real execution chain through a registered executor, and read back the finalized decision value and evidence summary.
## Prerequisites
Before you start, make sure you have:
* The `wattswarm` binary built (`cargo build --bin wattswarm`)
* `wattswarm-runtime` built and running (`cargo run --bin wattswarm-runtime -- --listen 127.0.0.1:8787`)
* A node started with `wattswarm node up`
* The `rt` executor registered (`wattswarm executors add rt http://127.0.0.1:8787`)
If any of these steps are unfamiliar, follow the [Quick Start](/quickstart) guide first, then return here.
***
## Creating a Task Contract
A **task contract** is the boundary object between your application and the WattSwarm kernel. It is a JSON document that tells the kernel what work to do, what a valid answer looks like, how much compute budget to allocate across execution stages, and when the task expires.
Create a file called `task.json` in your working directory:
```json task.json theme={null}
{
"protocol_version": "0.1",
"task_id": "task-demo-001",
"task_type": "swarm",
"inputs": {
"prompt": "Summarize the trade-offs between consistency and availability in distributed systems."
},
"output_schema": {
"type": "object",
"required": ["answer"],
"properties": {
"answer": { "type": "string" },
"confidence": { "type": "number" }
}
},
"budget": {
"time_ms": 120000,
"max_steps": 10,
"cost_units": 100,
"explore_cost_units": 40,
"verify_cost_units": 30,
"finalize_cost_units": 10,
"reuse_verify_time_ms": 10000,
"reuse_verify_cost_units": 5,
"reuse_max_attempts": 2
},
"assignment": {
"mode": "open",
"claim": {
"lease_ms": 30000,
"max_concurrency": { "propose": 1, "verify": 1 }
}
},
"acceptance": {
"quorum_threshold": 1,
"verifier_policy": {
"policy_id": "vp.schema_only.v1",
"policy_version": "1",
"policy_hash": "sha256:placeholder",
"policy_params": {}
},
"vote": { "commit_reveal": false, "reveal_deadline_ms": 5000 },
"settlement": {
"window_ms": 86400000,
"implicit_weight": 1.0,
"implicit_diminishing_returns": { "W": 10, "K": 3 },
"bad_penalty": { "P": -5 },
"feedback": { "mode": "none", "authority_pubkey": "" }
},
"da_quorum_threshold": 1
},
"expiry_ms": 1999999999000,
"evidence_policy": {
"max_inline_evidence_bytes": 65536,
"max_inline_media_bytes": 1048576,
"inline_mime_allowlist": ["text/plain", "application/json"]
}
}
```
### Field reference
| Field | Type | Purpose |
| ------------------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `protocol_version` | string | Contract schema version. Use `"0.1"` for the current kernel. |
| `task_id` | string | Unique identifier for this task. Use any stable string — UUIDs work well. |
| `task_type` | string | Must match one of the executor's declared `task_types` from its `/capabilities` response. |
| `inputs` | object | Key-value pairs forwarded as-is to the runtime `/execute` endpoint. The `prompt` key is the standard way to pass a natural-language instruction. |
| `output_schema` | JSON Schema object | The kernel validates every candidate output against this schema before accepting it as a potential decision. |
| `budget.time_ms` | number | Wall-clock budget in milliseconds for the entire task. |
| `budget.max_steps` | number | Maximum number of execution steps allowed before the task is terminated. |
| `budget.cost_units` | number | Total cost budget across all stages combined. |
| `budget.explore_cost_units` | number | Hard cost gate for the explore stage. Execution cannot advance past this stage once the threshold is exceeded. |
| `budget.verify_cost_units` | number | Hard cost gate for the verify stage. |
| `budget.finalize_cost_units` | number | Hard cost gate for the finalize stage. |
| `budget.reuse_verify_time_ms` | number | Time budget allocated for knowledge-reuse verification attempts. |
| `budget.reuse_verify_cost_units` | number | Cost budget for knowledge-reuse verification. |
| `budget.reuse_max_attempts` | number | Maximum number of reuse verification attempts before falling back to fresh execution. |
| `assignment` | object | Claim and concurrency policy controlling how proposers and verifiers are scheduled. |
| `acceptance` | object | Quorum threshold, voting policy, verification policy binding, and settlement configuration. |
| `expiry_ms` | number | Unix epoch in milliseconds when the task expires. Set this far enough in the future that your execution chain can complete. |
| `evidence_policy.max_inline_evidence_bytes` | number | Maximum byte size for inline evidence payloads. |
| `evidence_policy.max_inline_media_bytes` | number | Maximum byte size for inline media evidence payloads. |
| `evidence_policy.inline_mime_allowlist` | string array | MIME types permitted for inline evidence (e.g. `text/plain`, `application/json`). |
The `output_schema` field is what `vp.schema_only.v1` (the default verification policy) validates against. Make sure every required field your executor returns is declared here, or verification will fail.
The `acceptance.verifier_policy.policy_hash` value must be the actual SHA-256 hash of the policy definition. When using `task run-real`, the kernel resolves this automatically. If you are submitting a raw task contract, run `wattswarm executors check ` to retrieve the correct hash for your runtime's registered policies.
***
## Submit the Task
Submit the task contract to the kernel's local event log:
```bash theme={null}
wattswarm --state-dir ./.ws-dev --store wattswarm.state task submit ./task.json
```
The kernel stores the contract and emits a `TASK_CREATED` event. At this point the task exists but has not been executed yet.
***
## Run the Task
Trigger the full execution chain using a registered executor:
```bash theme={null}
wattswarm --state-dir ./.ws-dev --store wattswarm.state \
task run-real --executor rt --profile default --task-id task-demo-001
```
`task run-real` drives the complete lifecycle sequence internally:
```text theme={null}
TASK_CREATED
→ TASK_CLAIMED (propose)
→ CANDIDATE_PROPOSED
→ TASK_CLAIMED (verify)
→ EVIDENCE_AVAILABLE
→ VERIFIER_RESULT_SUBMITTED
→ VOTE_COMMIT
→ VOTE_REVEAL
→ DECISION_COMMITTED
→ DECISION_FINALIZED
```
The command blocks until the task reaches a terminal state and then prints the result as JSON.
***
## Watch for Completion
If you want to poll the task state separately (for example, when running in compose where the worker drives execution asynchronously), use:
```bash theme={null}
wattswarm --state-dir ./.ws-dev --store wattswarm.state task watch task-demo-001
```
The output shows the current state, whether a candidate has been committed, and whether the task has been finalized:
```text theme={null}
task=task-demo-001 state=Some(Finalized) committed=Some("cand-abc123") finalized=Some("cand-abc123")
```
***
## Fetch the Decision
Once the task is finalized, retrieve the full decision record:
```bash theme={null}
wattswarm --state-dir ./.ws-dev --store wattswarm.state task decision task-demo-001
```
The decision output includes:
```json theme={null}
{
"task": "task-demo-001",
"committed": "cand-abc123",
"finalized": "cand-abc123"
}
```
### Understanding the decision output
| Field | Meaning |
| ------------------ | ------------------------------------------------------------------------------------------------------------------- |
| `committed` | The candidate ID that won the commit-reveal vote round. |
| `finalized` | The candidate ID that passed finality proof verification. Matches `committed` when no fork was detected. |
| `candidate_output` | The raw JSON object your executor returned as `candidate_output` from `/execute`. This is the actual answer. |
| `confidence` | The `confidence` value your executor included in `candidate_output` (if present). |
| `finalized_at` | Timestamp (ms) when `DECISION_FINALIZED` was emitted. |
| `evidence_summary` | Array of evidence references (inline digests and external `ArtifactRef` URIs) that supported the winning candidate. |
The full decision memory — including `quorum_result_json` and `reason_details` — is persisted to the knowledge store for future reuse. Tasks of the same `task_type` can benefit from seed bundles drawn from previous decisions.
***
## Using the UI Console
If you prefer a visual interface, all of the above steps are available through the built-in kernel console. Start the UI server:
```bash theme={null}
wattswarm --state-dir ./.ws-dev --store wattswarm.state ui --listen 127.0.0.1:7788
```
Then open **[http://127.0.0.1:7788/](http://127.0.0.1:7788/)** in your browser. The recommended operation order on the console matches the CLI workflow above:
1. **Node → UP**
2. **Executors → ADD** (name `rt`, base URL `http://127.0.0.1:8787`)
3. **Executors → CHECK**
4. **Task → SAMPLE** (optionally apply a preset)
5. **Task → SUBMIT**
6. **Task → RUN-REAL**
7. **Task → WATCH / DECISION**
The Task panel also includes a built-in `TaskContract Minimal Reference` snippet and preset helpers for common task shapes (swarm / arbitrage / security).