From 9813f56f5d053a19baa955d323127a7cd6381f9d Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Thu, 13 Aug 2026 13:24:31 +0000 Subject: [PATCH 1/3] docs(sandboxes): clarify outbound protocol support --- .../governance/access-controls/network.md | 6 ++++-- .../manuals/ai/sandboxes/governance/concepts.md | 5 +++-- .../manuals/ai/sandboxes/security/defaults.md | 16 +++++++--------- 3 files changed, 14 insertions(+), 13 deletions(-) diff --git a/content/manuals/ai/sandboxes/governance/access-controls/network.md b/content/manuals/ai/sandboxes/governance/access-controls/network.md index b30d1dbb5a0d..cde42157a6ac 100644 --- a/content/manuals/ai/sandboxes/governance/access-controls/network.md +++ b/content/manuals/ai/sandboxes/governance/access-controls/network.md @@ -24,8 +24,10 @@ policy. See [Precedence](../concepts.md#precedence). ## Rule syntax -Network rules use the actions `connect:tcp` and `connect:udp`. Resources are -hostnames, CIDR ranges, ports, or hostnames with ports. +Network rules use the action `connect:tcp`. Resources are hostnames, CIDR +ranges, ports, or hostnames with ports. The governance policy schema also +accepts `connect:udp`, but Docker Sandboxes blocks direct external UDP +independently of network policy. Examples: diff --git a/content/manuals/ai/sandboxes/governance/concepts.md b/content/manuals/ai/sandboxes/governance/concepts.md index 624661f39979..be9e730b9598 100644 --- a/content/manuals/ai/sandboxes/governance/concepts.md +++ b/content/manuals/ai/sandboxes/governance/concepts.md @@ -59,8 +59,9 @@ plus every team-scoped policy for a team they belong to. See ### Network rules -Network rules use the actions `connect:tcp` and `connect:udp`. Resources are -hostnames, CIDR ranges, or ports. +Network rules use the action `connect:tcp`. Resources are hostnames, CIDR +ranges, or ports. The governance policy schema also accepts `connect:udp`, but +Docker Sandboxes blocks direct external UDP independently of network policy. **Hostname patterns** diff --git a/content/manuals/ai/sandboxes/security/defaults.md b/content/manuals/ai/sandboxes/security/defaults.md index cdc75cb1de11..7b6029de9423 100644 --- a/content/manuals/ai/sandboxes/security/defaults.md +++ b/content/manuals/ai/sandboxes/security/defaults.md @@ -11,10 +11,10 @@ security posture. ## Network defaults -All outbound HTTP and HTTPS traffic is blocked unless an explicit rule allows -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. +All outbound TCP traffic, including HTTP, HTTPS, and SSH, is blocked unless an +explicit rule allows the destination. Direct external UDP and ICMP traffic is +blocked at the network layer. DNS queries use the sandbox's policy-gated +resolver. Run `sbx policy ls` to see the active network rules for your installation. Rules can be customized per machine with the `sbx policy` CLI, or managed @@ -71,10 +71,8 @@ policy configuration: - Host filesystem access outside explicitly mounted workspaces and the shared skills store - Host Docker daemon -- Host network and localhost - Direct network communication between sandboxes -- Raw TCP, UDP, and ICMP connections -- Traffic to private IP ranges and link-local addresses +- Direct external UDP and ICMP connections -Outbound HTTP/HTTPS to domains not in the allow list is also blocked by -default, but you can add allow rules with `sbx policy allow`. +Outbound TCP to destinations not in the allow list is also blocked by default, +but you can add allow rules with `sbx policy allow`. From 7352567efb32f00e425885b4cb169fe02b1a950d Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Thu, 13 Aug 2026 13:35:51 +0000 Subject: [PATCH 2/3] docs(sandboxes): align network isolation wording --- .../governance/access-controls/network.md | 4 ++-- .../ai/sandboxes/governance/concepts.md | 3 ++- .../manuals/ai/sandboxes/security/_index.md | 18 ++++++++++-------- .../manuals/ai/sandboxes/security/defaults.md | 4 ++-- .../manuals/ai/sandboxes/security/isolation.md | 17 ++++++----------- 5 files changed, 22 insertions(+), 24 deletions(-) diff --git a/content/manuals/ai/sandboxes/governance/access-controls/network.md b/content/manuals/ai/sandboxes/governance/access-controls/network.md index cde42157a6ac..e2047be4ce3b 100644 --- a/content/manuals/ai/sandboxes/governance/access-controls/network.md +++ b/content/manuals/ai/sandboxes/governance/access-controls/network.md @@ -26,8 +26,8 @@ policy. See [Precedence](../concepts.md#precedence). Network rules use the action `connect:tcp`. Resources are hostnames, CIDR ranges, ports, or hostnames with ports. The governance policy schema also -accepts `connect:udp`, but Docker Sandboxes blocks direct external UDP -independently of network policy. +accepts `connect:udp`, but Docker Sandboxes always blocks direct external UDP +and ICMP. `connect:udp` rules have no effect. Examples: diff --git a/content/manuals/ai/sandboxes/governance/concepts.md b/content/manuals/ai/sandboxes/governance/concepts.md index be9e730b9598..d39cd47f128c 100644 --- a/content/manuals/ai/sandboxes/governance/concepts.md +++ b/content/manuals/ai/sandboxes/governance/concepts.md @@ -61,7 +61,8 @@ plus every team-scoped policy for a team they belong to. See Network rules use the action `connect:tcp`. Resources are hostnames, CIDR ranges, or ports. The governance policy schema also accepts `connect:udp`, but -Docker Sandboxes blocks direct external UDP independently of network policy. +Docker Sandboxes always blocks direct external UDP and ICMP. `connect:udp` +rules have no effect. **Hostname patterns** diff --git a/content/manuals/ai/sandboxes/security/_index.md b/content/manuals/ai/sandboxes/security/_index.md index 003061b6decf..3b085fadc779 100644 --- a/content/manuals/ai/sandboxes/security/_index.md +++ b/content/manuals/ai/sandboxes/security/_index.md @@ -24,8 +24,8 @@ What crosses the boundary into the VM: and the agent works on a private clone. - **Credentials:** the host-side proxy injects authentication headers into outbound HTTP requests. The raw credential values never enter the VM. -- **Network access:** HTTP and HTTPS requests to - [allowed domains](defaults/) are proxied through the host. +- **Network access:** outbound TCP connections to destinations allowed by + [network policy](defaults/) are proxied through the host. - **Shared agent skills:** a persistent host-side store is mounted read-write at the agent's skills directory unless you opt out when creating the sandbox. Supported agents in other sandboxes mount the same store. @@ -36,15 +36,16 @@ What crosses the boundary back to the host: - **Workspace file changes:** visible on your host in real time with the default direct mount. -- **HTTP/HTTPS requests:** sent to allowed domains through the host proxy. +- **Outbound TCP connections:** sent to allowed destinations through the host + proxy. - **Shared skill changes:** written to the host-side store and visible to other sandboxes that share it. Outside the workspace and shared skills store, the agent cannot access your host filesystem. It also cannot access your host Docker daemon, your host -network or localhost, or any domain not in the allow list. Sandboxes cannot -communicate directly over the network. Raw TCP, UDP, and ICMP are blocked at -the network layer. +network directly, or any destination not allowed by network policy. Sandboxes +cannot communicate directly over the network. Direct external UDP and ICMP are +blocked at the network layer. MCP servers are an explicit integration point. Remote MCP servers run outside Docker Sandboxes, and local stdio MCP servers run on the host, not inside the @@ -61,8 +62,9 @@ The sandbox security model has five layers. See - **Hypervisor isolation:** separate kernel per sandbox. No shared memory or processes with the host. -- **Network isolation:** all HTTP/HTTPS traffic proxied through the host. - [Deny-by-default policy](defaults/). Non-HTTP protocols blocked entirely. +- **Network isolation:** outbound TCP traffic is proxied through the host and + governed by a [deny-by-default policy](defaults/). Direct external UDP and + ICMP are blocked. - **Docker Engine isolation:** each sandbox has its own Docker Engine with no path to the host daemon. - **Workspace isolation** (opt-in via `--clone`): the agent works on a diff --git a/content/manuals/ai/sandboxes/security/defaults.md b/content/manuals/ai/sandboxes/security/defaults.md index 7b6029de9423..98ef11dfad0c 100644 --- a/content/manuals/ai/sandboxes/security/defaults.md +++ b/content/manuals/ai/sandboxes/security/defaults.md @@ -13,8 +13,8 @@ security posture. All outbound TCP traffic, including HTTP, HTTPS, and SSH, is blocked unless an explicit rule allows the destination. Direct external UDP and ICMP traffic is -blocked at the network layer. DNS queries use the sandbox's policy-gated -resolver. +blocked at the network layer. DNS queries use the sandbox's internal resolver, +which enforces network policy. Run `sbx policy ls` to see the active network rules for your installation. Rules can be customized per machine with the `sbx policy` CLI, or managed diff --git a/content/manuals/ai/sandboxes/security/isolation.md b/content/manuals/ai/sandboxes/security/isolation.md index 917e62bfa851..9c9f476d8849 100644 --- a/content/manuals/ai/sandboxes/security/isolation.md +++ b/content/manuals/ai/sandboxes/security/isolation.md @@ -33,23 +33,18 @@ hypervisor boundary is the isolation control, not in-VM privilege separation. ## Network isolation -Each sandbox has its own isolated network. Sandboxes cannot communicate with -each other and cannot reach your host's localhost. There is no shared network -between sandboxes or between a sandbox and your host. +Each sandbox has its own isolated network. Sandboxes cannot communicate +directly with each other or share a network with your host. -All HTTP and HTTPS traffic leaving a sandbox passes through a proxy on your -host that enforces the +All outbound TCP traffic passes through a proxy on your host that enforces the [network access policy](../governance/access-controls/network.md). The sandbox routes traffic through either a forward proxy or a transparent proxy depending on the client's configuration. Both enforce the network policy. Only the forward proxy [injects credentials](credentials.md) for AI services. -Raw TCP connections, UDP, and ICMP are blocked at the network layer. DNS -resolution goes through the proxy and is subject to the same network policy — -domains that policy denies are refused at the resolver; loopback names such as -`localhost` are always resolved regardless of policy. Traffic to private IP -ranges, loopback, and link-local addresses is also blocked. Only domains -explicitly listed in the policy are reachable. +Direct external UDP and ICMP are blocked at the network layer. DNS queries use +the sandbox's internal resolver, which enforces network policy. TCP connections +are allowed only when a policy rule matches the destination. For the default set of allowed domains, see [Default security posture](defaults.md). To forward allowed traffic through a From 492f31b940af7d5ad6a25f7f9953b5c294769faa Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Fri, 14 Aug 2026 07:58:37 +0000 Subject: [PATCH 3/3] docs(sandboxes): clarify TCP proxy behavior --- content/manuals/ai/sandboxes/architecture.md | 9 +++++---- .../governance/access-controls/local.md | 11 +++++----- .../ai/sandboxes/security/isolation.md | 4 +++- .../manuals/ai/sandboxes/troubleshooting.md | 20 +++++++++++-------- 4 files changed, 25 insertions(+), 19 deletions(-) diff --git a/content/manuals/ai/sandboxes/architecture.md b/content/manuals/ai/sandboxes/architecture.md index 680e3099746c..ce34ce5f1246 100644 --- a/content/manuals/ai/sandboxes/architecture.md +++ b/content/manuals/ai/sandboxes/architecture.md @@ -52,10 +52,11 @@ $ DOCKER_SANDBOXES_ENABLE_VIRTIOFS_CACHE=0 sbx run