WattSwarm Architecture: Kernel, Nodes, and Executors

Understand how WattSwarm’s kernel, executor runtimes, PostgreSQL, and P2P network fit together to coordinate multi-agent task orchestration.

WattSwarm is built around a clean separation of concerns: the kernel coordinates, executors do the work, and a peer-to-peer network keeps every node in sync. Understanding how these three layers relate helps you design integrations that stay durable across deployments, from a single developer machine all the way to a wide-area multi-node swarm.

How the pieces relate

When you run WattSwarm, you start one or more nodes. Each node owns a local PostgreSQL database and an artifact store. The node publishes and receives signed events over an Iroh-backed P2P network. Your executor — an HTTP service you build and register — receives task requests from the kernel and returns candidates and verification results.

┌──────────────────────────────────────────────────┐
│                  WattSwarm Node                  │
│                                                  │
│  ┌──────────────┐   ┌────────────────────────┐  │
│  │  node-core   │   │  Structured Event Log  │  │
│  │  (kernel)    │──▶│  (append-only, SEL)    │  │
│  └──────┬───────┘   └────────────────────────┘  │
│         │                                        │
│  ┌──────▼───────┐   ┌────────────────────────┐  │
│  │  PostgreSQL  │   │    Artifact Store       │  │
│  │  (local SoT) │   │  (filesystem / blobs)   │  │
│  └──────────────┘   └────────────────────────┘  │
│                                                  │
│  ┌──────────────────────────────────────────┐   │
│  │        Iroh P2P Bridge                   │   │
│  │  gossip ▸ backfill ▸ anti-entropy        │   │
│  └──────────────────────────────────────────┘   │
└──────────────────────┬───────────────────────────┘
                       │ HTTP
               ┌───────▼────────┐
               │   Executor     │
               │  /health       │
               │  /capabilities │
               │  /execute      │
               │  /verify       │
               └────────────────┘

The P2P network connects multiple nodes; each node applies received events into its own local store rather than sharing a database.

The three-layer model

WattSwarm organises itself into three logical layers that work in concert.

Layer	What it does
Kernel (coordination)	Manages task lifecycle, evidence, voting, finality, knowledge, and reputation. Lives entirely inside the node process.
Executor (agent work)	Executes tasks and verifies candidate outputs. An HTTP service you implement; the kernel calls it over a registered base URL.
Network (sync)	Propagates signed events between nodes using Iroh gossip, backfill, and anti-entropy. Keeps every node eventually consistent with the swarm.

What a node is

A node is a running WattSwarm process with its own persistent identity and local storage. When you start a node for the first time, WattSwarm generates an Ed25519 keypair and derives a node_id from the public key. That identity signs every event the node authors, so the rest of the network can verify authorship without a central authority.

Each node maintains:

• A local PostgreSQL database — the node’s source of truth for the SEL, task projections, leases, votes, reputation, knowledge, and run-queue state.
• A local artifact store — a filesystem layout for candidate outputs, evidence blobs, checkpoints, snapshots, and event batch archives.
• An Iroh endpoint — the QUIC-based P2P transport used for gossip notifications, control-stream backfill, and direct data fetch.

Two nodes that share the same node_seed.hex file will produce a duplicate-identity conflict on bootstrap. Each node must have its own unique seed.

What an executor is

An executor is an HTTP service you implement and register with the kernel. The kernel sends tasks to it and reads back candidate outputs and verification decisions. Every executor must expose four endpoints:

Endpoint	Purpose
GET /health	Liveness check; the kernel calls this before routing work.
GET /capabilities	Declares what task types the executor handles.
POST /execute	Accepts a task contract and returns a candidate output.
POST /verify	Accepts a candidate and returns a verification result.

You register an executor by name and base URL:

wattswarm --state-dir ./.ws-dev executors add rt http://127.0.0.1:8787

One executor can be a single model endpoint or a gateway that fans out internally to many agents. The kernel treats the base URL as the boundary; what happens behind it is up to you.

Local, LAN, and network mode

WattSwarm supports three deployment modes that determine how the node discovers peers and joins a network.

Mode	Description
local	Single self-contained node. No P2P connections are opened. The network is auto-bootstrapped as local:<node_id> with a default org of local:<node_id>:bootstrap. Ideal for development and single-machine orchestration.
lan	Connects to peers on the local network. mDNS/UDP announce is available as a discovery aid. Nodes exchange Iroh contact material and sync over QUIC.
network / wan	Joins a shared network by connecting to one or more bootstrap contacts. The joining node fetches a signed NetworkBootstrapBundle to obtain network topology and protocol parameters.

Set WATTSWARM_P2P_ENABLED=false to force local-only mode regardless of the configured node mode.

The Structured Event Log (SEL)

Every state change in WattSwarm is recorded as a signed event appended to the Structured Event Log. The SEL is:

• Append-only — events are never edited or deleted. Invalid events are invalidated by a subsequent EventRevoked or NodePenalized event.
• Replayable — you can replay the full event stream from the beginning to reconstruct any projection, task state, or reputation score.
• The source of truth — if a projection table and the SEL disagree, the SEL wins.

Each event carries a protocol_version, an author_node_id, an epoch, a created_at timestamp, and an event_kind. The kernel uses these fields to validate ordering, detect duplicates, and enforce finality rules.

PostgreSQL as node-local source of truth

Each node stores its SEL, projections, leases, votes, knowledge, reputation, and run-queue state in a local PostgreSQL database. This database is never replicated to other nodes.

Nodes do not share a database. Copying a PostgreSQL database between nodes is not a supported sync method. Use the P2P event pipeline instead.

The default schema is public. Override it with WATTSWARM_PG_SCHEMA=<schema> if you need multiple isolated WattSwarm instances on the same PostgreSQL server.

How nodes sync

Nodes stay consistent by exchanging signed events, not database rows. The sync flow works like this:

1. A node authors a local event and writes it to its SEL.
2. The Iroh bridge publishes that event as a gossip notification on the appropriate scope topic.
3. Connected peers that subscribe to that topic receive the notification.
4. Each peer ingests the event into its own local event log and rebuilds the affected projections.
5. Peers that were offline or missed messages request missing event pages through backfill over Iroh control streams.
6. Anti-entropy runs periodically, so gaps from partitions or late joins are repaired automatically.

Large content bodies (candidate outputs, evidence blobs, topic message bodies) travel separately over Iroh’s BLAKE3-addressed transfer layer. Control-plane events carry a content reference; the receiving node fetches the body on demand.

Kernel crate boundary

The following crates form the kernel boundary. Everything inside this boundary is coordination logic; everything outside is transport, storage, or UI.

Crate	Role
node-core	Core node process: task lifecycle, evidence, voting, finality, knowledge, and SEL ingestion.
storage-core	PostgreSQL schema, projections, and query helpers.
policy-engine	Built-in verification policies (vp.schema_only.v1, vp.schema_thresholds.v1, vp.crosscheck.v1).
protocol	Canonical event types, task contract types, and payload definitions.
crypto	Ed25519 identity, event signing, candidate hashing, and vote commit hashing.
runtime-client	HTTP client the kernel uses to call executor /execute and /verify endpoints.

You can run the kernel fully without the UI. Remove or ignore ui/* and drive everything through the CLI or the kernel’s HTTP API.