> ## 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 startup_config.json: Fields and Examples

> Learn how startup_config.json controls network mode, bootstrap contacts, gateway URLs, and the default executor runtime for a WattSwarm node.

Every WattSwarm node reads a `startup_config.json` file from its state directory when it starts. This file controls the node's network mode, which peers it contacts on first boot, which gateway URLs it advertises, and which executor runtime handles tasks by default. Changes to this file take effect the next time the node starts — or immediately when you save them through the kernel console UI.

## Where the file lives

The default state directory is `.wattswarm/` in the current working directory. Inside Docker Compose the default container path is `/var/lib/wattswarm/`, backed by the named volume `wattswarm_state_data`.

```
<state-dir>/startup_config.json        # startup configuration
<state-dir>/node_state.json            # records node UP / DOWN status
<state-dir>/node_seed.hex              # Ed25519 private key seed
```

You can override the state directory with `--state-dir <path>` on any `wattswarm` CLI command, or with the `WATTSWARM_STATE_DIR` environment variable in Docker Compose.

## How to edit it

You have two options:

* **Kernel console UI** — open `http://127.0.0.1:7788/` and go to the **Startup** panel. Changes are validated and written to `startup_config.json` immediately.
* **Direct JSON edit** — open `<state-dir>/startup_config.json` in any text editor and save. The node reads the file on next startup; it does not hot-reload.

## Key fields

| Field                | Type       | Description                                                                                                                 |
| -------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------- |
| `network_mode`       | `string`   | Node operating mode: `"local"`, `"lan"`, or `"wan"`. Controls how the node bootstraps its network context on startup.       |
| `bootstrap_contacts` | `string[]` | Iroh contact strings for WAN or LAN mode, in `<iroh-node-id>@<host:port>` format. Cleared automatically in `local` mode.    |
| `gateway_urls`       | `string[]` | Optional gateway HTTP URLs used for network sync. Trailing slashes are stripped on save.                                    |
| `core_agent`         | `object`   | Configuration for the default executor runtime. Contains `mode`, `provider`, `base_url`, `model`, and `api_key` sub-fields. |

The `core_agent.base_url` field is the URL registered as the `core-agent` executor in the local PostgreSQL `executor_registry_local` table whenever you save from the startup UI. Setting it to your runtime's HTTP address (e.g. `http://127.0.0.1:8787`) is equivalent to running `wattswarm executors add core-agent <url>`.

## Example: local mode

A minimal single-machine configuration. No P2P or bootstrap contacts are needed.

```json theme={null}
{
  "network_mode": "local",
  "bootstrap_contacts": [],
  "gateway_urls": [],
  "core_agent": {
    "mode": "local_url",
    "provider": "openai-compatible",
    "base_url": "http://127.0.0.1:8787",
    "model": "",
    "api_key": ""
  }
}
```

## Example: WAN / network mode

A joining node that connects to an existing shared network. The `bootstrap_contacts` value comes from running `wattswarm node export-contact` on the genesis node.

```json theme={null}
{
  "network_mode": "wan",
  "bootstrap_contacts": [
    "abc123nodeId@203.0.113.10:4001"
  ],
  "gateway_urls": [
    "https://gateway.example.com"
  ],
  "core_agent": {
    "mode": "remote_url",
    "provider": "openai-compatible",
    "base_url": "https://runtime.example.com",
    "model": "",
    "api_key": ""
  }
}
```

## Other state-directory files

**`node_state.json`** records whether the node is currently `UP` or `DOWN`. The `wattswarm node up` and `wattswarm node down` commands write to this file. You do not need to edit it manually.

**`node_seed.hex`** contains the Ed25519 private key seed that determines the node's permanent identity (`node_id` and public key). The kernel derives the node's `node_id` from this seed on every startup.

<Warning>
  **Never copy `node_seed.hex` from one node to another.** Each node must have a unique seed. If two nodes start with the same seed, the registry bootstrap raises a clear conflict error because `node_registry.node_id` and `node_registry.public_key` must be unique across the network. Generate a fresh state directory for every new node.
</Warning>

## How startup UI saves differ from full bootstrap sync

When you save fields in the Startup panel, the kernel writes `network_mode`, `bootstrap_contacts`, `gateway_urls`, and `core_agent` directly to `startup_config.json`. It does **not** write network topology or signed network parameters into PostgreSQL at save time. The full `NetworkBootstrapBundle` — including `network_id`, `genesis_node_id`, `params_hash`, and the genesis signature — is imported into PostgreSQL only during node startup, when the kernel fetches and verifies the bundle from a configured bootstrap peer. You cannot bypass that verification step through the UI.