Every aspect of a WattSwarm node’s runtime behavior — from how it connects to PostgreSQL, to how aggressively it claims work, to whether it joins a P2P mesh — is controlled through environment variables. Set these in your shell, in a .env file, or in the environment block of your docker-compose.yml.
PostgreSQL
| Variable | Default | Description |
|---|
WATTSWARM_PG_URL | — | Full PostgreSQL connection URL (e.g. postgres://user:pass@host:5432/dbname). Required for all node operations. |
WATTSWARM_PG_SCHEMA | public | PostgreSQL schema name used for all WattSwarm tables. Override to isolate multiple nodes in one database. |
P2P Networking
| Variable | Default | Description |
|---|
WATTSWARM_P2P_ENABLED | true | Enable or disable the Iroh-backed P2P network bridge. Set to false for local-only mode. |
WATTSWARM_P2P_PORT | 4001 | Iroh direct listen port for QUIC connections from remote peers. |
WATTSWARM_P2P_LISTEN_ADDRS | — | Override the Iroh network address list. Useful when the node is behind NAT or needs to advertise a specific interface. |
WATTSWARM_P2P_REGION_IDS | — | Comma-separated list of region scope IDs to subscribe to (e.g. sol-1,sol-2). |
WATTSWARM_P2P_NODE_IDS | — | Comma-separated list of node scope IDs to subscribe to (e.g. lab-a). |
WATTSWARM_P2P_MDNS | true | Enable legacy mDNS local-discovery compatibility. Retained for generated-node compatibility paths. |
WATTSWARM_P2P_LOCAL_IDS | — | Legacy alias for WATTSWARM_P2P_NODE_IDS. Still accepted; prefer WATTSWARM_P2P_NODE_IDS for new deployments. |
Network Bootstrap
| Variable | Default | Description |
|---|
WATTSWARM_NODE_MODE | local | Node operating mode. One of local, lan, or network. Controls topology bootstrap behavior at startup. |
WATTSWARM_NETWORK_BOOTSTRAP_HTTP_URLS | — | Explicit HTTP endpoint URLs for fetching the signed NetworkBootstrapBundle when automatic peer derivation is not available. |
WATTSWARM_PUBLIC_DISCOVERY_URLS | — | Publishes one or more Discovery v1 API base URLs in /.well-known/wattswarm/join.json as discovery_urls, allowing joining nodes to locate this node. |
Worker Queue
| Variable | Default | Description |
|---|
WATTSWARM_WORKER_CONCURRENCY | 16 | Number of run steps claimed and executed in parallel by a single worker process. |
WATTSWARM_WORKER_POLL_MS | 250 | Milliseconds between worker poll cycles when no claimable steps are found. |
WATTSWARM_WORKER_LEASE_MS | 30000 | Duration in milliseconds for which a worker holds a step lease. The worker must renew before this window expires or the step becomes reclaimable. |
UDP Announce (LAN Discovery)
| Variable | Default | Description |
|---|
WATTSWARM_UDP_ANNOUNCE_ENABLED | false | Enable UDP multicast or broadcast peer announcement for LAN discovery. Also starts a listener that records discovered peer IDs into discovered_peers_local. |
WATTSWARM_UDP_ANNOUNCE_MODE | multicast | Announce strategy: multicast (default) or broadcast. |
WATTSWARM_UDP_ANNOUNCE_ADDR | 239.255.42.99 | Multicast group address. Set to 255.255.255.255 when using broadcast mode. |
WATTSWARM_UDP_ANNOUNCE_PORT | 37931 | UDP port used for both sending announcements and listening for peer sightings. |
Docker Compose Port Overrides
These variables let you remap host-side ports when the defaults conflict with other services on your machine. They affect only the Docker Compose port bindings; the in-container ports remain unchanged.
| Variable | Default | Description |
|---|
WATTSWARM_PG_HOST_PORT | 55432 | Host port mapped to the PostgreSQL container’s port 5432. |
WATTSWARM_UI_PORT | 7788 | Host port mapped to the kernel UI and HTTP API. |
WATTSWARM_P2P_HOST_PORT | 4001 | Host port mapped to the Iroh P2P listen port inside the kernel container. |
WATTSWARM_UDP_ANNOUNCE_HOST_PORT | 37931 | Host port mapped to the UDP announce port inside the kernel container. Only relevant when WATTSWARM_UDP_ANNOUNCE_ENABLED=true. |
WATTSWARM_RUNTIME_PORT | 8787 | Host port mapped to the reference runtime HTTP server. |
CLOCK_SKEW_TOLERANCE_MS defines the tolerance window used when validating step lease expiry across distributed nodes. If your nodes have clock drift larger than this value, a worker may incorrectly see an active lease as expired. Keep node system clocks synchronized (e.g. via NTP) and adjust this value only if you have a documented reason for wider tolerance.
MAX_EVENT_PAYLOAD_BYTES and MAX_STRUCTURED_SUMMARY_BYTES are hard caps enforced by kernel validation on event payloads and structured summary payloads respectively. Events or summaries that exceed these limits are rejected before they reach the event log. Keep shared_inputs and candidate output bodies concise, and prefer content references over inline blobs to stay within these limits.