diff --git a/content/manuals/ai/sandboxes/agents/claude-code.md b/content/manuals/ai/sandboxes/agents/claude-code.md index 1bf4acd0930..87c278b2b14 100644 --- a/content/manuals/ai/sandboxes/agents/claude-code.md +++ b/content/manuals/ai/sandboxes/agents/claude-code.md @@ -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. diff --git a/content/manuals/ai/sandboxes/agents/codex.md b/content/manuals/ai/sandboxes/agents/codex.md index e2452524f98..86e06cd78dd 100644 --- a/content/manuals/ai/sandboxes/agents/codex.md +++ b/content/manuals/ai/sandboxes/agents/codex.md @@ -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" diff --git a/content/manuals/ai/sandboxes/agents/copilot.md b/content/manuals/ai/sandboxes/agents/copilot.md index c8b75049a8a..e8f2c80e722 100644 --- a/content/manuals/ai/sandboxes/agents/copilot.md +++ b/content/manuals/ai/sandboxes/agents/copilot.md @@ -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` diff --git a/content/manuals/ai/sandboxes/agents/cursor.md b/content/manuals/ai/sandboxes/agents/cursor.md index 1d94fed53c9..f6481665213 100644 --- a/content/manuals/ai/sandboxes/agents/cursor.md +++ b/content/manuals/ai/sandboxes/agents/cursor.md @@ -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` diff --git a/content/manuals/ai/sandboxes/agents/docker-agent.md b/content/manuals/ai/sandboxes/agents/docker-agent.md index d0fc2e2259d..de68d668f49 100644 --- a/content/manuals/ai/sandboxes/agents/docker-agent.md +++ b/content/manuals/ai/sandboxes/agents/docker-agent.md @@ -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 diff --git a/content/manuals/ai/sandboxes/agents/gemini.md b/content/manuals/ai/sandboxes/agents/gemini.md index 898dc074061..4bd194ca949 100644 --- a/content/manuals/ai/sandboxes/agents/gemini.md +++ b/content/manuals/ai/sandboxes/agents/gemini.md @@ -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` diff --git a/content/manuals/ai/sandboxes/agents/kiro.md b/content/manuals/ai/sandboxes/agents/kiro.md index 048160301c8..62a416b720d 100644 --- a/content/manuals/ai/sandboxes/agents/kiro.md +++ b/content/manuals/ai/sandboxes/agents/kiro.md @@ -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 diff --git a/content/manuals/ai/sandboxes/agents/shell.md b/content/manuals/ai/sandboxes/agents/shell.md index 54d88a60dc0..fab2621b172 100644 --- a/content/manuals/ai/sandboxes/agents/shell.md +++ b/content/manuals/ai/sandboxes/agents/shell.md @@ -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: diff --git a/content/manuals/ai/sandboxes/faq.md b/content/manuals/ai/sandboxes/faq.md index 4f83d2ce515..572a66c66f9 100644 --- a/content/manuals/ai/sandboxes/faq.md +++ b/content/manuals/ai/sandboxes/faq.md @@ -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 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. diff --git a/content/manuals/ai/sandboxes/security/credentials.md b/content/manuals/ai/sandboxes/security/credentials.md index 644646f51c9..9c1dbae38f4 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,23 @@ $ 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 +``` + +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 @@ -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-`). 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 — 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). 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