Customize the Sandbox Network Policy

Add, remove, or modify the endpoints the sandbox can reach.

The NemoClaw repository declares the sandbox policy in a YAML file, and NVIDIA OpenShell enforces it at runtime. NemoClaw supports both static policy changes that persist across restarts and dynamic updates applied to a running sandbox through the OpenShell CLI.

Prerequisites

• A running NemoClaw sandbox for dynamic changes, or the NemoClaw source repository for static changes.
• The OpenShell CLI on your PATH.

[!IMPORTANT] Make static policy edits on the host, not inside the sandbox. The sandbox image includes a small set of operational tools such as vi, jq, and dos2unix, but host-side policy files remain the durable source of truth. The sandbox discards changes made only inside the sandbox when it is recreated.

Static Changes

Static changes modify the baseline policy file and take effect after the next sandbox creation.

Edit the Policy File

Open nemoclaw-blueprint/policies/openclaw-sandbox.yaml and add or modify endpoint entries.

To include a built-in preset in the baseline policy, merge its network_policies entries into this file and re-run nemoclaw onboard.

To apply a preset to a running sandbox, use nemoclaw <name> policy-add under Dynamic Changes. That updates the live policy and does not edit openclaw-sandbox.yaml.

Edit YAML manually when you need to allow custom hosts that a preset does not cover, such as an internal API or a weather service.

Each entry in the network section defines an endpoint group with the following fields:

endpoints : Host and port pairs that the sandbox can reach.

binaries : Executables allowed to use this endpoint.

rules : HTTP methods and paths that are permitted.

allow_encoded_slash : Allows percent-encoded slashes such as %2F in request paths. Leave this disabled unless the service uses encoded slashes as part of its documented route format, such as ClawHub scoped package names.

Re-Run Onboard

Apply the updated policy by re-running the onboard wizard:

$
nemoclaw onboard

The wizard reads the modified policy file and applies it to the sandbox.

Verify the Policy

Check that the sandbox is running with the updated policy:

$
nemoclaw <name> status

Add Blueprint Policy Additions

If you maintain a custom blueprint, add extra policy entries under components.policy.additions in nemoclaw-blueprint/blueprint.yaml. NemoClaw validates those entries with the same policy schema used by preset files, fetches the live policy during sandbox creation, merges the additions into network_policies, and applies the merged policy through OpenShell. The applied additions are recorded in the run metadata so you can audit which blueprint-level policy entries were active for that sandbox run.

Dynamic Changes

Dynamic changes apply a policy update to a running sandbox without restarting it.

[!WARNING] openshell policy set replaces the sandbox’s live policy with the contents of the file you provide. It does not merge. A running sandbox’s live policy is the baseline policy plus every preset that was layered on during onboarding. Applying a file that contains only the baseline (or only a single preset) silently drops every other preset that was in effect.

Add a Preset File with policy-add (Recommended)

This path preserves existing policy entries and is the only NemoClaw-supported flow for merging new entries into a running policy.

1. Create a preset-format YAML file under nemoclaw-blueprint/policies/presets/, for example nemoclaw-blueprint/policies/presets/influxdb.yaml:

   1
   preset:
   2
     name: influxdb
   3
     description: "InfluxDB time-series database"
   4
   network_policies:
   5
     influxdb:
   6
       name: influxdb
   7
       endpoints:
   8
         - host: influxdb.internal.example.com
   9
           port: 8086
   10
           protocol: rest
   11
           enforcement: enforce
   12
           rules:
   13
             - allow: { method: GET, path: "/**" }
   14
             - allow: { method: POST, path: "/api/v2/write" }
   15
       binaries:
   16
         - { path: /usr/bin/curl }

2. Apply it to the running sandbox:

$
nemoclaw my-assistant policy-add

NemoClaw reads the round-trippable base policy with openshell policy get --base, structurally merges your preset’s network_policies into it, and writes the merged result back. Provider-composed _provider_* entries are excluded because OpenShell reserves that namespace and rejects it in policy set. Existing presets and the baseline remain in place. The preset file under presets/ also persists across sandbox recreations.

Custom Recipe: URL-Based MCP Server

Adding a Streamable HTTP MCP server URL to OpenClaw (for example https://mcp.example.com/mcp) can result in the sandbox proxy denying the CONNECT tunnel with HTTP 403 Forbidden because the target host is not in the default allowlist. The symptom in ~/.openclaw/logs or in the MCP tool output is:

CONNECT tunnel failed, response 403

This recipe applies only when URL-based MCP traffic uses the sandbox proxy and fails with that CONNECT 403 response. An OAuth MCP login failure such as getaddrinfo EAI_AGAIN, or any direct-DNS path that bypasses the proxy, is a separate transport problem and is not fixed by widening this allowlist.

Add a preset with the MCP host, the exact Streamable HTTP MCP route, the HTTP methods that route uses (GET, POST, and DELETE), and only the process binary that opens the connection. Streamable HTTP MCP clients can use DELETE on the same endpoint to terminate a session, so keep that method scoped to the exact MCP route instead of widening the path:

1
preset:
2
  name: my-mcp
3
  description: "Custom URL-based MCP server"
4
network_policies:
5
  my_mcp:
6
    name: my_mcp
7
    endpoints:
8
      - host: mcp.example.com
9
        port: 443
10
        protocol: rest
11
        enforcement: enforce
12
        rules:
13
          - allow: { method: GET, path: "/mcp" }
14
          - allow: { method: POST, path: "/mcp" }
15
          - allow: { method: DELETE, path: "/mcp" }
16
    binaries:
17
      - { path: /usr/local/bin/node }

Save it under nemoclaw-blueprint/policies/presets/my-mcp.yaml and apply it to the running sandbox:

$
nemoclaw my-assistant policy-add --from-file nemoclaw-blueprint/policies/presets/my-mcp.yaml

NemoClaw prompts for confirmation because the preset targets a custom host that is not part of the vetted allowlist, then reports Widening sandbox egress — adding: mcp.example.com. For a publicly routed host that passes the separate SSRF checks, re-invoke the MCP tool and confirm that the CONNECT tunnel to mcp.example.com:443 succeeds.

Export, Edit, and Set the Base Policy

Use this path only when you cannot add a file under the NemoClaw source tree. Start from the current base policy so the presets layered on at onboarding stay in the file you apply. Requires OpenShell 0.0.72+ for the round-trippable policy get --base and policy set --wait syntax. Use NemoClaw to validate the base policy and strip the OpenShell metadata header before writing your editable copy.

$
nemoclaw my-assistant policy-get > current-policy.yaml

The command exits non-zero instead of emitting a partial policy when retrieval or validation fails. Do not use --raw for this workflow because raw output retains the metadata header.

Edit current-policy.yaml to add your entries under network_policies:, keeping the existing version field intact, then apply:

$
openshell policy set --policy current-policy.yaml --wait my-assistant

Scope of Dynamic Changes

Dynamic changes apply only to the current session. When the sandbox stops, the running policy resets to the baseline policy plus the presets recorded for the sandbox. Custom presets applied through nemoclaw <sandbox> policy-add --from-file or --from-dir are recorded with the sandbox, including their full YAML content. Snapshot restore and rebuild replay those recorded presets, so they survive sandbox recreation even if the original files are no longer on disk. For permanent baseline changes that apply to every future sandbox, edit the source policy for the target agent and re-run nemoclaw onboard.

Approve Requests Interactively

For one-off access, approve blocked requests in the OpenShell TUI instead of editing the baseline policy:

$
openshell term

Use this flow to test a destination before you decide whether it belongs in a permanent preset or custom policy file.

Policy Presets

NemoClaw ships preset policy files for common integrations in nemoclaw-blueprint/policies/presets/. Apply a preset as-is or use it as a starting template for a custom policy. For guided post-install examples, refer to Common Integration Policy Examples.

During onboarding, the policy tier you select determines which presets are enabled by default. You can add or remove individual presets in the interactive preset screen that follows tier selection. Built-in preset choices are scoped to the sandbox’s active agent, so unsupported messaging channel presets do not appear in policy-list or the interactive policy-add picker for agents without matching channel policy files.

Available presets:

To apply a preset to a running sandbox:

$
nemoclaw <name> policy-add

For example, to interactively add PyPI access to a running sandbox:

$
nemoclaw my-assistant policy-add

To list which presets are applied to a sandbox:

$
nemoclaw <name> policy-list

To include a preset in the baseline, merge its entries into openclaw-sandbox.yaml and re-run nemoclaw onboard.

For scripted workflows, policy-add and policy-remove accept the preset name as a positional argument:

$
nemoclaw my-assistant policy-add pypi --yes
$
nemoclaw my-assistant policy-remove pypi --yes

Set NEMOCLAW_NON_INTERACTIVE=1 instead of --yes to drive the same flow from an environment variable. Refer to Commands for the full flag reference.

nemoclaw <name> rebuild reapplies every policy preset to the recreated sandbox, so presets survive an agent-version upgrade without manual reapplication.

Custom Preset Files

Apply a user-authored preset YAML file to a running sandbox without editing the baseline or using openshell policy set.

Authoring

A custom preset follows the same shape as the built-in ones under nemoclaw-blueprint/policies/presets/:

1
preset:
2
  name: my-internal-api
3
  description: "Internal service"
4
network_policies:
5
  my-internal-api:
6
    name: my-internal-api
7
    endpoints:
8
      - host: api.example.internal
9
        port: 443
10
        protocol: rest
11
        enforcement: enforce
12
        rules:
13
          - allow: { method: GET, path: "/**" }
14
    binaries:
15
      - { path: /usr/local/bin/node }

The top-level preset.name must be a lowercase RFC 1123 label (letters, digits, hyphens) and must not collide with a built-in preset name such as slack or pypi. Rename preset.name if NemoClaw refuses to apply the file because of a collision. Each endpoint must name a specific host or a scoped subdomain wildcard such as *.example.com. NemoClaw rejects catch-all destinations including *, 0.0.0.0, 0.0.0.0/0, ::, and ::/0 before it applies a custom preset. Rule matchers must match the endpoint protocol. REST and WebSocket rules require method and path; REST accepts standard HTTP methods or *, while WebSocket accepts GET, WEBSOCKET_TEXT, or *. JSON-RPC rules accept only method, and MCP rules accept method plus optional tool or params.name matchers. The same protocol-specific matcher shape applies to deny_rules. User-authored presets must not declare allowed_ips for ordinary endpoints. NemoClaw rejects that field in files passed through --from-file or --from-dir because it can widen the private-address ranges that OpenShell checks during SSRF protection. Use hostnames, ports, protocols, methods, paths, and binary restrictions instead. The only exception is the host.openshell.internal bridge endpoint used for explicit sandbox-to-host service access.

Apply a Single File

$
nemoclaw my-assistant policy-add --from-file ./presets/my-internal-api.yaml

Use --dry-run to preview endpoints without applying changes. Use --yes or export NEMOCLAW_NON_INTERACTIVE=1 to skip the confirmation prompt.

Apply Every File in a Directory

$
nemoclaw my-assistant policy-add --from-dir ./presets/ --yes

NemoClaw processes files in lexicographic order. Processing stops at the first failure. NemoClaw does not roll back presets that were already applied. Fix the failing file and re-run the command to continue.

Remove a Custom Preset

NemoClaw records custom presets applied with --from-file or --from-dir in the sandbox registry alongside their full YAML content. Remove them by name without keeping the original file on disk:

$
nemoclaw my-assistant policy-remove my-internal-api --yes

policy-remove accepts both built-in and custom preset names. Run nemoclaw <name> policy-list to see every preset currently applied to the sandbox.

Agent Policy Context

When an agent runs in the sandbox, it needs a compact view of the active policy so it can decide whether a host or integration is allowed and what to suggest when something fails. nemoclaw <name> policy-explain prints that view as a redacted summary. The summary includes the recorded tier, applied presets and their allowed host categories, known presets that are not applied, inspect/add/remove commands that change policy, and support boundaries between NemoClaw, OpenShell, and the agent.

$
nemoclaw my-assistant policy-explain

Pass --json to emit the same context as a structured object the agent can read:

$
nemoclaw my-assistant policy-explain --json

During onboarding, NemoClaw seeds the rendered context inside the sandbox at /sandbox/.openclaw/workspace/POLICY.md. It refreshes that file on every policy-add or policy-remove, so the in-sandbox agent picks it up when it scans the workspace. Pass --write to refresh that file on demand without changing the policy:

$
nemoclaw my-assistant policy-explain --write

The output is intentionally redacted. Network policy rule bodies, credential metadata, and binary allowlists are not included. Only host stems and category-level summaries appear. Host stems that resolve to RFC 1918 ranges (10/8, 172.16/12, 192.168/16), loopback (127/8, ::1), link-local (169.254/16, fe80::/10), cloud metadata (169.254.169.254), unique-local IPv6 (fc00::/7), reserved zero (0.0.0.0/8), CGNAT (100.64/10), benchmarking (198.18/15), localhost, and the internal DNS suffixes .local, .internal, .lan, .home, .home.arpa, .corp, .intra, .intranet, .localdomain are dropped from allowedHostCategories and surface as a redactedHostCount.

Each active preset also carries a verification field that tells the agent whether the OpenShell gateway actually enforces it:

The context also documents how the agent should classify a failed host or integration attempt. The classifier evaluates rules in order so HTTP 403 has a single interpretation per call. When the host matches an applied preset, the request is treated as an authentication failure. Otherwise, the request is treated as a policy denial.

1. unsupported: The caller asserts the capability is not offered for this sandbox, such as a messaging channel that the active agent does not support. The agent should surface the limitation without retrying.
2. missing-approval: The host is allowed by an applied preset and the request was refused with HTTP 401. The network path is open. Credentials are missing or invalid.
3. missing-approval (low confidence): The host is allowed by an applied preset and the request was refused with HTTP 403. This is ambiguous because OpenShell policies enforce by method, path, protocol, and binary, so a 403 on an allowed host can still be a finer-grained policy denial rather than missing credentials. Confirm credentials first, then run openshell policy get to check whether the specific method or path is blocked.
4. blocked-by-policy: Either the host is not allowed by any applied preset and either an existing built-in or custom preset declares it (apply that preset), or the request is refused with a network-block error code (EHOSTUNREACH, ENETUNREACH, ENOTFOUND, ECONNREFUSED, ETIMEDOUT, EAI_AGAIN) or HTTP 403. The same network-block codes also surface as blocked-by-policy (low confidence) when the host is on an applied but unverified preset (registry-only or gateway-unavailable), because a block code on a host the registry says should be allowed is the strongest signal that the gateway is not enforcing the preset.
5. unknown: None of the above apply. The agent should surface the underlying error. A network-block code on a host that matches a verified preset stays unknown because the gateway has confirmed enforcement, so the block must be an upstream connectivity failure rather than a policy denial.

Each classification also carries a confidence field set to high or low. Low-confidence verdicts mean the agent should report multiple possibilities to the user instead of treating the next-step recommendation as authoritative. Common low-confidence triggers are:

• HTTP 403 on an active host (ambiguous between missing credentials and a finer-grained OpenShell denial by method, path, protocol, or binary).
• The matched preset is registry-only (the registry lists it but the gateway does not enforce it), so the agent must not assume the host is reachable.
• The matched preset is gateway-unavailable (no live gateway snapshot was available), so the verdict is registry-derived and advisory.

Callers that already hold a verified gateway snapshot can pass it to the classifier so verdicts about hosts on verified presets stay high-confidence.

Use the classification to pick the next step. For blocked-by-policy, run nemoclaw <name> policy-add <preset> or author a custom preset. For missing-approval, confirm the API token and scopes for the integration. For unsupported, surface the limitation to the user without retrying.

Related Topics

• Approve or Deny Agent Network Requests for real-time operator approval.
• Common Integration Policy Examples for maintained preset examples such as Outlook, messaging, GitHub, Jira, web search, package managers, Hugging Face, and local inference.
• Network Policies for the full baseline policy reference.
• OpenShell Policy Schema for the full YAML policy schema reference.
• OpenShell Sandbox Policies for applying, iterating, and debugging policies at the OpenShell layer.