The node command group controls the lifecycle of a WattSwarm node: bringing it online, taking it offline, checking its status, and managing the network configuration it uses to connect to peers. You must call node up before submitting tasks or running executor flows.
node up
Bring the node online and initialise the Iroh-backed P2P runtime.
Synopsis
wattswarm [--state-dir <path>] [--store <name>] node up [--mode local|lan|wan]
| Flag | Default | Description |
|---|
--mode | local | Network mode. local — single-machine, no P2P. lan — LAN peer discovery via mDNS. wan — WAN mode using configured bootstrap contacts and Iroh QUIC. |
node up opens the node state directory, initialises the local PostgreSQL store, and starts the Iroh-backed network bridge when P2P is enabled. It writes a node_state.json file marking the node as running. The node identity is derived from node_seed.hex in the state directory — if the file does not exist, WattSwarm creates one automatically on first startup.
Examples
# Start in local-only mode (no P2P)
wattswarm --state-dir ./.ws-dev node up
# Start in LAN mode
wattswarm --state-dir ./.ws-dev node up --mode lan
# Start in WAN mode (requires bootstrap contacts to be configured)
wattswarm --state-dir ./.ws-dev node up --mode wan
node down
Take the node offline.
Synopsis
wattswarm [--state-dir <path>] [--store <name>] node down
node down updates node_state.json to mark the node as stopped. It does not delete any stored state, event log entries, or projections. You can bring the node back online with node up at any time.
Example
wattswarm --state-dir ./.ws-dev node down
node status
Show the current node status and peer protocol version distribution.
Synopsis
wattswarm [--state-dir <path>] [--store <name>] node status
node_state.json and the local PostgreSQL store, then prints a JSON object with the node ID, running state, network mode, local protocol version, and a distribution map of connected peer protocol versions.
Example
wattswarm --state-dir ./.ws-dev node status
{
"running": true,
"mode": "local",
"local_protocol_version": "1",
"peer_protocol_distribution": {}
}
Print the Iroh contact string for this node so other nodes can bootstrap from it.
Synopsis
wattswarm [--state-dir <path>] [--store <name>] node export-contact [--json]
| Flag | Default | Description |
|---|
--json | false | Output contact material as a JSON object instead of the short contact string. Intended for internal debugging only. |
<iroh-node-id>@<host:port> contact string for this node. Share this string with operators of joining nodes so they can add it as a bootstrap contact. The default text format is the canonical format accepted by node add-bootstrap-contact.
Examples
# Export the short contact string (share with joining nodes)
wattswarm --state-dir ./.ws-genesis node export-contact
# Output: aef3b2...@203.0.113.10:4001
# Export as JSON (debugging only)
wattswarm --state-dir ./.ws-genesis node export-contact --json
Add a bootstrap contact string to this node’s startup configuration.
Synopsis
wattswarm [--state-dir <path>] [--store <name>] node add-bootstrap-contact <contact> [--mode wan]
| Argument | Description |
|---|
<contact> | The Iroh contact string exported by the genesis or bootstrap node (<iroh-node-id>@<host:port>). |
| Flag | Default | Description |
|---|
--mode | wan | Network mode to use when this contact is active. Must be lan or wan. |
startup_config.json in the state directory. The node uses these contacts on next startup to establish its initial Iroh connection and trigger bootstrap sync of network params and org registry from the remote node.
Bootstrap contacts require lan or wan mode. Passing --mode local returns an error.
wattswarm --state-dir ./.ws-joining node add-bootstrap-contact \
'aef3b2...@203.0.113.10:4001' \
--mode wan
List the bootstrap contacts configured in startup_config.json.
Synopsis
wattswarm [--state-dir <path>] [--store <name>] node bootstrap-contacts
startup_config.json from the state directory and prints each configured bootstrap contact string, one per line.
Example
wattswarm --state-dir ./.ws-joining node bootstrap-contacts
# Output:
# aef3b2...@203.0.113.10:4001
node sign-network-params
Sign and store network protocol parameters (genesis node only).
Synopsis
wattswarm [--state-dir <path>] [--store <name>] node sign-network-params \
--network-id <id> \
[--params-file <path>] \
[--pg-url <url>]
| Flag | Description |
|---|
--network-id | The network identifier to sign params for (required). |
--params-file | Path to a NetworkProtocolParams or signed envelope JSON file. Defaults to the built-in default params. |
--pg-url | Override the PostgreSQL connection string for this call. |
wattswarm --state-dir ./.ws-genesis node sign-network-params \
--network-id mainnet-alpha-1 \
--params-file ./network-params.json
{
"network_id": "mainnet-alpha-1",
"version": 1,
"prev_hash": null,
"params_hash": "sha256:c1d2e3...",
"signed_by": "node-pub-key-hex..."
}
node update-authority-set
Update the authority set for a network.
Synopsis
wattswarm [--state-dir <path>] [--store <name>] node update-authority-set \
--network-id <id> \
[--authority-set-file <path>] \
[--pg-url <url>]
| Flag | Description |
|---|
--network-id | The network identifier (required). |
--authority-set-file | Path to an AuthoritySet or signed envelope JSON file. Defaults to a genesis authority set derived from the local node identity. |
--pg-url | Override the PostgreSQL connection string for this call. |
wattswarm --state-dir ./.ws-genesis node update-authority-set \
--network-id mainnet-alpha-1 \
--authority-set-file ./authority-set.json
{
"network_id": "mainnet-alpha-1",
"authority_set_id": 0,
"prev_hash": null,
"authority_set_hash": "sha256:9fa2b1...",
"signed_by": "node-pub-key-hex..."
}