Walkthrough

Adds a Docker-network TCP probe and message formatter used during ollama-local onboarding to verify a sandbox container can reach the host Ollama auth proxy; failing TCP connectivity yields a formatted UFW remediation message and aborts onboarding.

Changes

Ollama Proxy Reachability Probing

Sequence Diagram(s)

sequenceDiagram
  participant Onboard as OnboardingWizard
  participant Probe as probeOllamaProxySandboxReachability
  participant DockerNet as DockerNetworkInspect
  participant DockerRun as DockerRun(container)
  participant Busybox as busybox nc
  participant Host as HostAuthProxy

  Onboard->>Probe: invoke probe after persisting proxy token
  Probe->>DockerNet: docker network inspect (get IPAM/gateway)
  alt network/gateway present
    Probe->>DockerRun: docker run --network <name> --add-host host-gateway:<ip|host-gateway> busybox nc host-gateway:PORT
    DockerRun->>Busybox: spawn nc inside container
    Busybox->>Host: TCP connect to host:PORT
    alt connection OK
      Host-->>Busybox: accept (nc exit 0)
      Busybox-->>DockerRun: exit 0
      DockerRun-->>Probe: success => {reason: "ok"}
      Probe-->>Onboard: returns ok
    else connection refused/blocked
      Host-->>Busybox: refuse/timeout (nc exit 1)
      Busybox-->>DockerRun: exit 1
      DockerRun-->>Probe: exit 1 => {reason: "tcp_failed", subnet}
      Probe-->>Onboard: returns tcp_failed
    end
  else probe unavailable
    DockerNet-->>Probe: missing/invalid => {reason: "probe_unavailable"}
    Probe-->>Onboard: returns probe_unavailable
  end

Estimated Code Review Effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• NVIDIA/NemoClaw#2442: Also modifies onboarding around Ollama proxy readiness checks (adds port readiness polling).

Suggested Labels

fix, Provider: Ollama, Docker, Local Models, Platform: Brev

Suggested Reviewers

• ericksoa
• jyaunches

Poem

🐰 I hopped through Docker's tangled net,
Ran a tiny probe to see what's set.
If proxy's blocked and packets fail,
I script the ufw rule to lift the veil.
Onboard halts with guidance—now that's a win!

❌ Failed checks (1 warning)

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

Pi Semantic E2E Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required E2E

• gpu-e2e: Exercises real Linux native onboard with provider=ollama, which is exactly the codepath where the new probeOllamaProxySandboxReachability() now runs before inference set. A regression in the probe (e.g., docker run flags, host-gateway detection, or hard exit on tcp_failed) would block local Ollama onboarding end-to-end.
• ollama-proxy-e2e: Manual workflow that explicitly validates the auth proxy chain on port 11435 including a Phase 8 'container reachability check' step. The new sandbox-side probe targets exactly this proxy via host.openshell.internal:11435 and shares the bridge-network reachability semantics.
• test-e2e-ollama-proxy: Default PR job that runs the auth proxy E2E harness on every PR. Covers token, proxy auth, and reachability behavior the new probe depends on.

Optional E2E

• gpu-double-onboard-e2e: Re-onboard path re-enters setupInference, so the new probe runs a second time. The PR's inline comment explicitly relies on isInferenceRouteReady() staying false on probe failure so retries re-run the probe — this job validates token consistency across re-onboard and is the natural place to exercise that.
• onboard-resume-e2e: The added comment explicitly references --resume behavior: 'a retry (including --resume) re-enters setupInference and re-runs this check'. Validates resume semantics around the probe.
• onboard-repair-e2e: Repair flows can re-invoke setupInference for ollama-local; useful confidence check that the new probe interacts cleanly with repair-time provider validation.
• wsl-e2e: Sanity check that the probe remains correctly skipped on WSL (the new code is gated by !isWsl()).
• macos-e2e: On macOS Docker Desktop the probe should classify failures as probe_unavailable (host-gateway mode), never tcp_failed. Confidence check that onboard does not now hard-exit on Mac due to the probe.

New E2E recommendations

• firewall-remediation (medium): No existing E2E exercises a Linux host where UFW (or equivalent) actually blocks the Docker bridge → 11435 path. Without such a test, the tcp_failed branch — which causes process.exit(1) and prints the new ufw remediation — is only covered by unit tests with stubbed runImpl. A regression here could either silently drop the actionable error or wrongly hard-exit healthy onboards.
  • Suggested test: Add a Linux E2E (e.g., test/e2e/test-ollama-proxy-firewall-block.sh wired into nightly-e2e.yaml) that: (1) installs UFW and adds a default-deny + allow loopback rule that blocks the docker bridge subnet from reaching 11435, (2) runs nemoclaw onboard --provider ollama-local --non-interactive, (3) asserts onboard exits non-zero, isInferenceRouteReady() stays false, and stderr contains both the network subnet and 'sudo ufw allow' guidance, then (4) removes the UFW rule and asserts a follow-up --resume succeeds because setupInference re-runs the probe.
• sandbox-network (low): The probe relies on the OpenShell Docker network being named via OPENSHELL_DOCKER_NETWORK_NAME (default openshell-docker) and on the busybox image being pullable. No existing E2E asserts that the probe degrades to probe_unavailable (rather than failing onboard) when the network is missing or the image cannot be pulled.
  • Suggested test: Extend test-ollama-auth-proxy-e2e.sh (or add a sibling case) to run the probe path with (a) a non-existent OPENSHELL_DOCKER_NETWORK_NAME and (b) docker network present but proxy unreachable in host-gateway mode, asserting that onboard treats both as probe_unavailable and continues without exiting.

Dispatch hint

• Workflow: nightly-e2e.yaml
• jobs input: gpu-e2e,gpu-double-onboard-e2e,onboard-resume-e2e,onboard-repair-e2e