From a755c70c1898fdbb9b820094f6e244df60caae0c Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Thu, 11 Jun 2026 13:52:28 +0200 Subject: [PATCH 1/8] docs(sandboxes): clarify DNS resolution is policy-gated in network isolation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Sandbox DNS lookups now go through the same policy engine as TCP connections — a denied domain is refused at the resolver level, not just the connection level. Updated the network isolation description to reflect this guarantee rather than describing DNS as merely proxied. Co-Authored-By: Claude Sonnet 4.6 --- content/manuals/ai/sandboxes/security/isolation.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/content/manuals/ai/sandboxes/security/isolation.md b/content/manuals/ai/sandboxes/security/isolation.md index 872cdfc1437..875edcb7338 100644 --- a/content/manuals/ai/sandboxes/security/isolation.md +++ b/content/manuals/ai/sandboxes/security/isolation.md @@ -43,9 +43,11 @@ 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 is handled by the proxy; the sandbox cannot make raw DNS queries. -Traffic to private IP ranges, loopback, and link-local addresses is also -blocked. Only domains explicitly listed in the policy are reachable. +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. For the default set of allowed domains, see [Default security posture](defaults.md). From 11fea16572fd5659a9c769cee3169889b5bae95e Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Thu, 11 Jun 2026 13:52:55 +0200 Subject: [PATCH 2/8] docs(sandboxes): add agent field to audit log schema Audit records now include an `agent` field identifying which AI agent drove the sandbox (claude, codex, etc.), so multi-agent deployments can attribute policy decisions per agent. Added to the example record and the field reference table. Co-Authored-By: Claude Sonnet 4.6 --- content/manuals/ai/sandboxes/governance/audit.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/content/manuals/ai/sandboxes/governance/audit.md b/content/manuals/ai/sandboxes/governance/audit.md index fcf2a4d24c9..10fe4103e6a 100644 --- a/content/manuals/ai/sandboxes/governance/audit.md +++ b/content/manuals/ai/sandboxes/governance/audit.md @@ -63,7 +63,8 @@ A network evaluation record looks like this: "no applicable policies for op(action=net:connect:tcp, resource=net:domain:example.com:443)" ], "action_type": "network_egress", - "network_egress": { "protocol": "tcp" } + "network_egress": { "protocol": "tcp" }, + "agent": "claude" } ``` @@ -83,6 +84,7 @@ Common fields include: | `resource_id` | The target of the evaluation, such as a host and port. | | `decision` | `AUDIT_DECISION_ALLOW` or `AUDIT_DECISION_DENY`. | | `deny_reason` | Why a denied request was blocked. Present on deny decisions. | +| `agent` | The AI agent driving the sandbox (for example, `claude`, `codex`). Omitted when the agent is unknown. | Each record is attributed to the signed-in Docker user and the organization whose governance policy is in effect. From 67514bc68dabe037b28f3a7674734cd774184791 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Thu, 11 Jun 2026 13:53:28 +0200 Subject: [PATCH 3/8] docs(sandboxes): document multiple --host patterns for custom secrets sbx secret set-custom --host is now repeatable, so one secret entry can cover multiple domains. Added a second example showing the multi-host form and updated the prose to reflect that the proxy matches any of the configured hosts. Co-Authored-By: Claude Sonnet 4.6 --- .../ai/sandboxes/security/credentials.md | 18 +++++++++++++++--- 1 file changed, 15 insertions(+), 3 deletions(-) diff --git a/content/manuals/ai/sandboxes/security/credentials.md b/content/manuals/ai/sandboxes/security/credentials.md index 644646f51c9..740e3495a6d 100644 --- a/content/manuals/ai/sandboxes/security/credentials.md +++ b/content/manuals/ai/sandboxes/security/credentials.md @@ -209,7 +209,7 @@ network policy. For details, see For credentials that don't fit the service-identifier model — for example, when an agent validates the environment variable format at boot, or when the credential lands in a request body rather than a header — use -`sbx secret set-custom`. The secret is keyed on a target domain, an +`sbx secret set-custom`. The secret is keyed on one or more target domains, an environment variable name, and an optional placeholder string, instead of a service identifier. @@ -220,6 +220,18 @@ $ sbx secret set-custom -g \ --value ``` +Repeat `--host` to cover multiple domains with the same secret — useful when +an API is split across related hostnames or when two unrelated endpoints share +a credential: + +```console +$ sbx secret set-custom -g \ + --host api.example.com \ + --host uploads.example.com \ + --env API_KEY \ + --value +``` + > [!WARNING] > Passing the secret as `--value ` records it in your shell history > and exposes it to other processes running as your user. Avoid pasting @@ -228,8 +240,8 @@ $ sbx secret set-custom -g \ > on the command line. Inside the sandbox, `API_KEY` is set to a generated placeholder (for example, -`sbx-cs-`). When a sandboxed process sends a request to -`api.example.com` and the placeholder appears anywhere in the request, the +`sbx-cs-`). When a sandboxed process sends a request to any of the +configured hosts and the placeholder appears anywhere in the request, the proxy replaces it with the real value. The agent never sees the real secret. Prefer the [service-based flow](#stored-secrets) whenever it's an option — From dc1affddb39ff8799bf40a7886bd8bf2046cea31 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Mon, 15 Jun 2026 12:51:22 +0200 Subject: [PATCH 4/8] docs(sandboxes): document --name as primary sandbox identity key --name now identifies a sandbox independently of the working directory. Expanded the reconnecting and naming section to cover: re-attaching by name from any directory, re-running a create command to reconnect without error, and using distinct names to run multiple sandboxes against the same workspace. Co-Authored-By: Claude Sonnet 4.6 --- content/manuals/ai/sandboxes/usage.md | 32 +++++++++++++++++++---- content/manuals/ai/sandboxes/workflows.md | 2 +- 2 files changed, 28 insertions(+), 6 deletions(-) diff --git a/content/manuals/ai/sandboxes/usage.md b/content/manuals/ai/sandboxes/usage.md index 0b4eb1c2d94..838c843c458 100644 --- a/content/manuals/ai/sandboxes/usage.md +++ b/content/manuals/ai/sandboxes/usage.md @@ -116,7 +116,7 @@ You can also create the sandbox in the background and attach later: ```console $ sbx create --clone --name my-sandbox claude . -$ sbx run my-sandbox +$ sbx run --name my-sandbox ``` The clone follows whichever ref your host repository has checked out at @@ -177,27 +177,49 @@ $ sbx run claude ~/my-project # creates sandbox $ sbx run claude ~/my-project # reconnects to same sandbox ``` -Use `--name` to make this explicit and avoid ambiguity: +Use `--name` to give a sandbox an explicit identity: ```console $ sbx run claude --name my-project ``` +Once a named sandbox exists, `--name` is how you re-attach to it — from any +working directory, with or without the agent positional: + +```console +$ sbx run --name my-project # re-attaches from anywhere +$ sbx run claude --name my-project # same, with agent confirmed +``` + +Re-running a command that previously created a sandbox reconnects to it rather +than returning an error, so you can up-arrow and re-enter a session without +first looking up the sandbox name. + +To run multiple sandboxes against the same workspace — for example, one for a +feature branch and one for exploratory changes — give each a distinct name: + +```console +$ sbx run claude --name feature ~/my-project +$ sbx run claude --name spike ~/my-project +``` + +Both sandboxes share the same workspace but are otherwise independent. + ## Creating without attaching [`sbx run`](/reference/cli/sbx/run/) creates the sandbox and attaches you to the agent. To create a sandbox in the background without attaching: ```console -$ sbx create claude . +$ sbx create --name my-project claude . ``` Unlike `run`, `create` requires an explicit workspace path. It uses direct mode by default, or pass `--clone` for [clone mode](#clone-mode). Attach -later with `sbx run`: +later with `sbx run --name`: ```console -$ sbx run claude-my-project +$ sbx run --name my-project ``` ## Multiple workspaces diff --git a/content/manuals/ai/sandboxes/workflows.md b/content/manuals/ai/sandboxes/workflows.md index 37f6388deac..c84e3dafabc 100644 --- a/content/manuals/ai/sandboxes/workflows.md +++ b/content/manuals/ai/sandboxes/workflows.md @@ -327,7 +327,7 @@ Create the sandbox in the background with `sbx create`, run agent tasks with ```console $ sbx create --name ci-task --clone claude -$ sbx run ci-task # attach and give instructions, or use sbx exec for one-off commands +$ sbx run --name ci-task # attach and give instructions, or use sbx exec for one-off commands $ git fetch sandbox-ci-task $ sbx rm ci-task ``` From 146d59ab07c2c7d08f78ce5fef48d3e3159475a9 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Mon, 15 Jun 2026 13:50:22 +0200 Subject: [PATCH 5/8] docs(sandboxes): document wildcard --host patterns for custom secrets sbx secret set-custom --host accepts wildcards (* for a single label, ** for any number), using the same syntax as network rules. Added a note and examples alongside the repeatable --host guidance. Co-Authored-By: Claude Sonnet 4.6 --- content/manuals/ai/sandboxes/security/credentials.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/content/manuals/ai/sandboxes/security/credentials.md b/content/manuals/ai/sandboxes/security/credentials.md index 740e3495a6d..9c1dbae38f4 100644 --- a/content/manuals/ai/sandboxes/security/credentials.md +++ b/content/manuals/ai/sandboxes/security/credentials.md @@ -232,6 +232,11 @@ $ sbx secret set-custom -g \ --value ``` +A `--host` value can also use wildcards, with the same syntax as +[network rules](../governance/concepts.md#network-rules): `*` matches a +single label (`*.example.com` covers `api.example.com`) and `**` matches any +number (`**.example.com` covers `api.example.com` and `v2.api.example.com`). + > [!WARNING] > Passing the secret as `--value ` records it in your shell history > and exposes it to other processes running as your user. Avoid pasting From c22158a7fa68ced29bf6a517bb3d3b5a591486fa Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Mon, 15 Jun 2026 13:50:22 +0200 Subject: [PATCH 6/8] docs(sandboxes): virtiofs cache is now enabled by default on macOS and Linux Direct-mode virtiofs caching is now on by default on macOS and Linux; Windows remains opt-in. Corrected the troubleshooting guidance, which still described caching as disabled by default, and documented DOCKER_SANDBOXES_ENABLE_VIRTIOFS_CACHE=0 as the kill switch. Co-Authored-By: Claude Sonnet 4.6 --- .../manuals/ai/sandboxes/troubleshooting.md | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/content/manuals/ai/sandboxes/troubleshooting.md b/content/manuals/ai/sandboxes/troubleshooting.md index b89710ac0a5..c3fb7057921 100644 --- a/content/manuals/ai/sandboxes/troubleshooting.md +++ b/content/manuals/ai/sandboxes/troubleshooting.md @@ -183,20 +183,24 @@ Extracting the tar archive as the current user avoids the `chown` call. Filesystem operations such as `git status`, `git log`, or directory scans can be noticeably slow when the sandbox workspace is mounted in direct mode (the -default for workspaces without `--clone`). In direct mode, virtiofs caching is -disabled by default to prevent data corruption. Clone-mode sandboxes enable -virtiofs caching automatically, so this tuning applies only to direct mode. +default for workspaces without `--clone`). Virtiofs caching speeds up these +workloads. Clone-mode sandboxes always enable it, so this tuning applies only +to direct mode. -To speed up filesystem-intensive workloads, opt into virtiofs caching when -creating the sandbox: +On macOS and Linux, virtiofs caching is enabled by default. On Windows it's +still opt-in — enable it when creating the sandbox: ```console $ DOCKER_SANDBOXES_ENABLE_VIRTIOFS_CACHE=1 sbx run