docs: document sandbox-scoped kit network policies

Kit network policy docs did not cover sandbox-scoped rules or kit-level deniedDomains.

Update the Sandboxes policy and kits pages with scoped policy examples, deniedDomains guidance, and a small policy page formatting fix.

Co-Authored-By: Codex <noreply@openai.com>
noreply@openai.com>

oreply@openai.com>

Author: codex

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/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 by default. Network allow, deny, list, and
+remove commands can also target one sandbox with `--sandbox`.
 
 ## Network policies
 
@@ -72,13 +73,21 @@ 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. By default, they apply to all
+sandboxes:
 
 ```console
 $ sbx policy allow network api.anthropic.com
 $ sbx policy deny network ads.example.com
 ```
 
+Use `--sandbox` to scope a rule to one sandbox:
+
+```console
+$ sbx policy allow network --sandbox my-sandbox api.example.com
+$ sbx policy deny network --sandbox my-sandbox ads.example.com
+```
+
 Specify multiple hosts in one command with a comma-separated list:
 
 ```console
@@ -89,12 +98,19 @@ 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.
+Use `--type network` to show only network policies. Use `--sandbox` to show
+global rules plus rules scoped to one sandbox:
+
+```console
+$ sbx policy ls --sandbox my-sandbox
+```
 
 Remove a policy by resource or by rule ID:
 
@@ -103,6 +119,12 @@ $ sbx policy rm network --resource ads.example.com
 $ sbx policy rm network --id 2d3c1f0e-4a73-4e05-bc9d-f2f9a4b50d67
 ```
 
+To remove a sandbox-scoped policy, include the sandbox name:
+
+```console
+$ sbx policy rm network --sandbox my-sandbox --resource api.example.com
+```
+
 ### Resetting to defaults
 
 To remove all custom policies and restore the default policy, use
@@ -202,7 +224,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`.