Document scoped network policies for sbx

content/manuals/ai/sandboxes/customize/build-an-agent.md

@@ -113,10 +113,10 @@ agent can't reach it.
 
 ## Allow network access
 
-The network block does two things: it lists the hosts the sandbox is
-allowed to reach (`allowedDomains`), and it wires the kit-side half of
-the auth flow from [Plan authentication](#plan-authentication)
-(`serviceDomains` + `serviceAuth`).
+The network block does two things: it lists the hosts the sandbox can
+reach (`allowedDomains`), and it wires the kit-side half of the auth flow
+from [Plan authentication](#plan-authentication) with `serviceDomains` and
+`serviceAuth`.
 
 ```yaml
 network:
@@ -136,6 +136,10 @@ install/CDN subdomains (`*.ampcode.com`). Treat it as a starting point;
 Amp may reach other domains (model providers, analytics, updates) that
 you'll discover by watching `sbx policy log` while testing.
 
+Kits can also declare `deniedDomains` for hosts the sandbox should not
+reach, such as telemetry endpoints. Deny rules take precedence over
+allow rules and apply only to sandboxes that use the kit.
+
 For the auth wiring, when the agent makes an outbound request to
 `ampcode.com`, the proxy looks up the host in `serviceDomains` to find
 the service id `amp`, then uses `serviceAuth.amp` to inject an
@@ -279,6 +283,8 @@ Two loops help:
 
 - Watch the network policy log (`sbx policy log`) to catch blocked
   requests, then add their domains to `allowedDomains`.
+- Add domains to `deniedDomains` when the agent should stay blocked from
+  a host even if another policy permits it.
 - Edit the spec and re-run `sbx run --kit ./amp/ amp` to pick up changes.
   Remove the sandbox first (`sbx rm <name>`) for a clean start.
 
@@ -304,7 +310,8 @@ the same decisions for your agent:
   into a custom image. Pick install if it's a one-line script; bake if
   the install is slow or you need a pinned version.
 - **Network mapping**: list only the API host in `serviceDomains`, not
-  a wildcard. Keep install/CDN paths out of TLS-intercepting mode.
+  a wildcard. Keep install/CDN paths out of TLS-intercepting mode. Use
+  `deniedDomains` for hosts the agent should not reach.
 - **Credential injection**: if the agent validates the API key's format
   locally, register with `sbx secret set-custom` and pick a matching
   placeholder. If it accepts the env var as-is, declare

content/manuals/ai/sandboxes/customize/kits.md

@@ -18,15 +18,15 @@ A kit packages a set of capabilities a sandbox can use, such as:
 - Tools to install
 - Environment variables to set
 - Credentials to inject
-- Domains to allow
+- Network rules to allow or deny domains
 - Files to drop in
 - Startup commands to run
 
 You declare these in a single `spec.yaml` file, point the CLI at the
 directory (or a ZIP, OCI artifact, or Git URL), and the sandbox applies
 and enforces them at runtime. Credentials stay on the host and go through
 a proxy instead of entering the VM, and outbound traffic is restricted to
-the domains the kit allows.
+the domains permitted by the kit's network rules.
 
 A kit is either a mixin or an agent:
 
@@ -113,15 +113,23 @@ be visible inside the sandbox VM.
 
 ### Control network access
 
-Network rules define which domains the sandbox can reach:
+Network rules define which domains the sandbox can reach or block. Kit
+network rules apply only to sandboxes that use the kit:
 
 ```yaml
 network:
   allowedDomains:
     - api.example.com
     - "*.cdn.example.com"
+  deniedDomains:
+    - telemetry.example.com
 ```
 
+Use `allowedDomains` for hosts the agent needs, such as package
+registries, install endpoints, or external APIs. Use `deniedDomains` for
+hosts the agent should not reach, such as telemetry endpoints. If a domain
+matches both an allow rule and a deny rule, the deny rule wins.
+
 For authenticated services, see
 [Authenticate to external services](#authenticate-to-external-services).
 
@@ -441,6 +449,7 @@ Service identifiers link credentials to [network rules](#network).
 ```yaml
 network:
   allowedDomains: [<domain>, ...]
+  deniedDomains: [<domain>, ...]
   serviceDomains:
     <domain>: <service-id>
   serviceAuth:
@@ -452,6 +461,7 @@ network:
 | Field                     | Description                                                      |
 | ------------------------- | ---------------------------------------------------------------- |
 | `allowedDomains`          | Domains the sandbox can reach. Wildcards supported.              |
+| `deniedDomains`           | Domains the sandbox can't reach. Deny rules take precedence.     |
 | `serviceDomains`          | Map of domain to service identifier from `credentials.sources`.  |
 | `serviceAuth.headerName`  | HTTP header the proxy sets (for example, `Authorization`).       |
 | `serviceAuth.valueFormat` | Format string for the header value (for example, `"Bearer %s"`). |

content/manuals/ai/sandboxes/customize/templates.md

@@ -142,7 +142,7 @@ Unless you use the permissive `allow-all` network policy, you may also need
 to allow-list any domains that your custom tools depend on:
 
 ```console
-$ sbx policy allow network "*.example.com:443,example.com:443"
+$ sbx policy allow network -g "*.example.com:443,example.com:443"
 ```
 
 Then run a sandbox with your template. The agent you specify must match

content/manuals/ai/sandboxes/get-started.md

@@ -230,7 +230,7 @@ $ sbx policy ls
 To allow a specific host:
 
 ```console
-$ sbx policy allow network registry.npmjs.org
+$ sbx policy allow network -g registry.npmjs.org
 ```
 
 With **Locked Down**, even your model provider API is blocked unless you

content/manuals/ai/sandboxes/security/defaults.md

@@ -18,7 +18,7 @@ it (deny-by-default). All non-HTTP protocols (raw TCP, UDP including DNS, and
 ICMP) are blocked at the network layer. Traffic to private IP ranges, loopback
 addresses, and link-local addresses is also blocked.
 
-Run `sbx policy ls` to see the active allow rules for your installation. To
+Run `sbx policy ls` to see the active network rules for your installation. To
 customize network access, see [Policies](policy.md).
 
 ## Workspace defaults

content/manuals/ai/sandboxes/security/policy.md

@@ -11,7 +11,8 @@ Sandboxes are [network-isolated](isolation.md) from your host and from each
 other. A policy system controls what a sandbox can access over the network.
 
 Use the `sbx policy` command to configure network access rules. Rules apply
-to all sandboxes on the machine.
+to all sandboxes on the machine when you use the global scope. Network allow,
+deny, list, and remove commands can also target one sandbox.
 
 ## Network policies
 
@@ -20,7 +21,7 @@ your host, which enforces access rules on every outbound request.
 
 Non-HTTP TCP traffic, including SSH, can be allowed by adding a policy rule
 for the destination IP address and port (for example,
-`sbx policy allow network "10.1.2.3:22"`). UDP and ICMP traffic is blocked
+`sbx policy allow network -g "10.1.2.3:22"`). UDP and ICMP traffic is blocked
 at the network layer and can't be unblocked with policy rules.
 
 ### Initial policy selection
@@ -40,7 +41,7 @@ Choose a default network policy:
 
 | Policy      | Description                                                                                                                                                                                    |
 | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Open        | All outbound traffic is allowed. No restrictions. Equivalent to adding a wildcard allow rule with `sbx policy allow network "**"`.                                                             |
+| Open        | All outbound traffic is allowed. No restrictions. Equivalent to adding a wildcard allow rule with `sbx policy allow network -g "**"`.                                                          |
 | Balanced    | Default deny, with a baseline allowlist covering AI provider APIs, package managers, code hosts, container registries, and common cloud services. You can extend this with `sbx policy allow`. |
 | Locked Down | All outbound traffic is blocked, including model provider APIs (for example, `api.anthropic.com`). You must explicitly allow everything you need.                                              |
 
@@ -72,35 +73,69 @@ services. Run `sbx policy ls` to see the active rules for your installation.
 
 Use [`sbx policy allow`](/reference/cli/sbx/policy/allow/) and
 [`sbx policy deny`](/reference/cli/sbx/policy/deny/) to add network access
-rules. Changes take effect immediately and apply to all sandboxes:
+rules. Changes take effect immediately. Pass `-g` to apply a rule to all
+sandboxes:
 
 ```console
-$ sbx policy allow network api.anthropic.com
-$ sbx policy deny network ads.example.com
+$ sbx policy allow network -g api.anthropic.com
+$ sbx policy deny network -g ads.example.com
+```
+
+Pass a sandbox name to scope a rule to one sandbox:
+
+```console
+$ sbx policy allow network my-sandbox api.example.com
+$ sbx policy deny network my-sandbox ads.example.com
 ```
 
 Specify multiple hosts in one command with a comma-separated list:
 
 ```console
-$ sbx policy allow network "api.anthropic.com,*.npmjs.org,*.pypi.org"
+$ sbx policy allow network -g "api.anthropic.com,*.npmjs.org,*.pypi.org"
 ```
 
 List all active policy rules with `sbx policy ls`:
 
 ```console
 $ sbx policy ls
-ID                                     TYPE      DECISION   RESOURCES
-a1b2c3d4-e5f6-7890-abcd-ef1234567890   network   allow      api.anthropic.com, *.npmjs.org
-f9e8d7c6-b5a4-3210-fedc-ba0987654321   network   deny       ads.example.com
+NAME                  TYPE      ORIGIN               DECISION   STATUS   RESOURCES
+balanced-dev          network   local                allow      active   api.anthropic.com
+ads-block             network   local                deny       active   ads.example.com
+kit:my-sandbox        network   sandbox:my-sandbox   allow      active   api.example.com
+kit:my-sandbox:deny   network   sandbox:my-sandbox   deny       active   telemetry.example.com
 ```
 
-Use `--type network` to show only network policies.
+The columns are:
+
+- `NAME`: the rule name.
+- `TYPE`: the rule type, such as `network`.
+- `ORIGIN`: where the rule applies. `local` means the rule is global and
+  applies to all sandboxes. `sandbox:<name>` means the rule is scoped to the
+  named sandbox.
+- `DECISION`: whether the rule allows or denies the resource.
+- `STATUS`: whether the rule is currently in effect. A rule may be inactive if
+  it's overridden by another rule, for example.
+- `RESOURCES`: the hosts or patterns the rule applies to.
+
+Use `--type network` to show only network policies. Without a sandbox argument,
+`sbx policy ls` shows every rule across all sandboxes. Pass a sandbox name to
+filter the list to global rules and rules scoped to that sandbox only:
+
+```console
+$ sbx policy ls my-sandbox
+```
 
 Remove a policy by resource or by rule ID:
 
 ```console
-$ sbx policy rm network --resource ads.example.com
-$ sbx policy rm network --id 2d3c1f0e-4a73-4e05-bc9d-f2f9a4b50d67
+$ sbx policy rm network -g --resource ads.example.com
+$ sbx policy rm network -g --id 2d3c1f0e-4a73-4e05-bc9d-f2f9a4b50d67
+```
+
+To remove a sandbox-scoped policy, include the sandbox name:
+
+```console
+$ sbx policy rm network my-sandbox --resource api.example.com
 ```
 
 ### Resetting to defaults
@@ -127,7 +162,7 @@ If you prefer a permissive policy where all outbound traffic is allowed, add
 a wildcard allow rule:
 
 ```console
-$ sbx policy allow network "**"
+$ sbx policy allow network -g "**"
 ```
 
 This lets agents install packages and call any external API without additional
@@ -146,7 +181,7 @@ match the root domain. Specify both to cover both.
 Allow access to package managers so agents can install dependencies:
 
 ```console
-$ sbx policy allow network "*.npmjs.org,*.pypi.org,files.pythonhosted.org,github.com"
+$ sbx policy allow network -g "*.npmjs.org,*.pypi.org,files.pythonhosted.org,github.com"
 ```
 
 The **Balanced** policy already includes AI provider APIs, package managers,
@@ -202,7 +237,8 @@ machine-readable output, or `--type network` to filter by policy type.
 
 All outbound traffic is blocked by default unless an explicit rule allows it.
 If a domain matches both an allow and a deny rule, the deny rule wins
-regardless of specificity.
+regardless of specificity. A sandbox-scoped deny rule can block a domain for
+one sandbox even when a global rule permits the same domain.
 
 To unblock a domain, find the deny rule with `sbx policy ls` and remove it
 with `sbx policy rm`.

content/manuals/ai/sandboxes/troubleshooting.md

@@ -43,13 +43,13 @@ $ sbx policy log
 Then allow the domains your workflow needs:
 
 ```console
-$ sbx policy allow network "*.npmjs.org,*.pypi.org,files.pythonhosted.org"
+$ sbx policy allow network -g "*.npmjs.org,*.pypi.org,files.pythonhosted.org"
 ```
 
 To allow all outbound traffic instead:
 
 ```console
-$ sbx policy allow network "**"
+$ sbx policy allow network -g "**"
 ```
 
 ## SSH and other non-HTTP connections fail
@@ -59,7 +59,7 @@ the destination IP address and port. For example, to allow SSH to a specific
 host:
 
 ```console
-$ sbx policy allow network "10.1.2.3:22"
+$ sbx policy allow network -g "10.1.2.3:22"
 ```
 
 Hostname-based rules (for example, `myhost:22`) don't work for non-HTTP

content/manuals/ai/sandboxes/usage.md

@@ -361,7 +361,7 @@ forwarding the request, so you must add the `localhost` address with the
 specific port to your network policy allowlist:
 
 ```console
-$ sbx policy allow network localhost:11434
+$ sbx policy allow network -g localhost:11434
 ```
 
 Then use `host.docker.internal` in any configuration or request that points at

data/sbx_cli/sbx_policy_allow_network.yaml

@@ -6,8 +6,15 @@ description: |-
     RESOURCES is a comma-separated list of hostnames, domains, or IP addresses.
     Supports exact domains (example.com), wildcard subdomains (*.example.com),
     and optional port suffixes (example.com:443). Use "**" to allow all hosts.
-usage: sbx policy allow network RESOURCES [flags]
+
+    Use -g/--global to apply the rule globally to all sandboxes, or provide
+    SANDBOX before RESOURCES to scope the rule to a specific sandbox.
+usage: sbx policy allow network [-g | SANDBOX] RESOURCES [flags]
 options:
+    - name: global
+      shorthand: g
+      default_value: "false"
+      usage: Apply the rule globally to all sandboxes
     - name: help
       shorthand: h
       default_value: "false"
@@ -18,16 +25,19 @@ inherited_options:
       default_value: "false"
       usage: Enable debug logging
 example: |4-
-      # Allow access to a single host
-      sbx policy allow network api.example.com
+      # Allow access to a single host globally
+      sbx policy allow network -g api.example.com
+
+      # Allow access to multiple hosts globally
+      sbx policy allow network -g "api.example.com,cdn.example.com"
 
-      # Allow access to multiple hosts
-      sbx policy allow network "api.example.com,cdn.example.com"
+      # Allow a host only for a specific sandbox
+      sbx policy allow network my-sandbox api.example.com
 
       # Allow all subdomains of a host
-      sbx policy allow network "*.npmjs.org"
+      sbx policy allow network -g "*.npmjs.org"
 
-      # Allow all outbound traffic
-      sbx policy allow network "**"
+      # Allow all outbound traffic globally
+      sbx policy allow network -g "**"
 see_also:
     - sbx policy allow - Add an allow policy for sandboxes

data/sbx_cli/sbx_policy_deny_network.yaml

@@ -5,8 +5,15 @@ description: |-
 
     RESOURCES is a comma-separated list of hostnames, domains, or IP addresses.
     Deny rules always take precedence over allow rules.
-usage: sbx policy deny network RESOURCES [flags]
+
+    Use -g/--global to apply the rule globally to all sandboxes, or provide
+    SANDBOX before RESOURCES to scope the rule to a specific sandbox.
+usage: sbx policy deny network [-g | SANDBOX] RESOURCES [flags]
 options:
+    - name: global
+      shorthand: g
+      default_value: "false"
+      usage: Apply the rule globally to all sandboxes
     - name: help
       shorthand: h
       default_value: "false"
@@ -17,10 +24,13 @@ inherited_options:
       default_value: "false"
       usage: Enable debug logging
 example: |4-
-      # Block access to a host
-      sbx policy deny network ads.example.com
+      # Block access to a host globally
+      sbx policy deny network -g ads.example.com
+
+      # Block a host only for a specific sandbox
+      sbx policy deny network my-sandbox ads.example.com
 
-      # Block all outbound traffic
-      sbx policy deny network "**"
+      # Block all outbound traffic globally
+      sbx policy deny network -g "**"
 see_also:
     - sbx policy deny - Add a deny policy for sandboxes