docs(debug-inference): generalize firewall section to cover any host firewall tooling

Author: pimlock

.agents/skills/debug-inference/SKILL.md

@@ -224,15 +224,15 @@ This failure commonly appears on Linux hosts that:
 
 - Run the OpenShell gateway in Docker
 - Route `inference.local` to a host-local OpenAI-compatible endpoint such as Ollama
-- Use UFW or another host firewall with default incoming or routed traffic denied
+- Have a host firewall or networking configuration that denies container-to-host traffic by default
 
 In this case, OpenShell routing is usually working correctly. The failing hop is container-to-host traffic on the backend port.
 
 ### Why CoreDNS Is Not the Cause
 
 This is not the same issue as the Colima CoreDNS fix.
 
-OpenShell injects `host.docker.internal` and `host.openshell.internal` into sandbox pods with `hostAliases`. That path bypasses cluster DNS lookup. If the request still times out, the usual cause is host firewall policy, not CoreDNS.
+OpenShell injects `host.docker.internal` and `host.openshell.internal` into sandbox pods with `hostAliases`. That path bypasses cluster DNS lookup. If the request still times out, the usual cause is host firewall or network policy, not CoreDNS.
 
 ### Verify the Problem
 
@@ -254,29 +254,27 @@ OpenShell injects `host.docker.internal` and `host.openshell.internal` into sand
    docker exec openshell-cluster-<gateway> wget -qO- -T 5 http://host.docker.internal:11434/v1/models
    ```
 
-If steps 1 and 2 succeed but step 3 times out, host firewall policy is blocking the container-to-host path.
+If steps 1 and 2 succeed but step 3 times out, the host firewall or network configuration is blocking the container-to-host path.
 
 ### Fix
 
-Allow the OpenShell cluster bridge network to reach the host-local inference port.
+Allow the Docker bridge network used by the OpenShell cluster to reach the host-local inference port. The exact command depends on your firewall tooling (iptables, nftables, firewalld, UFW, etc.), but the rule should allow:
 
-Example narrow UFW rule:
+- **Source**: the Docker bridge subnet used by the OpenShell cluster container (commonly `172.18.0.0/16`)
+- **Destination**: the host gateway IP injected into sandbox pods for `host.docker.internal` (commonly `172.17.0.1`)
+- **Port**: the inference server port (e.g. `11434/tcp` for Ollama)
 
-```bash
-sudo ufw allow proto tcp \
-  from 172.18.0.0/16 \
-  to 172.17.0.1 \
-  port 11434 \
-  comment 'OpenShell local inference'
-```
+To find the actual values on your system:
 
-This example matches a common local layout:
+```bash
+# Docker bridge subnet for the OpenShell cluster network
+docker network inspect $(docker network ls --filter name=openshell -q) --format '{{range .IPAM.Config}}{{.Subnet}}{{end}}'
 
-- `172.18.0.0/16`: the Docker bridge subnet used by the OpenShell cluster container
-- `172.17.0.1`: the host gateway IP injected into sandbox pods for `host.docker.internal`
-- `11434/tcp`: the default Ollama port
+# Host gateway IP visible from inside the container
+docker exec openshell-cluster-<gateway> cat /etc/hosts | grep host.docker.internal
+```
 
-Adjust the source subnet, destination IP, or port if your local Docker network differs.
+Adjust the source subnet, destination IP, or port to match your local Docker network layout.
 
 ### Verify the Fix
 
@@ -294,27 +292,13 @@ Adjust the source subnet, destination IP, or port if your local Docker network d
 
 Both commands should return the upstream model list.
 
-### Check the Active Firewall Rule
-
-```bash
-sudo ufw status numbered
-```
-
-You should see a rule similar to:
-
-```
-172.17.0.1 11434/tcp  ALLOW IN  172.18.0.0/16
-```
-
 ### If It Still Fails
 
 - Confirm the backend listens on a host-reachable address: `ss -ltnp | rg ':11434\b'`
 - Confirm the provider points at the host alias path you expect: `openshell provider get <provider-name>`
 - Confirm the active inference route: `openshell inference get`
 - Inspect sandbox logs for upstream timeout details: `openshell logs <sandbox-name> --since 10m`
 
-If the host uses a firewall other than UFW, apply the equivalent allow rule for traffic from the Docker bridge network to the host-local inference port.
-
 ## Common Failure Patterns
 
 | Symptom | Likely cause | Fix |
@@ -327,7 +311,7 @@ If the host uses a firewall other than UFW, apply the equivalent allow rule for
 | `no compatible route` | Provider type does not match request shape | Switch provider type or change the client API |
 | Direct call to external host is denied | Missing policy or provider attachment | Update `network_policies` and launch sandbox with the right provider |
 | SDK fails on empty auth token | Client requires a non-empty API key even though OpenShell injects the real one | Use any placeholder token such as `test` |
-| Upstream timeout from container to host-local backend | Host firewall (UFW or similar) blocks container-to-host traffic | Allow the Docker bridge subnet to reach the inference port on the host gateway IP (see firewall fix section above) |
+| Upstream timeout from container to host-local backend | Host firewall or network config blocks container-to-host traffic | Allow the Docker bridge subnet to reach the inference port on the host gateway IP (see firewall fix section above) |
 
 ## Full Diagnostic Dump