Multi-Machine Setup

This guide explains how to connect Starweft nodes across multiple machines using the libp2p TCP transport.

Transport Overview

Starweft provides two types of transport.

Switching to libp2p Transport

Specify at initialization

starweft init --role owner \
  --data-dir ~/.starweft-owner \
  --listen /ip4/0.0.0.0/tcp/9100

Specifying /ip4/0.0.0.0 listens on all network interfaces.

Modify existing configuration

Edit the [p2p] and [node] sections in config.toml.

[node]
role = "owner"
listen = ["/ip4/0.0.0.0/tcp/9100"]
 
[p2p]
transport = "libp2p"
relay_enabled = true
direct_preferred = true
max_peers = 128

Network Configuration

Example Port Design

Firewall Configuration

Open the ports used on each machine. Starweft uses TCP only (UDP/QUIC is not currently supported).

# Example: using ufw
sudo ufw allow 9100/tcp

Manual Peer Registration

With the libp2p transport, the multiaddress must include /p2p/<peer-id>.

starweft identity show --data-dir ~/.starweft-owner

# Register the owner with the principal
starweft peer add /ip4/192.168.1.20/tcp/9100/p2p/<OWNER_PEER_ID> \
  --data-dir ~/.starweft-principal \
  --actor-id <OWNER_ACTOR_ID> \
  --node-id <OWNER_NODE_ID> \
  --public-key <OWNER_PUBLIC_KEY>
 
# Register the worker with the owner
starweft peer add /ip4/192.168.1.30/tcp/9200/p2p/<WORKER_PEER_ID> \
  --data-dir ~/.starweft-owner \
  --actor-id <WORKER_ACTOR_ID> \
  --node-id <WORKER_NODE_ID> \
  --public-key <WORKER_PUBLIC_KEY>

starweft peer list --data-dir ~/.starweft-principal

mDNS Auto-Discovery (v0.3.0)

Starting with v0.3.0, nodes on the same LAN can be automatically discovered via mDNS (Multicast DNS). This eliminates the need for manual peer registration and allows flexible handling of node additions and removals.

Enabling mDNS

Configure it in the [discovery] section of config.toml.

[p2p]
transport = "libp2p"
 
[discovery]
mdns = true

How It Works

When a node with mDNS enabled starts up, the following process runs automatically:

1. Peer discovery — Automatically discovers Starweft nodes on the same network via mDNS multicast
2. Address registration — Automatically registers the discovered peer's multiaddress in the local peer store
3. CapabilityQuery transmission — Sends a CapabilityQuery message containing the local node's identity and capabilities to the discovered peer
4. CapabilityAdvertisement reception — The remote node responds with a CapabilityAdvertisement, mutually exchanging capability information
5. Peer information persistence — Saves the received public key, capabilities, and listen addresses to the local database

Through this exchange, the information needed for authentication and communication between nodes is automatically shared without manually running peer add.

CapabilityQuery / CapabilityAdvertisement

The messages exchanged during mDNS discovery contain the following information:

{
  "node_id": "node_...",
  "public_key": "<base64-encoded Ed25519 public key>",
  "stop_public_key": "<base64-encoded stop authority key (optional)>",
  "capabilities": ["openclaw.execution.v1"],
  "listen_addresses": ["/ip4/192.168.1.20/tcp/9100"],
  "requested_at": "2026-03-15T10:00:00Z"
}

Security Considerations

• Use only on trusted networks — mDNS uses multicast, so all devices on the same LAN become discovery targets
• Disable on public networks — In cafes, shared offices, etc., setting mdns = false is recommended
• Message signing is maintained — Even when communicating with peers discovered via mDNS, all messages are signed and verified with Ed25519
• Existing peer registrations take priority — Peer information discovered via mDNS does not overwrite manually registered peer information

Disabling mDNS

[discovery]
mdns = false

mDNS is disabled by default even when using the libp2p transport. It only operates when explicitly set to true.

Relay Node Configuration

When nodes behind NAT cannot communicate directly with each other, messages can be relayed through a relay node.

Initializing a Relay Node

starweft init --role relay \
  --data-dir ~/.starweft-relay \
  --listen /ip4/0.0.0.0/tcp/9300

Registering the Relay Node as a Peer

Register the relay as a peer from each node.

starweft peer add /ip4/<RELAY_IP>/tcp/9300/p2p/<RELAY_PEER_ID> \
  --data-dir ~/.starweft-owner

Relay Settings

[p2p]
transport = "libp2p"
relay_enabled = true
direct_preferred = true

• relay_enabled — Allow communication via relay (default: true)
• direct_preferred — Prefer direct connections; use relay only when direct connection fails (default: true)

Seed Peer Configuration

You can specify seed peers that are automatically connected to at startup in the [discovery] section of config.toml.

[discovery]
seeds = [
  "/ip4/192.168.1.10/tcp/9000/p2p/12D3Koo...",
  "/ip4/192.168.1.20/tcp/9100/p2p/12D3Koo..."
]
auto_discovery = true

• seeds — List of multiaddresses of peers to attempt connection to at startup
• auto_discovery — Enable automatic exchange of CapabilityQuery/CapabilityAdvertisement

Reconnection to seed peers is automatically attempted at 5-second intervals. Connections are also automatically restored if disconnected.

Troubleshooting

Cannot Connect

# Check port reachability
nc -zv <TARGET_IP> <PORT>

# Correct format
/ip4/192.168.1.20/tcp/9100/p2p/12D3KooWAbcDef...
 
# Incorrect format (missing peer-id)
/ip4/192.168.1.20/tcp/9100

starweft config show --data-dir ~/.starweft-owner | grep transport

Peers Not Discovered (mDNS)

starweft config show --data-dir ~/.starweft-owner | grep mdns

Checking Logs

To investigate connection issues, check the logs.

starweft logs --data-dir ~/.starweft-owner --component p2p --tail 50

If more detailed logs are needed, start the node with increased verbosity.

starweft run --data-dir ~/.starweft-owner --foreground --log-level debug -v

Validating Configuration

starweft config validate --data-dir ~/.starweft-owner

This command validates listen address formats, key file existence, protocol version compatibility, and more, reporting any warnings or errors.

Next Steps