docs: document policy path for host services (#1551)

[yanyunl1991]

Summary

Document the recommended path for accessing host-side HTTP services from a NemoClaw sandbox through the normal OpenShell policy/proxy flow. This avoids recommending direct host.docker.internal access, which bypasses policy enforcement and may not be reachable in every sandbox runtime.

Related Issue

Fixes #1551

Changes

• Add troubleshooting guidance for host-side HTTP services.
• Show how to create a custom NemoClaw policy preset for a host IP and port.
• Document applying that preset with nemoclaw <sandbox> policy-add --from-file.
• Add a network-policy note that host.docker.internal should not be treated as a general host-service path.
• Regenerate the generated nemoclaw-user-* agent skills from the docs.

Type of Change

• Code change (feature, bug fix, or refactor)
• Code change with doc updates
• Doc only (prose changes, no code sample modifications)
• Doc only (includes code sample changes)

Verification

• npx prek run --all-files passes
• npm test passes
• Tests added or updated for new or changed behavior
• No secrets, API keys, or credentials committed
• Docs updated for user-facing behavior changes
• make docs builds without warnings (doc changes only)
• Doc pages follow the style guide (doc changes only)
• New doc pages include SPDX header and frontmatter (new pages only)

AI Disclosure

• AI-assisted — tool: Codex

Summary by CodeRabbit

• Documentation
  • Added guidance for configuring sandbox agents to access HTTP services on the host via the platform's network/proxy path.
  • Included steps for creating and applying custom network policy presets to allow host-service access and verify policy application.
  • Added troubleshooting diagnostics to distinguish policy matches from gateway reachability failures, plus warnings against bypassing the proxy with special hostnames or global no-proxy workarounds.

---

Signed-off-by: Yanyun Liao yanyunl@nvidia.com

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 3a66562a-4a1e-423b-8629-5ec10259f117

📥 Commits

Reviewing files that changed from the base of the PR and between e349a4c and 8d29744.

📒 Files selected for processing (4)

• .agents/skills/nemoclaw-user-manage-policy/SKILL.md
• .agents/skills/nemoclaw-user-reference/references/troubleshooting.md
• docs/network-policy/customize-network-policy.md
• docs/reference/troubleshooting.md

✅ Files skipped from review due to trivial changes (4)

• .agents/skills/nemoclaw-user-manage-policy/SKILL.md
• docs/network-policy/customize-network-policy.md
• docs/reference/troubleshooting.md
• .agents/skills/nemoclaw-user-reference/references/troubleshooting.md

---

📝 Walkthrough

Walkthrough

Adds documentation clarifying how a sandbox should reach HTTP services on the host via the OpenShell gateway and NemoClaw network policy preset workflow; includes CLI commands, diagnostic steps, and explicit warnings against using host-specific shortcuts that bypass OpenShell policy enforcement.

Changes

Cohort / File(s)	Summary
Agent skills docs .agents/skills/nemoclaw-user-manage-policy/SKILL.md, .agents/skills/nemoclaw-user-reference/references/troubleshooting.md	Adds notes and troubleshooting guidance instructing use of a host IP reachable by the OpenShell gateway, applying a NemoClaw policy preset via nemoclaw <sandbox> policy-add --from-file, requiring the calling binary in the policy binaries, and warning against host.docker.internal/host.openshell.internal and proxy bypass.
Public docs docs/network-policy/customize-network-policy.md, docs/reference/troubleshooting.md	Documents the proxy/policy-based path for host-service access: require service on a gateway-reachable non-loopback IP, shows a preset template and exact CLI to apply it, adds diagnostic checks (inspect openshell term transitions like policy_denied→upstream_unreachable), and discourages bypassing the proxy.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐇 I nibble docs and hop with cheer,
Preset in paw, the gateway's near.
No secret bridges on my map,
I follow rules — no sneaky gap.
Logs and policy keep the path clear.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Linked Issues check	⚠️ Warning	The PR partially addresses issue #1551's objectives. It documents the supported OpenShell policy/proxy flow path with examples and commands, but it does not document the Docker bridge path (host.docker.internal) that was the original request in the issue.	Add documentation explaining that host.docker.internal resolves to 172.17.0.1, clarify it bypasses OpenShell policy enforcement, and document host firewall requirements (UFW rules for Docker bridge subnet) as requested in #1551.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'docs: document policy path for host services (#1551)' directly and clearly describes the main change: adding documentation about the policy path for accessing host services, which is the primary objective across all modified documentation files.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to documenting host service access patterns. The modifications to troubleshooting guides, network policy docs, and agent skill documentation are all focused on the policy/proxy path recommendation without introducing unrelated changes.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/docs-host-bridge-networking-1551

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (4)

.agents/skills/nemoclaw-user-reference/references/troubleshooting.md (1)

739-739: Use active voice instead of passive.

Line 739: "After the policy is applied" uses passive voice.
Rewrite to active voice.

As per coding guidelines, "Active voice required. Flag passive constructions."

✏️ Suggested revision

-After the policy is applied, retry the request from inside the sandbox without disabling the proxy:
+After applying the policy, retry the request from inside the sandbox without disabling the proxy:

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In @.agents/skills/nemoclaw-user-reference/references/troubleshooting.md at line
739, Replace the passive phrase "After the policy is applied" with an
active-voice construction (e.g., "After you apply the policy") in the sentence
that begins "After the policy is applied, retry the request from inside the
sandbox without disabling the proxy"; ensure the updated sentence uses active
voice and retains the original meaning and instructions.

docs/reference/troubleshooting.md (1)

769-769: Use active voice instead of passive.

Line 769: "After the policy is applied" uses passive voice.
Rewrite to active voice.

As per coding guidelines, "Active voice required. Flag passive constructions."

✏️ Suggested revision

-After the policy is applied, retry the request from inside the sandbox without disabling the proxy:
+After applying the policy, retry the request from inside the sandbox without disabling the proxy:

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/reference/troubleshooting.md` at line 769, The sentence uses passive
voice ("After the policy is applied"); rewrite it in active voice by replacing
that phrase with an active construction such as "After you apply the policy" or
"Once you apply the policy" so the full sentence reads e.g. "After you apply the
policy, retry the request from inside the sandbox without disabling the proxy."
Locate the exact text "After the policy is applied, retry the request from
inside the sandbox without disabling the proxy:" and update it accordingly.

docs/network-policy/customize-network-policy.md (1)

30-34: Split line 31 into separate sentences for diff readability.

Line 31 contains two sentences on one line.
The style guide requires one sentence per line in source for readable diffs.

As per coding guidelines, "One sentence per line in source (makes diffs readable). Flag paragraphs where multiple sentences appear on the same line."

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/network-policy/customize-network-policy.md` around lines 30 - 34, The
note block containing "If the sandbox needs to reach an HTTP service running on
the host, expose the service on a host IP that the OpenShell gateway can reach
and apply a custom NemoClaw preset with `nemoclaw <sandbox> policy-add
--from-file`." has two sentences on the same source line; split that line into
two separate lines so each sentence is on its own line to satisfy the "one
sentence per line" style rule—edit the note paragraph (the block beginning with
"If the sandbox needs to reach an HTTP service running on the host...") and
break the combined sentence into two lines, preserving wording and punctuation.

.agents/skills/nemoclaw-user-manage-policy/SKILL.md (1)

77-79: Split line 77 into separate sentences for diff readability.

Line 77 contains two sentences on one line.
The style guide requires one sentence per line in source.

As per coding guidelines, "One sentence per line in source (makes diffs readable). Flag paragraphs where multiple sentences appear on the same line."

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In @.agents/skills/nemoclaw-user-manage-policy/SKILL.md around lines 77 - 79,
The paragraph in SKILL.md contains two sentences on the same line; split the
combined sentence that starts "If the sandbox needs to reach an HTTP service
running on the host, expose the service on a host IP that the OpenShell gateway
can reach and apply a custom NemoClaw preset with `nemoclaw <sandbox> policy-add
--from-file`." into two lines so each sentence is on its own line (keep the
first sentence about exposing the service on a host IP and the second sentence
about applying a custom NemoClaw preset), ensuring the existing wording and
inline code (`nemoclaw <sandbox> policy-add --from-file`) remain unchanged.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In @.agents/skills/nemoclaw-user-manage-policy/SKILL.md:
- Around line 77-79: The paragraph in SKILL.md contains two sentences on the
same line; split the combined sentence that starts "If the sandbox needs to
reach an HTTP service running on the host, expose the service on a host IP that
the OpenShell gateway can reach and apply a custom NemoClaw preset with
`nemoclaw <sandbox> policy-add --from-file`." into two lines so each sentence is
on its own line (keep the first sentence about exposing the service on a host IP
and the second sentence about applying a custom NemoClaw preset), ensuring the
existing wording and inline code (`nemoclaw <sandbox> policy-add --from-file`)
remain unchanged.

In @.agents/skills/nemoclaw-user-reference/references/troubleshooting.md:
- Line 739: Replace the passive phrase "After the policy is applied" with an
active-voice construction (e.g., "After you apply the policy") in the sentence
that begins "After the policy is applied, retry the request from inside the
sandbox without disabling the proxy"; ensure the updated sentence uses active
voice and retains the original meaning and instructions.

In `@docs/network-policy/customize-network-policy.md`:
- Around line 30-34: The note block containing "If the sandbox needs to reach an
HTTP service running on the host, expose the service on a host IP that the
OpenShell gateway can reach and apply a custom NemoClaw preset with `nemoclaw
<sandbox> policy-add --from-file`." has two sentences on the same source line;
split that line into two separate lines so each sentence is on its own line to
satisfy the "one sentence per line" style rule—edit the note paragraph (the
block beginning with "If the sandbox needs to reach an HTTP service running on
the host...") and break the combined sentence into two lines, preserving wording
and punctuation.

In `@docs/reference/troubleshooting.md`:
- Line 769: The sentence uses passive voice ("After the policy is applied");
rewrite it in active voice by replacing that phrase with an active construction
such as "After you apply the policy" or "Once you apply the policy" so the full
sentence reads e.g. "After you apply the policy, retry the request from inside
the sandbox without disabling the proxy." Locate the exact text "After the
policy is applied, retry the request from inside the sandbox without disabling
the proxy:" and update it accordingly.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 09f1ba92-2342-486d-b489-145d28ced381

📥 Commits

Reviewing files that changed from the base of the PR and between 0b49851 and e349a4c.

📒 Files selected for processing (4)

• .agents/skills/nemoclaw-user-manage-policy/SKILL.md
• .agents/skills/nemoclaw-user-reference/references/troubleshooting.md
• docs/network-policy/customize-network-policy.md
• docs/reference/troubleshooting.md

[ericksoa]

Approved. This documents the supported OpenShell policy/proxy path for host-side HTTP services and avoids recommending the unreliable/direct bridge path that bypasses policy and audit. The docs and generated skill updates are consistent, and the existing checks are green.