> ## Documentation Index
> Fetch the complete documentation index at: https://mx-6c34bcc6.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# 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.