Merge pull request docker#25161 from dvdksn/sbx-agent-args-config-docs

sbx: document new arg-passing behavior for agents

Author: dvdksn

content/manuals/ai/sandboxes/agents/claude-code.md

@@ -54,19 +54,27 @@ available inside the sandbox. See
 [Why doesn't the sandbox use my user-level agent configuration?](../faq.md#why-doesnt-the-sandbox-use-my-user-level-agent-configuration)
 for workarounds.
 
-Any Claude Code CLI options can be passed after the `--` separator:
+### Default startup command
+
+Without extra args, the sandbox runs:
+
+```text
+claude --dangerously-skip-permissions
+```
+
+Args after `--` replace these defaults rather than being appended. To keep
+`--dangerously-skip-permissions`, include it yourself:
 
 ```console
-$ sbx run claude --name my-sandbox -- --continue
+$ sbx run claude -- --dangerously-skip-permissions -c
 ```
 
 See the [Claude Code CLI reference](https://code.claude.com/docs/en/cli-reference)
 for available options.
 
 ## Base image
 
-The sandbox uses `docker/sandbox-templates:claude-code` and launches Claude Code
-with `--dangerously-skip-permissions` by default. See
+The sandbox uses `docker/sandbox-templates:claude-code`. See
 [Templates](../customize/templates.md) to build your own image on top of
 this base.
 

content/manuals/ai/sandboxes/agents/codex.md

@@ -62,18 +62,24 @@ available inside the sandbox. See
 [Why doesn't the sandbox use my user-level agent configuration?](../faq.md#why-doesnt-the-sandbox-use-my-user-level-agent-configuration)
 for workarounds.
 
-The sandbox runs Codex without approval prompts by default. Pass additional
-Codex CLI options after `--`:
+### Default startup command
+
+Without extra args, the sandbox runs:
+
+```text
+codex --dangerously-bypass-approvals-and-sandbox
+```
+
+Args after `--` replace these defaults rather than being appended. To keep
+the flag, include it yourself:
 
 ```console
-$ sbx run codex --name <sandbox-name> -- <codex-options>
+$ sbx run codex -- --dangerously-bypass-approvals-and-sandbox "fix the build"
 ```
 
 ## Base image
 
 Template: `docker/sandbox-templates:codex`
 
-Preconfigured to run without approval prompts.
-
 See [Customize](../customize/) to pre-install tools or customize this
 environment.

content/manuals/ai/sandboxes/agents/copilot.md

@@ -51,19 +51,26 @@ for workarounds.
 Copilot is configured to trust the workspace directory by default, so it
 operates without repeated confirmations for workspace files.
 
-### Pass options at runtime
+### Default startup command
 
-Pass Copilot CLI options after `--`:
+Without extra args, the sandbox runs:
+
+```text
+copilot --yolo
+```
+
+Args after `--` replace these defaults rather than being appended. To keep
+`--yolo`, include it yourself:
 
 ```console
-$ sbx run copilot --name <sandbox-name> -- <copilot-options>
+$ sbx run copilot -- --yolo -p "review this PR"
 ```
 
 ## Base image
 
 Template: `docker/sandbox-templates:copilot`
 
-Preconfigured to trust the workspace directory and run without approval prompts.
+Preconfigured to trust the workspace directory.
 
 See [Customize](../customize/) to pre-install tools or customize this
 environment.

content/manuals/ai/sandboxes/agents/cursor.md

@@ -57,21 +57,28 @@ for workarounds.
 
 Cursor reads `AGENTS.md` from the workspace for agent-specific instructions.
 
-The sandbox runs Cursor in YOLO mode by default, which executes commands
-without approval prompts. Pass additional `cursor-agent` CLI options after
-`--`:
+### Default startup command
+
+Without extra args, the sandbox runs:
+
+```text
+cursor-agent --yolo
+```
+
+Args after `--` replace these defaults rather than being appended. To keep
+`--yolo`, include it yourself:
 
 ```console
-$ sbx run cursor --name <sandbox-name> -- <cursor-options>
+$ sbx run cursor -- --yolo -p "refactor this"
 ```
 
 ## Base image
 
 Template: `docker/sandbox-templates:cursor-agent-docker`
 
-Preconfigured to run in YOLO mode with HTTP/1.1 and server-sent events for
-agent traffic so requests flow through the host proxy. Authentication state
-is persisted across sandbox restarts.
+Preconfigured with HTTP/1.1 and server-sent events for agent traffic so
+requests flow through the host proxy. Authentication state is persisted across
+sandbox restarts.
 
 See [Customize](../customize/) to pre-install tools or customize this
 environment.

content/manuals/ai/sandboxes/agents/docker-agent.md

@@ -50,22 +50,23 @@ sandbox. See
 [Why doesn't the sandbox use my user-level agent configuration?](../faq.md#why-doesnt-the-sandbox-use-my-user-level-agent-configuration)
 for workarounds.
 
-The sandbox runs Docker Agent without approval prompts by default. Pass
-additional CLI options after `--`:
+### Default startup command
 
-```console
-$ sbx run docker-agent --name my-sandbox -- <options>
+Without extra args, the sandbox runs:
+
+```text
+docker-agent run --yolo
 ```
 
-For example, to specify a custom `agent.yml` configuration file:
+Args after `--` replace these defaults rather than being appended. To keep
+`run --yolo`, include them yourself:
 
 ```console
-$ sbx run docker-agent -- agent.yml
+$ sbx run docker-agent -- run --yolo agent.yml
 ```
 
 ## Base image
 
-The sandbox uses `docker/sandbox-templates:docker-agent` and launches Docker
-Agent without approval prompts by default. See
+The sandbox uses `docker/sandbox-templates:docker-agent`. See
 [Templates](../customize/templates.md) to build your own image on top of
 this base.

content/manuals/ai/sandboxes/agents/droid.md

@@ -56,11 +56,13 @@ sandbox. See
 [Why doesn't the sandbox use my user-level agent configuration?](../faq.md#why-doesnt-the-sandbox-use-my-user-level-agent-configuration)
 for workarounds.
 
-The sandbox runs Droid without approval prompts by default. Pass additional
-`droid` CLI options after `--`:
+### Default startup command
+
+The sandbox runs `droid` with no implicit flags. Args after `--` are passed
+straight through:
 
 ```console
-$ sbx run droid --name <sandbox-name> -- <droid-options>
+$ sbx run droid -- exec "fix the build"
 ```
 
 ## Base image

content/manuals/ai/sandboxes/agents/gemini.md

@@ -54,21 +54,30 @@ available inside the sandbox. See
 [Why doesn't the sandbox use my user-level agent configuration?](../faq.md#why-doesnt-the-sandbox-use-my-user-level-agent-configuration)
 for workarounds.
 
-The sandbox runs Gemini without approval prompts by default and disables
-Gemini's built-in sandbox tool (since the sandbox itself provides isolation).
-Pass additional Gemini CLI options after `--`:
+The sandbox disables Gemini's built-in sandbox tool (since the sandbox itself
+provides isolation).
+
+### Default startup command
+
+Without extra args, the sandbox runs:
+
+```text
+gemini --yolo
+```
+
+Args after `--` replace these defaults rather than being appended. To keep
+`--yolo`, include it yourself:
 
 ```console
-$ sbx run gemini --name <sandbox-name> -- <gemini-options>
+$ sbx run gemini -- --yolo -p "explain this"
 ```
 
 ## Base image
 
 Template: `docker/sandbox-templates:gemini`
 
 Gemini is configured to disable its built-in OAuth flow. Authentication is
-managed through the proxy with API keys. Preconfigured to run without
-approval prompts.
+managed through the proxy with API keys.
 
 See [Customize](../customize/) to pre-install tools or customize this
 environment.

content/manuals/ai/sandboxes/agents/kiro.md

@@ -75,23 +75,30 @@ sandbox. See
 for workarounds.
 
 Kiro requires minimal configuration. The agent runs with trust-all-tools mode
-by default, which lets it execute commands without repeated approval
-prompts.
+by default, which lets it execute commands without repeated approval prompts.
 
-### Pass options at runtime
+### Default startup command
 
-Pass Kiro CLI options after `--`:
+Without extra args, the sandbox runs:
+
+```text
+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:
 
 ```console
-$ sbx run kiro --name <sandbox-name> -- <kiro-options>
+$ sbx run kiro -- chat --trust-all-tools --resume
 ```
 
 ## Base image
 
 Template: `docker/sandbox-templates:kiro`
 
-Preconfigured to run without approval prompts. Authentication state is
-persisted across sandbox restarts.
+Authentication state is persisted across sandbox restarts.
 
 See [Customize](../customize/) to pre-install tools or customize this
 environment.

content/manuals/ai/sandboxes/agents/opencode.md

@@ -63,18 +63,13 @@ OpenCode uses a TUI interface and doesn't require extensive configuration
 files. The agent prompts you to select a provider when it starts, and you can
 switch providers during a session.
 
-### Pass options at runtime
+### Default startup command
 
-Pass OpenCode CLI options after `--`:
+The sandbox runs `opencode` with no implicit flags. Args after `--` are passed
+straight through. For example, to resume an existing session:
 
 ```console
-$ sbx run opencode --name <sandbox-name> -- <opencode-options>
-```
-
-For example, to resume an existing session in a named sandbox:
-
-```console
-$ sbx run <sandbox-name> -- -s <session-id>
+$ sbx run opencode -- -s <session-id>
 ```
 
 ### TUI mode

content/manuals/ai/sandboxes/agents/shell.md

@@ -21,6 +21,16 @@ command instead of an interactive shell, pass it after `--`:
 $ 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:
+
+```console
+$ sbx run shell -- -l -c "echo hi"
+```
+
 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: