wattswarm
wattetheria/wattswarm
Swarm coordination kernel for agent networks. Powers wattetheria, and works standalone.
Instalação
npx convez-ai wattetheria/wattswarm1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
Wattswarm
Wattswarm is an open-source coordination kernel for agent networks. It provides the shared runtime layer for multi-agent task execution, verification, voting, consensus, event replay, and node-to-node synchronization.
You bring one or more agent runtimes. Wattswarm handles the kernel concerns: task lifecycle, executor registry, PostgreSQL-backed state, run queue scheduling, auditable events, P2P propagation, and finalized decisions.
Documentation
The full product and operator documentation lives in the docs site:
- Documentation home
- Quickstart
- Docker quickstart
- Architecture
- Task lifecycle
- Nodes, networks, and orgs
- Multi-agent runs
- Runtime executor API
- CLI reference
- Environment variables
- Diagnostics
This README is intentionally short. Detailed command recipes, API payloads, topology guides, and troubleshooting live in the docs site.
What It Does
- Coordinates task execution across one or more agent runtimes.
- Persists a structured append-only event log and replayable projections.
- Uses PostgreSQL for node-local state and the multi-agent run queue.
- Stores large or referenced payloads through node-local artifact/object storage.
- Supports claim, execute, verify, vote, commit, finalize, retry, and expiry flows.
- Provides commit-reveal voting, quorum rules, aggregation policies, and memory reuse.
- Connects nodes over an Iroh-first P2P layer for scoped event, message, and artifact sync.
- Includes a CLI, HTTP API, reference runtime, worker loop, and built-in UI console.
Quick Start
The fastest way to run the full local stack is Docker Compose:
docker compose up -d --build
This starts PostgreSQL, the Wattswarm kernel UI, the reference runtime, and a worker process.
Default local entry points:
- Kernel console:
http://127.0.0.1:7788/ - Swarm dashboard:
http://127.0.0.1:7788/swarm - Runtime HTTP:
http://127.0.0.1:8787 - PostgreSQL:
127.0.0.1:55432
For a guided first task, use the Quickstart or Docker quickstart.
Core Boundary
Wattswarm is a kernel-first project.
- Kernel/core:
crates/node-core,crates/storage-core,crates/policy-engine,crates/protocol,crates/crypto,crates/runtime-client - Network and transport:
crates/network-discovery,crates/network-p2p,crates/network-substrate,crates/network-transport-core,crates/network-transport-iroh - Artifact storage:
crates/artifact-store - Network-to-kernel bridge:
crates/control-plane/src/network_bridge/mod.rs - CLI and HTTP/UI app:
apps/Wattswarm - Reference runtime:
apps/Wattswarm-runtime - UI assets:
ui/*
The UI is optional. The kernel can be operated through the CLI and HTTP APIs.
Architecture Snapshot
These diagrams show the current high-level architecture and propagation model. More detailed explanation lives in the Architecture and Nodes, networks, and orgs docs.
flowchart TD
A["Node joins network"] --> B["Load bootstrap/contact material<br/>PostgreSQL + startup config"]
B --> C["Iroh endpoint online<br/>QUIC direct / relay urls where available"]
C --> D["Node subscribes to configured scopes"]
D --> E["Local topic set is derived<br/>namespace + scope + kind"]
C --> C1["Iroh address lookup<br/>direct addrs + relay urls"]
F["Local task/event/summary is produced"] --> G["Network bridge resolves scope"]
G --> H["Publish to topic over gossip"]
H --> I["Connected peers that subscribed to that topic receive it"]
I --> J["Event: ingest into local event log"]
I --> K["Summary: import supported summary payloads"]
J --> L["Projection/state rebuild on local node"]
K --> L
M["Peer missed messages or joined late"] --> N["Backfill request to connected peer"]
N --> O["Backfill response with missing events"]
O --> P["Local node applies missing events"]
P --> L
flowchart LR
U["Task / Topic Source"] --> K["Single Local Wattswarm Node"]
subgraph L["Local Multi-Agent Swarm"]
A1["Agent A"]
A2["Agent B"]
A3["Agent C"]
A4["Agent D"]
end
subgraph C["Wattswarm Local Kernel"]
K1["Task lifecycle
create -> claim -> execute -> verify -> vote -> commit -> finalize"]
K2["Evidence + policy checks"]
K3["Aggregation + quorum + re-explore"]
K4["Local swarm memory
decision memory / reuse / reputation / task outcomes"]
K5["Local PostgreSQL
event log / projections / summaries / metrics"]
end
K --> A1
K --> A2
K --> A3
K --> A4
A1 --> K1
A2 --> K1
A3 --> K1
A4 --> K1
K1 --> K2
K2 --> K3
K3 --> O["Local emergent outcome
better decision / less duplicate work / adaptive retry"]
O --> K4
K4 --> K1
K1 --> K5
K2 --> K5
K3 --> K5
K4 --> K5
flowchart LR
T["Task stream over time"] --> M["Local multi-agent node
Agent A / Agent B / Agent C / Agent D"]
M --> K["Wattswarm local kernel
execute / verify / vote / aggregate / finalize"]
K --> O["Per-task outcomes
decisions / evidence / failures / retries / scores"]
O --> P["Local persistence
event log / projections / summaries / metrics"]
P --> H["Historical state
decision memory / reputation / task outcomes / reuse blacklist"]
H --> A["Adaptive future behavior
better reuse / less duplicate work / smarter re-explore / trust weighting"]
A --> M
A --> T
H --> E["Local emergence patterns
specialization / faster convergence / more stable decisions"]
flowchart LR
U["Task / Topic Source"] --> A["Node A
Coordinator node + local Wattswarm store"]
subgraph N["P2P Network Overlay"]
N1["LAN / WAN
Iroh contact material"]
N2["Iroh endpoint
QUIC direct + relay urls"]
N3["Sync + Repair
gossip / backfill / anti-entropy"]
N4["Scoped dissemination
global / region / node / group"]
end
N1 --> N3
N2 --> N3
N4 --> N3
A --> A1["Coordinator loop
publish task or topic / watch shared facts / decide next round or close"]
A1 --> E["TaskAnnounced / topic message / checkpoint publication"]
N3 --> B["Node B
Executor B + local Wattswarm store"]
N3 --> C["Node C
Executor C + local Wattswarm store"]
N3 --> D["Node D
Executor D + local Wattswarm store"]
B --> B1["Local executor loop
execute / verify / vote / publish facts"]
C --> C1["Local executor loop
execute / verify / vote / publish facts"]
D --> D1["Local executor loop
execute / verify / vote / publish facts"]
B1 --> F["Shared facts
execution set / candidates / verifier results / vote reveals / checkpoints"]
C1 --> F
D1 --> F
F --> N3
N3 --> A1
A1 --> O["Coordinator decision
close round / re-explore / next round / fallback finalize"]
O --> S["Shared swarm memory
decision memory / reputation / task outcome summaries"]
S --> R["Future tasks on any node
seed bundle / reuse / better routing / better decisions"]
R --> A
R --> B
R --> C
R --> D
flowchart LR
T["Task stream over time"] --> I["Coordinator node
starts task or topic / stores policy / opens round 1"]
subgraph G["Agent-node swarm"]
B["Executor node B"]
C["Executor node C"]
D["Executor node D"]
end
I --> X["Round coordination
select participants / publish work / wait for shared facts"]
B --> X
C --> X
D --> X
X --> N["Shared fact exchange
events / candidates / votes / checkpoints / backfill / anti-entropy"]
N --> H["Coordinator evaluation
policy check / round close check / max-round check / fallback check"]
H --> R["Round result
close now / start next round / finalize with fallback"]
R --> M["Persistent swarm memory
decision memory / reputation / task outcome summaries"]
M --> P["Adaptive future behavior
better participant selection / stronger scope fit / reduced duplicate exploration / more stable convergence"]
P --> B
P --> C
P --> D
P --> T
M --> E["Emergence patterns over time
specialization / faster closure / more stable network-level behavior"]
Storage Model
Node state is intentionally local.
- PostgreSQL stores the SEL event log, projections, task state, run queue, executor registry, knowledge, reputation, metrics, settlement state, and local dashboard queries.
- The filesystem artifact store holds references, message bodies, task outputs, evidence blobs, checkpoints, snapshots, event batches, and availability manifests.
- Nodes do not replicate PostgreSQL databases. They exchange signed events, summaries, checkpoint metadata, and artifact references, then re-apply that state locally.
CLI Overview
The CLI binary is Wattswarm.
Common command groups:
node: start, stop, inspect, and configure a nodepeers: inspect known peerslog: inspect, replay, and verify the structured event logexecutors: register and health-check runtime executorstask: submit task contracts and read decisionsrun: operate the PostgreSQL multi-agent run queueknowledge: export decision memory bundlesgovernance: manage membership, revocation, and penalty eventsui: start the built-in HTTP UI console
See the CLI reference for full syntax and examples.
Runtime Executor Contract
Executors are HTTP services that implement the runtime API expected by the kernel:
GET /healthGET /capabilitiesPOST /executePOST /verify
The reference runtime lives in apps/Wattswarm-runtime. Custom runtimes should
follow the Runtime executor API.
Multi-Agent Run Queue
The run queue uses PostgreSQL tables to coordinate multi-agent runs:
run submitcreates a run and its steps.run kickoffmoves pending work into the queue.run workerleases and executes queued steps.run watch,run events, andrun resultinspect progress and output.run cancelandrun retrycontrol terminal or failed runs.
The queue is DB-native and does not require RabbitMQ, Kafka, or Redis for the current scope. See the multi-agent runs guide and run CLI reference.
Development
Prerequisites:
- Rust toolchain
- Docker, for the full local stack
- PostgreSQL, if running without Docker Compose
Useful local checks:
cargo fmt --all
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
Report helpers:
make test
make test-report
Report output is written under target/test-report/.
Repository Layout
apps/
Wattswarm/ CLI, HTTP API, UI server
Wattswarm-runtime/ Reference executor runtime
crates/
artifact-store/ Node-local artifact/object storage
control-plane/ Kernel orchestration and network bridge
crypto/ Node identity and signatures
network-* Discovery, P2P, substrate, and Iroh transport crates
node-core/ Core task lifecycle logic
policy-engine/ Verification policy registry and evaluation
protocol/ Shared protocol types and envelopes
run-queue/ PostgreSQL multi-agent run queue
runtime-client/ Executor HTTP client
storage-core/ PostgreSQL storage and projections
docs/ Project design notes and implementation plans
scripts/ Local automation helpers
ui/ Built-in console and swarm dashboard assets
Star History
License
See LICENSING.md.