StratCraft

Discovery Chains

ClawNexus uses four complementary discovery mechanisms to find OpenClaw instances on local networks and beyond — no manual configuration required for most setups.

How Discovery Works

When clawnexus start runs, all four chains activate in parallel. Each chain reports found instances to a central registry, which deduplicates and maintains live status. Run Quick Start first to install the daemon.

Chain 1mDNS (Multicast DNS)
Chain 2UDP Broadcast
Chain 3Active LAN Scan
Chain 4Manual Registry
Chain 1

mDNS (Multicast DNS)

Zero-config local network discovery via RFC 6762 multicast DNS. Works automatically on the same subnet.

  • ClawNexus broadcasts a _clawnexus._tcp.local service record on startup.
  • All instances on the same LAN respond within 1–2 seconds.
  • No router configuration or DHCP reservations needed.
  • Compatible with macOS, Linux, and Windows 10+.
# mDNS discovery is automatic — no config needed
clawnexus start
# [mDNS] Listening on _clawnexus._tcp.local
# [mDNS] Found: home @ 192.168.1.10:7473
Chain 2

UDP Broadcast

Broadcast UDP packets across the subnet to find instances that may not support mDNS.

  • Sends a discovery beacon to the subnet broadcast address (e.g., 192.168.1.255).
  • Fallback for environments where mDNS multicast is blocked.
  • Configurable broadcast interval (default: 30s).
  • Works on any IPv4 LAN segment.
# UDP broadcast fires automatically as fallback
# [UDP] Broadcast sent to 192.168.1.255:7473
# [UDP] Response from 192.168.1.42 (raspi)
Chain 3

Active LAN Scan

Actively probe a configurable IP range for ClawNexus daemons. Triggered manually or on schedule.

  • Probes port 7473 across a configurable CIDR range.
  • Run on-demand with `clawnexus scan` or configure an auto-scan interval.
  • Respects a concurrency limit to avoid flooding the network.
  • Results are merged with mDNS/UDP findings in the instance registry.
clawnexus scan
# [Scan] Probing 192.168.1.0/24 on port 7473
# [Scan] Found 3 instances in 1.2s
Chain 4

Manual Registry

Explicitly register remote instances by IP or hostname. Required for cross-network peers (relay mode).

  • Add any host manually: `clawnexus add office 203.0.113.5`.
  • Persisted to `~/.clawnexus/registry.json`.
  • Supports hostname resolution for dynamic IPs.
  • Required when relay mode is used for cross-network connectivity.
clawnexus add office 203.0.113.5
# [Registry] Added: office @ 203.0.113.5:7473
clawnexus list
# NAME     HOST           STATUS
# home     192.168.1.10   online
# raspi    192.168.1.42   online
# office   203.0.113.5    relay

Discovery Priority

When the same instance is found by multiple chains, ClawNexus uses the following priority for connection routing:

  1. Manual Registry — explicit entries always win
  2. mDNS — preferred for LAN peers (lowest latency)
  3. UDP Broadcast — fallback when mDNS is blocked
  4. Active Scan — used when above methods miss an instance

For cross-network instances, see Relay documentation. For how instances are named after discovery, see Naming system.

← Quick StartNaming System →