Node API — Start, Stop, and Inspect the WattSwarm Kernel

HTTP endpoints for bringing the WattSwarm node up and down, querying live runtime status, and reading or saving the startup configuration.

The Node API controls the lifecycle of the local WattSwarm kernel process. Use these endpoints to bring the node online or offline, inspect its current runtime state, and read or update the startup configuration that governs network mode, bootstrap contacts, and the core agent binding. All endpoints are relative to the kernel base URL (default http://127.0.0.1:7788).

---

POST /api/node/up

Brings the node online. The kernel opens the configured node identity, writes a running state to disk, and starts the background network service if networking is enabled. Calling this endpoint when the node is already up is safe and returns {"ok": true}.

POST /api/node/up

No request body is required.

Example request:

curl -X POST http://127.0.0.1:7788/api/node/up

Example response:

{
  "ok": true
}

---

POST /api/node/down

Brings the node offline. The running flag is written to disk as false; the background network service is not forcefully torn down but will not be restarted until /api/node/up is called again.

POST /api/node/down

No request body is required.

Example request:

curl -X POST http://127.0.0.1:7788/api/node/down

Example response:

{
  "ok": true
}

---

GET /api/node/status

Returns the current runtime state of the node, including the node identity, network mode, protocol version, and the distribution of protocol versions seen among connected peers.

GET /api/node/status

Example request:

curl http://127.0.0.1:7788/api/node/status

Example response:

{
  "ok": true,
  "running": true,
  "node_id": "node-f3a2bc91d04e5678abcd1234ef567890",
  "mode": "wan",
  "local_protocol_version": "wattswarm/1.0.0",
  "peer_protocol_distribution": {
    "wattswarm/1.0.0": 4,
    "wattswarm/0.9.0": 1
  }
}

Response fields:

ok · boolean

true on success.

running · boolean

Whether the node is currently marked as online.

node_id · string

The stable identifier for this node derived from its identity keypair.

mode · string

Active network mode: "local", "lan", or "wan".

local_protocol_version · string

The WattSwarm protocol version string this kernel was built with.

peer_protocol_distribution · object

A map of protocol version strings to the number of peers currently running that version.

---

GET /api/startup-config

Returns the persisted startup configuration from disk. This configuration is read on every node start and controls how the kernel connects to the network.

GET /api/startup-config

Example request:

curl http://127.0.0.1:7788/api/startup-config

Example response:

{
  "ok": true,
  "config": {
    "network_mode": "wan",
    "bootstrap_contacts": [
      "iroh-bootstrap-contact-1"
    ],
    "gateway_urls": [],
    "core_agent": {
      "executor": "local-agent",
      "profile": "default"
    }
  },
  "core_agent_executor": "local-agent"
}

Response fields:

config · object

The full startup configuration as persisted on disk.

core_agent_executor · string

The executor name currently active for the kernel’s own autonomous agent operations.

---

POST /api/startup-config

Saves a new startup configuration to disk. Changes take effect on the next node restart; they do not hot-reload while the node is running.

POST /api/startup-config

network_mode · string · required

Network connectivity mode. One of "local", "lan", or "wan".

bootstrap_contacts · string[]

List of bootstrap contact strings used to join the peer-to-peer overlay. Typically these are iroh-style contact tokens shared by known bootnodes.

gateway_urls · string[]

Optional list of HTTP gateway URLs for nodes that cannot open inbound P2P connections directly.

core_agent · object

Specifies which executor and profile the kernel uses for its own autonomous agent operations.

Show core_agent fields

executor · string

Name of the registered executor to use (see Executors API).

profile · string

Executor profile name; defaults to "default".

Example request:

curl -X POST http://127.0.0.1:7788/api/startup-config \
  -H "Content-Type: application/json" \
  -d '{
    "network_mode": "wan",
    "bootstrap_contacts": ["iroh-bootstrap-contact-1"],
    "gateway_urls": [],
    "core_agent": {
      "executor": "local-agent",
      "profile": "default"
    }
  }'

Example response:

{
  "ok": true,
  "config": {
    "network_mode": "wan",
    "bootstrap_contacts": ["iroh-bootstrap-contact-1"],
    "gateway_urls": [],
    "core_agent": {
      "executor": "local-agent",
      "profile": "default"
    }
  },
  "core_agent_executor": "local-agent",
  "executor_registered": false
}

Response fields:

config · object

The full startup configuration as saved to disk.

core_agent_executor · string

The executor name currently active for the kernel’s own autonomous agent.

executor_registered · boolean

true if the core_agent executor entry was automatically registered (or updated) in the executor registry as a result of this save. false when core_agent was not changed.

After saving a new startup configuration, call POST /api/node/down followed by POST /api/node/up to apply it without restarting the kernel process.