feat(us-016/us-017): mining-style node startup CLI, live dashboard, auto-shard, P2P gossip + TLS

Merges worktree-feat+us-016 into master. Combined both sets of _NodeEntry
fields: hf_repo/num_layers (HEAD) and relay_addr/cert_fingerprint/peer_id
(US-017). Kept HEAD's auto-shard tracker query and shard_label formatting.

US-016: mining-style startup CLI with live ASCII dashboard, hardware
detection, auto-shard range detection from model layer count, tracker
network-assign integration for gap-filling.

US-017: P2P gossip protocol, NAT-traversal relay node, TLS peer
authentication via cert fingerprint.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

packages/node/pyproject.toml

@@ -13,6 +13,7 @@ dependencies = [
     "huggingface-hub>=0.20",
     "accelerate>=0.28",
     "bitsandbytes>=0.43",
+    "rich>=13",
     "safetensors>=0.4",
     "torch>=2.1",
     "transformers>=4.39",

packages/p2p/meshnet_p2p/gossip.py

@@ -0,0 +1,162 @@
+"""WebSocket gossip client — connects to relay, publish/subscribe to topics."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import threading
+import time
+import uuid
+from collections import defaultdict
+from typing import Callable
+
+log = logging.getLogger(__name__)
+
+# Message envelope topics
+TOPIC_NODE_JOIN = "node-join"
+TOPIC_NODE_LEAVE = "node-leave"
+TOPIC_COVERAGE_UPDATE = "coverage-update"
+TOPIC_HEARTBEAT = "heartbeat"
+TOPIC_PEER_LIST = "peer-list"
+TOPIC_RELAY_ANNOUNCE = "relay-announce"
+
+_MSG_TTL = 3  # max re-broadcast hops
+
+
+def _make_envelope(topic: str, payload: dict, from_peer: str, ttl: int = _MSG_TTL) -> dict:
+    return {
+        "topic": topic,
+        "version": 1,
+        "from_peer": from_peer,
+        "timestamp": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+        "msg_id": str(uuid.uuid4()),
+        "ttl": ttl,
+        "payload": payload,
+    }
+
+
+class GossipClient:
+    """Thread-safe WebSocket gossip client.
+
+    Usage::
+
+        client = GossipClient(relay_url="ws://relay:8765", peer_id="abc123")
+        client.subscribe("node-join", lambda env: print(env["payload"]))
+        client.start()
+        client.publish("node-join", {"addr": "http://192.168.1.42:8001", ...})
+        ...
+        client.stop()
+    """
+
+    def __init__(self, relay_url: str, peer_id: str, reconnect_interval: float = 3.0):
+        self.relay_url = relay_url
+        self.peer_id = peer_id
+        self.reconnect_interval = reconnect_interval
+
+        self._handlers: dict[str, list[Callable]] = defaultdict(list)
+        self._seen: set[str] = set()
+        self._loop: asyncio.AbstractEventLoop | None = None
+        self._thread: threading.Thread | None = None
+        self._ws = None
+        self._running = False
+        self._connected = threading.Event()
+        self._stop_event: asyncio.Event | None = None
+
+    def subscribe(self, topic: str, handler: Callable) -> None:
+        """Register a sync callback for messages on topic."""
+        self._handlers[topic].append(handler)
+
+    def publish(self, topic: str, payload: dict) -> None:
+        """Send a gossip message to all peers via the relay. Thread-safe."""
+        envelope = _make_envelope(topic, payload, self.peer_id)
+        if self._loop and self._running:
+            asyncio.run_coroutine_threadsafe(self._send(envelope), self._loop)
+
+    def start(self) -> None:
+        """Start the gossip client in a background thread."""
+        self._running = True
+        self._loop = asyncio.new_event_loop()
+        self._thread = threading.Thread(target=self._run_loop, daemon=True, name="gossip")
+        self._thread.start()
+
+    def wait_connected(self, timeout: float = 5.0) -> bool:
+        """Block until connected to relay or timeout. Returns True if connected."""
+        return self._connected.wait(timeout)
+
+    def stop(self) -> None:
+        """Stop the gossip client and clean up."""
+        self._running = False
+        if self._loop and self._stop_event is not None:
+            self._loop.call_soon_threadsafe(self._stop_event.set)
+        if self._thread:
+            self._thread.join(timeout=3.0)
+
+    # ------------------------------------------------------------------
+    # Internal asyncio methods (run inside the background event loop)
+    # ------------------------------------------------------------------
+
+    def _run_loop(self) -> None:
+        asyncio.set_event_loop(self._loop)
+        self._stop_event = asyncio.Event()
+        try:
+            self._loop.run_until_complete(self._connect_loop())
+        except Exception:
+            log.debug("Gossip loop exited", exc_info=True)
+
+    async def _connect_loop(self) -> None:
+        import websockets  # type: ignore[import]
+
+        while self._running and not (self._stop_event and self._stop_event.is_set()):
+            try:
+                async with websockets.connect(
+                    self.relay_url,
+                    ping_interval=20,
+                    ping_timeout=10,
+                    open_timeout=5,
+                ) as ws:
+                    self._ws = ws
+                    self._connected.set()
+                    log.debug("Gossip connected to %s", self.relay_url)
+                    # Send peer registration
+                    await ws.send(json.dumps(
+                        _make_envelope(
+                            "peer-register",
+                            {"peer_id": self.peer_id},
+                            self.peer_id,
+                        )
+                    ))
+                    await self._receive_loop(ws)
+            except Exception as exc:
+                self._connected.clear()
+                if self._running:
+                    log.debug("Gossip disconnected (%s); reconnecting in %ss", exc, self.reconnect_interval)
+                    await asyncio.sleep(self.reconnect_interval)
+
+    async def _receive_loop(self, ws) -> None:
+        async for raw in ws:
+            try:
+                envelope = json.loads(raw)
+            except (json.JSONDecodeError, TypeError):
+                continue
+            msg_id = envelope.get("msg_id", "")
+            if msg_id in self._seen:
+                continue
+            self._seen.add(msg_id)
+            if len(self._seen) > 10_000:
+                # Trim seen set to avoid unbounded growth
+                self._seen = set(list(self._seen)[-5_000:])
+
+            topic = envelope.get("topic", "")
+            for handler in self._handlers.get(topic, []):
+                try:
+                    handler(envelope)
+                except Exception:
+                    log.debug("Gossip handler error for topic %s", topic, exc_info=True)
+
+    async def _send(self, envelope: dict) -> None:
+        if self._ws is not None:
+            try:
+                await self._ws.send(json.dumps(envelope))
+            except Exception as exc:
+                log.debug("Gossip send failed: %s", exc)

packages/p2p/meshnet_p2p/identity.py

@@ -0,0 +1,64 @@
+"""Peer identity — stable peer_id and RSA keypair, persisted to disk."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import stat
+from pathlib import Path
+
+_DEFAULT_IDENTITY_PATH = Path.home() / ".config" / "meshnet" / "identity.json"
+
+
+def _generate_keypair() -> tuple[bytes, bytes]:
+    """Return (private_key_pem, public_key_pem) for a new RSA-2048 keypair."""
+    from cryptography.hazmat.primitives.asymmetric import rsa
+    from cryptography.hazmat.primitives import serialization
+
+    key = rsa.generate_private_key(public_exponent=65537, key_size=2048)
+    priv_pem = key.private_bytes(
+        serialization.Encoding.PEM,
+        serialization.PrivateFormat.PKCS8,
+        serialization.NoEncryption(),
+    )
+    pub_pem = key.public_key().public_bytes(
+        serialization.Encoding.PEM,
+        serialization.PublicFormat.SubjectPublicKeyInfo,
+    )
+    return priv_pem, pub_pem
+
+
+def _peer_id_from_pubkey(pub_pem: bytes) -> str:
+    return hashlib.sha256(pub_pem).hexdigest()[:16]
+
+
+def load_or_create_identity(path: Path | None = None) -> dict:
+    """Return identity dict with peer_id, private_key_pem, public_key_pem.
+
+    Creates and persists a new identity if none exists at path.
+    """
+    p = path or _DEFAULT_IDENTITY_PATH
+    if p.exists():
+        try:
+            data = json.loads(p.read_text())
+            if "peer_id" in data and "public_key_pem" in data:
+                return data
+        except (json.JSONDecodeError, OSError):
+            pass
+
+    priv_pem, pub_pem = _generate_keypair()
+    identity = {
+        "peer_id": _peer_id_from_pubkey(pub_pem),
+        "private_key_pem": priv_pem.decode(),
+        "public_key_pem": pub_pem.decode(),
+    }
+
+    p.parent.mkdir(parents=True, exist_ok=True)
+    p.write_text(json.dumps(identity, indent=2))
+    try:
+        os.chmod(p, stat.S_IRUSR | stat.S_IWUSR)
+    except OSError:
+        pass
+
+    return identity

packages/p2p/meshnet_p2p/mdns.py

@@ -0,0 +1,136 @@
+"""mDNS peer discovery using zeroconf (optional dependency).
+
+Falls back gracefully if zeroconf is not installed.
+"""
+
+from __future__ import annotations
+
+import logging
+import socket
+import threading
+from typing import Callable
+
+log = logging.getLogger(__name__)
+
+MDNS_SERVICE_TYPE = "_meshnet._tcp.local."
+
+try:
+    from zeroconf import ServiceInfo, ServiceBrowser, Zeroconf  # type: ignore[import]
+
+    _HAS_ZEROCONF = True
+except ImportError:
+    _HAS_ZEROCONF = False
+
+
+def _local_ip() -> str:
+    try:
+        s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+        s.connect(("8.8.8.8", 80))
+        ip = s.getsockname()[0]
+        s.close()
+        return ip
+    except OSError:
+        return "127.0.0.1"
+
+
+class MdnsDiscovery:
+    """Announce this node on mDNS and discover peers on the same LAN.
+
+    If `zeroconf` is not installed, all methods are no-ops.
+
+    Usage::
+
+        disc = MdnsDiscovery(
+            peer_id="abc123",
+            port=8001,
+            on_peer_found=lambda peer_id, addr: print("found", peer_id, addr),
+        )
+        disc.start()
+        ...
+        disc.stop()
+    """
+
+    def __init__(
+        self,
+        peer_id: str,
+        port: int,
+        on_peer_found: Callable[[str, str], None] | None = None,
+        on_peer_lost: Callable[[str], None] | None = None,
+    ):
+        self.peer_id = peer_id
+        self.port = port
+        self.on_peer_found = on_peer_found
+        self.on_peer_lost = on_peer_lost
+        self._zc: "Zeroconf | None" = None  # type: ignore[name-defined]
+        self._info: "ServiceInfo | None" = None  # type: ignore[name-defined]
+        self._browser = None
+
+    def is_available(self) -> bool:
+        return _HAS_ZEROCONF
+
+    def start(self) -> None:
+        if not _HAS_ZEROCONF:
+            log.info("zeroconf not installed — mDNS discovery disabled")
+            return
+        try:
+            self._zc = Zeroconf()
+            local_ip = _local_ip()
+            self._info = ServiceInfo(
+                MDNS_SERVICE_TYPE,
+                f"{self.peer_id}.{MDNS_SERVICE_TYPE}",
+                addresses=[socket.inet_aton(local_ip)],
+                port=self.port,
+                properties={"peer_id": self.peer_id, "version": "1"},
+            )
+            self._zc.register_service(self._info)
+            if self.on_peer_found or self.on_peer_lost:
+                self._browser = ServiceBrowser(
+                    self._zc, MDNS_SERVICE_TYPE, listener=_Listener(self)
+                )
+            log.info("mDNS announced: %s on %s:%d", self.peer_id, local_ip, self.port)
+        except Exception as exc:
+            log.warning("mDNS start failed: %s", exc)
+
+    def stop(self) -> None:
+        if not _HAS_ZEROCONF or self._zc is None:
+            return
+        try:
+            if self._info:
+                self._zc.unregister_service(self._info)
+            self._zc.close()
+        except Exception as exc:
+            log.debug("mDNS stop error: %s", exc)
+        self._zc = None
+
+
+class _Listener:
+    """Internal zeroconf service listener."""
+
+    def __init__(self, disc: MdnsDiscovery):
+        self._disc = disc
+
+    def add_service(self, zc, type_, name):
+        try:
+            info = zc.get_service_info(type_, name)
+            if info is None:
+                return
+            remote_peer_id = (info.properties or {}).get(b"peer_id", b"").decode()
+            if remote_peer_id == self._disc.peer_id:
+                return  # ignore self
+            addr = f"http://{socket.inet_ntoa(info.addresses[0])}:{info.port}"
+            if self._disc.on_peer_found:
+                self._disc.on_peer_found(remote_peer_id, addr)
+        except Exception as exc:
+            log.debug("mDNS add_service error: %s", exc)
+
+    def remove_service(self, zc, type_, name):
+        try:
+            # name is like "peer_id._meshnet._tcp.local."
+            peer_id = name.split(".")[0]
+            if self._disc.on_peer_lost:
+                self._disc.on_peer_lost(peer_id)
+        except Exception as exc:
+            log.debug("mDNS remove_service error: %s", exc)
+
+    def update_service(self, zc, type_, name):
+        pass

packages/p2p/meshnet_p2p/tls.py

@@ -0,0 +1,114 @@
+"""TLS certificate generation and fingerprint helpers for node-to-node comms."""
+
+from __future__ import annotations
+
+import datetime
+import hashlib
+import ipaddress
+import json
+import os
+import socket
+import ssl
+import stat
+from pathlib import Path
+
+_CERT_PATH = Path.home() / ".config" / "meshnet" / "node_cert.pem"
+_KEY_PATH = Path.home() / ".config" / "meshnet" / "node_key.pem"
+
+
+def generate_self_signed_cert(
+    cert_path: Path | None = None,
+    key_path: Path | None = None,
+    common_name: str | None = None,
+) -> tuple[Path, Path]:
+    """Generate a self-signed RSA-2048 cert valid for 10 years.
+
+    Returns (cert_path, key_path). Skips generation if both files already exist.
+    """
+    from cryptography import x509
+    from cryptography.hazmat.primitives import hashes, serialization
+    from cryptography.hazmat.primitives.asymmetric import rsa
+    from cryptography.x509.oid import NameOID
+
+    cert_p = cert_path or _CERT_PATH
+    key_p = key_path or _KEY_PATH
+
+    if cert_p.exists() and key_p.exists():
+        return cert_p, key_p
+
+    cert_p.parent.mkdir(parents=True, exist_ok=True)
+
+    key = rsa.generate_private_key(public_exponent=65537, key_size=2048)
+    cn = common_name or socket.getfqdn()
+
+    subject = issuer = x509.Name([
+        x509.NameAttribute(NameOID.COMMON_NAME, cn),
+        x509.NameAttribute(NameOID.ORGANIZATION_NAME, "meshnet-node"),
+    ])
+
+    san_list: list = [x509.DNSName(cn)]
+    try:
+        san_list.append(x509.IPAddress(ipaddress.IPv4Address(socket.gethostbyname(cn))))
+    except (socket.gaierror, ValueError):
+        pass
+    san_list.append(x509.IPAddress(ipaddress.IPv4Address("127.0.0.1")))
+
+    cert = (
+        x509.CertificateBuilder()
+        .subject_name(subject)
+        .issuer_name(issuer)
+        .public_key(key.public_key())
+        .serial_number(x509.random_serial_number())
+        .not_valid_before(datetime.datetime.now(datetime.timezone.utc))
+        .not_valid_after(datetime.datetime.now(datetime.timezone.utc) + datetime.timedelta(days=365 * 10))
+        .add_extension(x509.SubjectAlternativeName(san_list), critical=False)
+        .sign(key, hashes.SHA256())
+    )
+
+    key_pem = key.private_bytes(
+        serialization.Encoding.PEM,
+        serialization.PrivateFormat.TraditionalOpenSSL,
+        serialization.NoEncryption(),
+    )
+    cert_pem = cert.public_bytes(serialization.Encoding.PEM)
+
+    key_p.write_bytes(key_pem)
+    cert_p.write_bytes(cert_pem)
+    try:
+        os.chmod(key_p, stat.S_IRUSR | stat.S_IWUSR)
+    except OSError:
+        pass
+
+    return cert_p, key_p
+
+
+def cert_fingerprint(cert_path: Path | None = None) -> str:
+    """Return sha256 fingerprint of the cert as 'sha256:<hex>'."""
+    from cryptography import x509
+    from cryptography.hazmat.primitives import hashes
+
+    p = cert_path or _CERT_PATH
+    cert = x509.load_pem_x509_certificate(p.read_bytes())
+    fp = cert.fingerprint(hashes.SHA256()).hex()
+    return f"sha256:{fp}"
+
+
+def make_server_ssl_context(
+    cert_path: Path | None = None,
+    key_path: Path | None = None,
+) -> ssl.SSLContext:
+    """Return an ssl.SSLContext for a server using our self-signed cert."""
+    cert_p = cert_path or _CERT_PATH
+    key_p = key_path or _KEY_PATH
+    ctx = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
+    ctx.load_cert_chain(certfile=str(cert_p), keyfile=str(key_p))
+    return ctx
+
+
+def make_client_ssl_context(verify: bool = False) -> ssl.SSLContext:
+    """Return a client SSLContext. verify=False for self-signed TOFU connections."""
+    ctx = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
+    if not verify:
+        ctx.check_hostname = False
+        ctx.verify_mode = ssl.CERT_NONE
+    return ctx

packages/p2p/pyproject.toml

@@ -8,6 +8,14 @@ version = "0.1.0"
 description = "Distributed Inference Network gossip and shard swarm"
 requires-python = ">=3.10"
 
+dependencies = [
+    "cryptography>=41",
+    "websockets>=13",
+]
+
+[project.optional-dependencies]
+mdns = ["zeroconf>=0.131"]
+
 [tool.setuptools.packages.find]
 where = ["."]
 include = ["meshnet_p2p*"]

packages/p2p/relay_bootstrap.json

@@ -0,0 +1,10 @@
+{
+  "relays": [
+    {
+      "url": "ws://localhost:8765",
+      "cert_fingerprint": null,
+      "operator": "localhost-dev",
+      "note": "Local development relay — replace with team relay URL before production"
+    }
+  ]
+}

packages/relay/meshnet_relay/__init__.py

@@ -0,0 +1,3 @@
+"""meshnet-relay — NAT-traversal relay and gossip hub."""
+
+__version__ = "0.1.0"

packages/relay/meshnet_relay/cli.py

@@ -0,0 +1,60 @@
+"""meshnet-relay CLI entry point."""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import sys
+import time
+from pathlib import Path
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="meshnet-relay",
+        description="Meshnet NAT-traversal relay and gossip hub",
+    )
+    parser.add_argument("--host", default="0.0.0.0", help="Interface to bind")
+    parser.add_argument("--port", type=int, default=8765, help="WebSocket port")
+    parser.add_argument("--cert", metavar="PATH", help="TLS certificate (PEM)")
+    parser.add_argument("--key", metavar="PATH", help="TLS private key (PEM)")
+    parser.add_argument("--max-peers", type=int, default=500, help="Max concurrent peers")
+    parser.add_argument("--log-level", default="INFO", choices=["DEBUG", "INFO", "WARNING", "ERROR"])
+
+    args = parser.parse_args()
+    logging.basicConfig(
+        level=getattr(logging, args.log_level),
+        format="%(asctime)s  %(levelname)-8s  %(name)s  %(message)s",
+    )
+
+    from .server import RelayServer
+
+    ssl_cert = Path(args.cert) if args.cert else None
+    ssl_key = Path(args.key) if args.key else None
+
+    server = RelayServer(
+        host=args.host,
+        port=args.port,
+        ssl_cert=ssl_cert,
+        ssl_key=ssl_key,
+        max_peers=args.max_peers,
+    )
+    port = server.start()
+    scheme = "wss" if ssl_cert else "ws"
+    print(f"meshnet-relay listening on {scheme}://{args.host}:{port}", flush=True)
+    print("  /ws             gossip PubSub", flush=True)
+    print("  /relay/<id>     circuit relay to peer", flush=True)
+    print("  /health         health check", flush=True)
+    print("  /v1/peers       peer list", flush=True)
+    print("Press Ctrl-C to stop.", flush=True)
+
+    try:
+        while True:
+            time.sleep(1)
+    except KeyboardInterrupt:
+        print("\nStopping relay…", flush=True)
+        server.stop()
+
+
+if __name__ == "__main__":
+    main()

packages/relay/meshnet_relay/peer_registry.py

@@ -0,0 +1,60 @@
+"""In-memory registry of connected gossip peers."""
+
+from __future__ import annotations
+
+import threading
+import time
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class PeerEntry:
+    peer_id: str
+    addr: str
+    ws: Any  # websockets.WebSocketServerProtocol
+    connected_at: float = field(default_factory=time.monotonic)
+    last_seen: float = field(default_factory=time.monotonic)
+
+
+class PeerRegistry:
+    def __init__(self):
+        self._peers: dict[str, PeerEntry] = {}
+        self._lock = threading.Lock()
+
+    def register(self, peer_id: str, addr: str, ws) -> None:
+        with self._lock:
+            self._peers[peer_id] = PeerEntry(peer_id=peer_id, addr=addr, ws=ws)
+
+    def unregister(self, peer_id: str) -> None:
+        with self._lock:
+            self._peers.pop(peer_id, None)
+
+    def touch(self, peer_id: str) -> None:
+        with self._lock:
+            if peer_id in self._peers:
+                self._peers[peer_id].last_seen = time.monotonic()
+
+    def get(self, peer_id: str) -> PeerEntry | None:
+        with self._lock:
+            return self._peers.get(peer_id)
+
+    def all_except(self, peer_id: str) -> list[PeerEntry]:
+        with self._lock:
+            return [e for pid, e in self._peers.items() if pid != peer_id]
+
+    def list_peers(self) -> list[dict]:
+        with self._lock:
+            return [
+                {
+                    "peer_id": e.peer_id,
+                    "addr": e.addr,
+                    "connected_at": e.connected_at,
+                    "last_seen": e.last_seen,
+                }
+                for e in self._peers.values()
+            ]
+
+    def __len__(self) -> int:
+        with self._lock:
+            return len(self._peers)

packages/relay/meshnet_relay/server.py

@@ -0,0 +1,224 @@
+"""Relay server — WebSocket gossip hub + circuit relay proxy.
+
+HTTP API (served via asyncio-based handler on same port):
+  GET /health              → {"status": "ok", "peers": N}
+  GET /v1/peers            → [{peer_id, addr, last_seen}]
+  POST /v1/gossip          → accept a gossip envelope, fan out to connected peers
+
+WebSocket endpoints:
+  ws[s]://host:port/ws              → gossip PubSub connection
+  ws[s]://host:port/relay/{peer_id} → circuit relay to that peer
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import threading
+from pathlib import Path
+
+from .peer_registry import PeerRegistry
+
+log = logging.getLogger(__name__)
+
+
+class RelayServer:
+    """Async WebSocket relay server that runs in a background thread.
+
+    Usage::
+
+        server = RelayServer(host="0.0.0.0", port=8765)
+        port = server.start()   # returns actual port
+        ...
+        server.stop()
+    """
+
+    def __init__(
+        self,
+        host: str = "0.0.0.0",
+        port: int = 8765,
+        ssl_cert: Path | None = None,
+        ssl_key: Path | None = None,
+        max_peers: int = 500,
+    ):
+        self.host = host
+        self.port = port
+        self.ssl_cert = ssl_cert
+        self.ssl_key = ssl_key
+        self.max_peers = max_peers
+
+        self._registry = PeerRegistry()
+        self._loop: asyncio.AbstractEventLoop | None = None
+        self._thread: threading.Thread | None = None
+        self._server = None
+        self._actual_port: int = port
+        self._ready = threading.Event()
+        self._running = False
+        self._stop_event: asyncio.Event | None = None
+
+    @property
+    def registry(self) -> PeerRegistry:
+        return self._registry
+
+    def start(self) -> int:
+        """Start server in background thread. Returns actual bound port."""
+        self._running = True
+        self._loop = asyncio.new_event_loop()
+        self._thread = threading.Thread(target=self._run, daemon=True, name="relay")
+        self._thread.start()
+        self._ready.wait(timeout=5)
+        return self._actual_port
+
+    def stop(self) -> None:
+        self._running = False
+        if self._loop and self._stop_event is not None:
+            self._loop.call_soon_threadsafe(self._stop_event.set)
+        if self._thread:
+            self._thread.join(timeout=3.0)
+
+    def _run(self) -> None:
+        asyncio.set_event_loop(self._loop)
+        self._loop.run_until_complete(self._serve())
+
+    async def _serve(self) -> None:
+        import websockets  # type: ignore[import]
+        import websockets.server  # type: ignore[import]
+
+        ssl_ctx = None
+        if self.ssl_cert and self.ssl_key:
+            import ssl
+            ssl_ctx = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
+            ssl_ctx.load_cert_chain(str(self.ssl_cert), str(self.ssl_key))
+
+        server = await websockets.serve(
+            self._handle_connection,
+            self.host,
+            self.port,
+            ssl=ssl_ctx,
+        )
+        # Record actual port after bind
+        for sock in server.sockets or []:
+            self._actual_port = sock.getsockname()[1]
+            break
+
+        self._stop_event = asyncio.Event()
+        self._server = server
+        self._ready.set()
+        log.info("Relay listening on %s:%d", self.host, self._actual_port)
+
+        await self._stop_event.wait()
+        server.close()
+        await server.wait_closed()
+
+    async def _handle_connection(self, ws) -> None:
+        """Dispatch incoming WebSocket to gossip hub or circuit relay."""
+        try:
+            path = ws.request.path
+        except AttributeError:
+            path = getattr(ws, "path", "/ws")
+
+        if path.startswith("/relay/"):
+            peer_id = path[len("/relay/"):]
+            await self._handle_circuit_relay(ws, peer_id)
+        elif path == "/health":
+            await ws.send(json.dumps({"status": "ok", "peers": len(self._registry)}))
+            await ws.close()
+        elif path == "/v1/peers":
+            await ws.send(json.dumps(self._registry.list_peers()))
+            await ws.close()
+        else:
+            await self._handle_gossip(ws)
+
+    async def _handle_gossip(self, ws) -> None:
+        """Accept a gossip peer connection, register it, and fan out messages."""
+        peer_id: str | None = None
+        peer_addr: str = ""
+
+        try:
+            async for raw in ws:
+                try:
+                    envelope = json.loads(raw)
+                except (json.JSONDecodeError, TypeError):
+                    continue
+
+                topic = envelope.get("topic", "")
+                from_peer = envelope.get("from_peer", "")
+
+                # Handle peer registration message
+                if topic == "peer-register":
+                    payload = envelope.get("payload", {})
+                    peer_id = payload.get("peer_id") or from_peer
+                    peer_addr = payload.get("addr", "")
+                    if len(self._registry) >= self.max_peers:
+                        await ws.close(1008, "relay at capacity")
+                        return
+                    self._registry.register(peer_id, peer_addr, ws)
+                    log.debug("Peer registered: %s", peer_id)
+                    # Send current peer list back
+                    await ws.send(json.dumps({
+                        "topic": "peer-list",
+                        "version": 1,
+                        "from_peer": "relay",
+                        "payload": {"peers": self._registry.list_peers()},
+                    }))
+                    continue
+
+                # Fan out to all other registered peers
+                if peer_id:
+                    self._registry.touch(peer_id)
+                fan_out_peers = self._registry.all_except(peer_id or "")
+                await _broadcast(raw, fan_out_peers)
+
+        except Exception as exc:
+            log.debug("Gossip connection error: %s", exc)
+        finally:
+            if peer_id:
+                self._registry.unregister(peer_id)
+                log.debug("Peer unregistered: %s", peer_id)
+
+    async def _handle_circuit_relay(self, ws_requester, target_peer_id: str) -> None:
+        """Proxy WebSocket traffic between ws_requester and target_peer_id's ws."""
+        target = self._registry.get(target_peer_id)
+        if target is None:
+            try:
+                await ws_requester.send(json.dumps({
+                    "error": f"peer {target_peer_id!r} not connected to relay"
+                }))
+                await ws_requester.close(1011, "target peer not found")
+            except Exception:
+                pass
+            return
+
+        log.debug("Circuit relay: ??? → %s", target_peer_id)
+
+        async def pipe(src, dst) -> None:
+            try:
+                async for msg in src:
+                    await dst.send(msg)
+            except Exception:
+                pass
+
+        await asyncio.gather(
+            pipe(ws_requester, target.ws),
+            pipe(target.ws, ws_requester),
+            return_exceptions=True,
+        )
+
+
+async def _broadcast(raw: str | bytes, peers: list) -> None:
+    """Send raw message to all peers; ignore individual send failures."""
+    if not peers:
+        return
+    import asyncio
+    await asyncio.gather(
+        *[_safe_send(p.ws, raw) for p in peers],
+        return_exceptions=True,
+    )
+
+
+async def _safe_send(ws, msg) -> None:
+    try:
+        await ws.send(msg)
+    except Exception:
+        pass

packages/relay/pyproject.toml

@@ -0,0 +1,20 @@
+[build-system]
+requires = ["setuptools>=64"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "meshnet-relay"
+version = "0.1.0"
+description = "Distributed Inference Network NAT-traversal relay and gossip hub"
+requires-python = ">=3.10"
+
+dependencies = [
+    "websockets>=13",
+]
+
+[project.scripts]
+meshnet-relay = "meshnet_relay.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["meshnet_relay*"]

packages/tracker/meshnet_tracker/server.py

@@ -59,6 +59,7 @@ class _NodeEntry:
         "score", "vram_bytes", "ram_bytes", "quantizations",
         "benchmark_tokens_per_sec", "quantization", "managed_assignment",
         "pending_directives", "last_heartbeat", "tracker_mode",
+        "relay_addr", "cert_fingerprint", "peer_id",
     )
 
     def __init__(
@@ -81,6 +82,9 @@ class _NodeEntry:
         tracker_mode: bool = False,
         hf_repo: str | None = None,
         num_layers: int | None = None,
+        relay_addr: str | None = None,
+        cert_fingerprint: str | None = None,
+        peer_id: str | None = None,
     ) -> None:
         self.node_id = node_id
         self.endpoint = endpoint
@@ -100,6 +104,9 @@ class _NodeEntry:
         self.tracker_mode = tracker_mode
         self.hf_repo = hf_repo
         self.num_layers = num_layers
+        self.relay_addr = relay_addr
+        self.cert_fingerprint = cert_fingerprint
+        self.peer_id = peer_id
         self.pending_directives: list[dict] = []
         self.last_heartbeat: float = time.monotonic()
 
@@ -914,6 +921,9 @@ class _TrackerHandler(http.server.BaseHTTPRequestHandler):
             except (TypeError, ValueError):
                 self._send_json(400, {"error": "num_layers must be an integer"})
                 return
+        relay_addr = body.get("relay_addr") or None
+        cert_fingerprint = body.get("cert_fingerprint") or None
+        peer_id = body.get("peer_id") or None
 
         node_id = _node_id_for_registration(
             endpoint,
@@ -942,6 +952,9 @@ class _TrackerHandler(http.server.BaseHTTPRequestHandler):
             tracker_mode=tracker_mode,
             hf_repo=hf_repo,
             num_layers=num_layers,
+            relay_addr=relay_addr,
+            cert_fingerprint=cert_fingerprint,
+            peer_id=peer_id,
         )
         with server.lock:
             self._purge_expired_nodes()
@@ -990,6 +1003,13 @@ class _TrackerHandler(http.server.BaseHTTPRequestHandler):
 
     def _handle_heartbeat(self, node_id: str):
         server: _TrackerHTTPServer = self.server  # type: ignore[assignment]
+        body: dict = {}
+        content_length = int(self.headers.get("Content-Length", 0))
+        if content_length > 0:
+            try:
+                body = json.loads(self.rfile.read(content_length))
+            except Exception:
+                pass
         with server.lock:
             self._purge_expired_nodes()
             entry = server.registry.get(node_id)
@@ -997,6 +1017,12 @@ class _TrackerHandler(http.server.BaseHTTPRequestHandler):
                 self._send_json(404, {"error": "node not found"})
                 return
             entry.last_heartbeat = time.monotonic()
+            if body.get("relay_addr"):
+                entry.relay_addr = body["relay_addr"]
+            if body.get("cert_fingerprint"):
+                entry.cert_fingerprint = body["cert_fingerprint"]
+            if body.get("peer_id"):
+                entry.peer_id = body["peer_id"]
             _rebalance_model_locked(server, entry.model or "stub-model")
             directives = list(entry.pending_directives)
             entry.pending_directives.clear()