feat(networking): add multi-host topology connectivity checks
- Dominant language
- TypeScript
- Stars
- 22.5k
- Forks
- 3.1k
- Avg merge
- 1d 1h
- Merged PRs (30d)
- 715
Description
## Summary
Add topology-aware connectivity checks for deployments where the NemoClaw CLI, OpenShell gateway, OpenClaw gateway/TUI, sandbox runtime, and inference endpoints may run across different hosts, ports, or network namespaces.
Parent: #2218
## Problem
In multi-host or multi-namespace deployments, operators can easily misconfigure gateway URLs, dashboard ports, sandbox routes, proxy settings, DNS, host aliases, or exposed service bindings.
Today these failures are hard to diagnose because the broken route is often discovered only after onboarding or connect/status commands fail. NemoClaw should detect the required hops and explain which one is broken.
## Related Issues
- #3053 Support multiple NemoClaw-managed instances on a single host
- #4865 Second `NEMOCLAW_GATEWAY_PORT` instance breaks first sandbox
- #3877 Could not connect to local service from inside sandbox
- #3953 Dashboard port preflight
- #2390 Dashboard Delivery Contract
## Proposed Scope
- Define the supported multi-host topology model for NemoClaw-managed deployments.
- Add a preflight or `nemoclaw doctor` style check for required connectivity between:
- NemoClaw CLI host,
- OpenShell gateway,
- OpenClaw gateway/TUI,
- sandbox runtime,
- inference/provider endpoints.
- Validate required ports, DNS/host aliases, proxy bypass rules, TLS/CA requirements, and dashboard reachability.
- Distinguish route failures from port conflicts, DNS failures, proxy denials, TLS failures, and sandbox policy denials where practical.
- Print actionable remediation or docs links when a required route is unavailable.
- Document the recommended production topology and expected port/host mapping.
## Non-goals
- Do not make arbitrary distributed/Kubernetes topologies fully supported by default.
- Do not replace operator-managed ingress, firewall, VPN, DNS, or certificate infrastructure.
- Do not solve multiple independent local sandboxes on one host beyond the checks needed for production topology validation.
## Acceptance Criteria
- [ ] Supported multi-host topology is documented.
- [ ] CLI/preflight/doctor checks verify required routes and ports.
- [ ] Failures identify which hop is broken.
- [ ] Checks distinguish DNS, port conflict, proxy, TLS/CA, and policy failures where possible.
- [ ] Output includes actionable remediation or docs links.
- [ ] At least one test or dry-run scenario covers a misconfigured route and verifies the reported failure reason.
Contributor guide
Assessment
This issue has not been assessed yet.