docker · dvdksn · Jun 11, 2026 · Jun 11, 2026 · Jun 11, 2026 · Jun 15, 2026
@@ -62,13 +62,17 @@ Without extra args, the sandbox runs:
 claude --dangerously-skip-permissions
 ```
 
-Args after `--` replace these defaults rather than being appended. To keep
-`--dangerously-skip-permissions`, include it yourself:
+Arguments after `--` are added after the default flags when the first one is
+itself a flag (begins with `-`), so `--dangerously-skip-permissions` is
+preserved:
 
 ```console
-$ sbx run claude -- --dangerously-skip-permissions -c
+$ sbx run claude -- -c   # runs claude --dangerously-skip-permissions -c
 ```
 
+When the first argument is a bare word, such as the `agents` subcommand, it
+replaces the defaults instead.
+
 See the [Claude Code CLI reference](https://code.claude.com/docs/en/cli-reference)
 for available options.
 

@@ -73,8 +73,9 @@ Without extra args, the sandbox runs:
 codex --dangerously-bypass-approvals-and-sandbox
 ```
 
-Args after `--` replace these defaults rather than being appended. To keep
-the flag, include it yourself:
+Arguments after `--` are added after the default flags when the first one is
+itself a flag (begins with `-`). A bare word — such as a prompt — replaces the
+defaults instead, so lead with the flag to keep bypass mode:
 
 ```console
 $ sbx run codex -- --dangerously-bypass-approvals-and-sandbox "fix the build"

@@ -59,13 +59,16 @@ Without extra args, the sandbox runs:
 copilot --yolo
 ```
 
-Args after `--` replace these defaults rather than being appended. To keep
-`--yolo`, include it yourself:
+Arguments after `--` are added after the default flags when the first one is
+itself a flag (begins with `-`), so `--yolo` is preserved:
 
 ```console
-$ sbx run copilot -- --yolo -p "review this PR"
+$ sbx run copilot -- -p "review this PR"   # runs copilot --yolo -p "review this PR"
 ```
 
+When the first argument is a bare word — a subcommand or prompt — it replaces
+the defaults instead.
+
 ## Base image
 
 Template: `docker/sandbox-templates:copilot`

@@ -65,13 +65,16 @@ Without extra args, the sandbox runs:
 cursor-agent --yolo
 ```
 
-Args after `--` replace these defaults rather than being appended. To keep
-`--yolo`, include it yourself:
+Arguments after `--` are added after the default flags when the first one is
+itself a flag (begins with `-`), so `--yolo` is preserved:
 
 ```console
-$ sbx run cursor -- --yolo -p "refactor this"
+$ sbx run cursor -- -p "refactor this"   # runs cursor-agent --yolo -p "refactor this"
 ```
 
+When the first argument is a bare word — a subcommand or prompt — it replaces
+the defaults instead.
+
 ## Base image
 
 Template: `docker/sandbox-templates:cursor-agent-docker`

@@ -60,8 +60,10 @@ Without extra args, the sandbox runs:
 docker-agent run --yolo
 ```
 
-Args after `--` replace these defaults rather than being appended. To keep
-`run --yolo`, include them yourself:
+Arguments after `--` are added after the default flags when the first one is
+itself a flag (begins with `-`). When the first argument is a bare word — such
+as the `run` subcommand or a config file — it replaces the defaults, so include
+`run --yolo` yourself:
 
 ```console
 $ sbx run docker-agent -- run --yolo agent.yml

@@ -65,13 +65,16 @@ Without extra args, the sandbox runs:
 gemini --yolo
 ```
 
-Args after `--` replace these defaults rather than being appended. To keep
-`--yolo`, include it yourself:
+Arguments after `--` are added after the default flags when the first one is
+itself a flag (begins with `-`), so `--yolo` is preserved:
 
 ```console
-$ sbx run gemini -- --yolo -p "explain this"
+$ sbx run gemini -- -p "explain this"   # runs gemini --yolo -p "explain this"
 ```
 
+When the first argument is a bare word — a subcommand or prompt — it replaces
+the defaults instead.
+
 ## Base image
 
 Template: `docker/sandbox-templates:gemini`

@@ -85,10 +85,12 @@ Without extra args, the sandbox runs:
 kiro chat --trust-all-tools
 ```
 
-Args after `--` replace these defaults rather than being appended. This is
-why `sbx run kiro -- login --use-device-flow` works for the login subcommand.
-To keep `chat --trust-all-tools` alongside your own args, include them
-yourself:
+When the first argument after `--` is a flag (begins with `-`), it's added
+after the defaults — for example, `sbx run kiro -- --resume` runs
+`kiro chat --trust-all-tools --resume`. When the first argument is a bare word,
+it replaces the defaults, which is why `sbx run kiro -- login --use-device-flow`
+runs the login subcommand on its own. To run `chat` with extra arguments of
+your own, include the subcommand:
 
 ```console
 $ sbx run kiro -- chat --trust-all-tools --resume

@@ -23,14 +23,16 @@ $ sbx run shell -- -c "echo 'Hello from sandbox'"
 
 ## Default startup command
 
-Without extra args, the sandbox runs `bash -l`. Args after `--` replace `-l`
-rather than being appended. To preserve login-shell behavior, include `-l`
-yourself:
+Without extra args, the sandbox runs `bash -l`. When the first argument after
+`--` is a flag (begins with `-`), it's added after `-l`, so login-shell
+behavior is preserved:
 
 ```console
-$ sbx run shell -- -l -c "echo hi"
+$ sbx run shell -- -c "echo hi"   # runs bash -l -c "echo hi"
 ```
 
+When the first argument is a bare word, it replaces `-l` instead.
+
 Set your API keys as environment variables so the sandbox proxy can inject
 them into API requests automatically. Credentials are never stored inside
 the VM:

@@ -2,7 +2,7 @@
 title: FAQ
 weight: 70
 description: Frequently asked questions about Docker Sandboxes.
-keywords: docker sandboxes, sbx, faq, sign in, telemetry
+keywords: docker sandboxes, sbx, faq, sign in, telemetry, clipboard, image paste
 ---
 
 ## Why do I need to sign in?
@@ -159,6 +159,35 @@ Collocating skills and other agent configuration with the project itself is a
 good practice regardless of sandboxes. It's versioned alongside the code and
 evolves with the project as it changes.
 
+## Can I paste images into an agent?
+
+Yes, but it's off by default. Text paste already works, because the terminal
+sends it directly. Pasting an image or screenshot with `Ctrl+V` is different:
+the agent reads it from your host clipboard, and the sandbox blocks that access
+unless you opt in.
+
+Turn it on with a local setting:
+
+```console
+$ sbx settings set clipboard.imagePaste true
+```
+
+`Ctrl+V` then pastes host images into agents that read the clipboard, including
+Claude Code and Codex. The setting takes effect within a few seconds, even for
+running sandboxes.
+
+This is opt-in because it relaxes the sandbox's isolation: when enabled, a process
+inside the sandbox can read your host clipboard through the host-side proxy. The
+exposure is narrow — reads happen only on a paste, return image data only
+(`image/png`), and clipboard content is never cached or logged — but it's still
+host data crossing into the sandbox, so it stays off until you turn it on.
+
+To turn it back off:
+
+```console
+$ sbx settings set clipboard.imagePaste false
+```
+
 ## Can I use Docker Sandboxes on headless Linux?
 
 Yes. On Linux, `sbx` stores secrets in the Secret Service exposed by your

@@ -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.

@@ -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,23 @@ $ sbx secret set-custom -g \
     --value <secret>
 ```
 
+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 <secret>
+```
+
+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 <secret>` records it in your shell history
 > and exposes it to other processes running as your user. Avoid pasting
@@ -228,8 +245,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-<rand>`). When a sandboxed process sends a request to
-`api.example.com` and the placeholder appears anywhere in the request, the
+`sbx-cs-<rand>`). 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 —

@@ -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).

@@ -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 <template>
 ```
 
 The setting is persisted in the sandbox spec and applies for the lifetime of
-that sandbox. If you experience Git index corruption or unexpected file content
-after enabling the cache, remove the sandbox and recreate it without the flag.
+that sandbox. If you experience Git index corruption or unexpected file content,
+disable caching with the kill switch and recreate the sandbox:
+
+```console
+$ DOCKER_SANDBOXES_ENABLE_VIRTIOFS_CACHE=0 sbx run <template>
+```
 
 ## Clone mode reports "not in a Git repository" on WSL
 

@@ -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

@@ -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
 ```