Description

[Description]
The “Approve or Deny Agent Network Requests” documentation correctly explains that OpenShell intercepts agent network requests and surfaces them in the TUI for operator approval, but it omits two important clarifications: (1) that TUI approvals are strictly session-only and must be reflected in the YAML/presets to persist across sandbox restarts, and (2) that the ./scripts/walkthrough.sh helper script must be run from the NemoClaw repository root with an existing sandbox, not just “anywhere with NVIDIA_API_KEY set.” This can lead users to misinterpret the durability of approvals and to encounter avoidable errors when running the walkthrough.

[Environment]
Docs page: “Approve or Deny Agent Network Requests” in the NemoClaw documentation
Related docs: “Customize the Sandbox Network Policy” and network policy overview pages
Product versions: Any NemoClaw + OpenShell version with network policy support and the walkthrough.sh script present in scripts/

[Steps to Reproduce]

1. Read the “Approve or Deny Agent Network Requests” page and follow the instructions:
   • Start a NemoClaw sandbox and ensure OpenShell is on the PATH.
   • Run openshell term to open the TUI and monitor sandbox activity.
   • Trigger a blocked network request from an agent so that the TUI displays an approval prompt.
2. Approve a previously-blocked endpoint from the TUI and observe that it becomes allowed for the current sandbox session.
3. Stop the sandbox and either restart it or create a new sandbox, without editing the policy YAML or presets.
4. Attempt to use the same endpoint again and note that it is blocked again, despite having been approved earlier.
5. Separately, from an arbitrary directory (not the NemoClaw repo root), set NVIDIA_API_KEY and run:
   bash ./scripts/walkthrough.sh

   without first ensuring an onboarded sandbox exists.

[Expected Result]

• The doc clearly states that:
  • Approving an endpoint in openshell term updates only the in-memory, running policy for the current sandbox session.
  • To persist an approved endpoint across sandbox restarts or new sandboxes, the user must explicitly update the policy YAML or apply a preset, as described in “Customize the Sandbox Network Policy.”
• The walkthrough instructions state that:
  • ./scripts/walkthrough.sh must be run from the NemoClaw repository root, where the scripts/ directory lives.
  • At least one sandbox must already be onboarded and reachable; the script assumes the presence of a running NemoClaw environment plus NVIDIA_API_KEY, not just the latter alone.

[Actual Result]

• The page says:

  “Approved endpoints remain in the running policy until the sandbox stops. They are not persisted to the baseline policy file.”
  but it does not explicitly tie this to the broader guidance about updating policy via YAML or presets, nor does it warn that approvals alone are not a way to permanently modify policy. Users unfamiliar with the rest of the docs can easily assume approvals are the main mechanism for updating policy and may be surprised when their approvals disappear after the sandbox stops.

• The walkthrough section states:

  “To observe the approval flow in a guided session, run the walkthrough script: ./scripts/walkthrough.sh … The walkthrough requires tmux and the NVIDIA_API_KEY environment variable.”
  It does not mention that the command must be run from the NemoClaw repo root, nor that an onboarded sandbox is required. This can lead to “file not found” (if run from another directory) or to “no sandbox/agent available” behavior that doesn’t match the description of a split tmux session with an active agent on the right and the TUI on the left.

[Impact / Notes]

• Impact:
  • Operators and QA may misinterpret the durability of approvals, believing they have updated the “real” network policy when they have only modified the session ephemeral state.
  • New users running ./scripts/walkthrough.sh can run into avoidable errors or confusion because directory and sandbox prerequisites are implicit rather than explicit.
• The underlying implementation is correct (session-only approvals and repo-root script location), so this is a documentation clarity issue, not a functional defect.
• Suggested fixes:
  • Add a sentence to the approvals section such as:

    “Approvals in the TUI are session-only. To keep an endpoint allowed across sandbox restarts, update your sandbox policy YAML or apply a policy preset as described in Customize the Sandbox Network Policy.”
    

    
    
    • 
      Update the walkthrough section to say:
      

      “From the NemoClaw repository root, run ./scripts/walkthrough.sh after you have onboarded at least one sandbox and set NVIDIA_API_KEY. The script opens tmux with the TUI on the left and an agent session on the right.”

      
      

    
    

    
    

Bug Details

[NVB#6188832]