WattSwarm Environment Variables: Complete Reference

Complete reference for every environment variable controlling WattSwarm: database connections, P2P networking, worker tuning, and Docker port overrides.

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.