Merge pull request #24167 from dvdksn/sandboxes-v0.12-followups

sandboxes v0.12 followups

Author: dvdksn

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

@@ -7,7 +7,7 @@ keywords: docker, sandboxes, opencode, ai agent, multi-provider, authentication,
 weight: 50
 ---
 
-{{< summary-bar feature_name="Docker Sandboxes" >}}
+{{< summary-bar feature_name="Docker Sandboxes v0.12" >}}
 
 This guide covers authentication, configuration, and usage of OpenCode in a
 sandboxed environment.

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

@@ -7,7 +7,7 @@ keywords: docker, sandboxes, shell, custom, manual setup, development environmen
 weight: 80
 ---
 
-{{< summary-bar feature_name="Docker Sandboxes" >}}
+{{< summary-bar feature_name="Docker Sandboxes v0.12" >}}
 
 This guide covers the Shell sandbox, a minimal environment for custom agent
 installation and development. Unlike other agent sandboxes, Shell doesn't

content/manuals/ai/sandboxes/get-started.md

@@ -46,9 +46,9 @@ Follow these steps to run a sandbox with Claude Code:
    2. Restart Docker Desktop so the daemon picks up the new environment variable.
 
    Alternatively, you can skip this step and authenticate interactively when
-   Claude Code starts. If no credentials are found, you'll be prompted to log
-   in. Note that interactive authentication requires you to authenticate for
-   each workspace separately.
+   Claude Code starts. Interactive authentication is less secure and requires
+   you to re-authenticate for each workspace. See
+   [Credential security](workflows.md#credential-security) for details.
 
 2. Create and run a sandbox for Claude Code for your workspace:
 

content/manuals/ai/sandboxes/migration.md

@@ -120,15 +120,13 @@ template.
 4. Create a new sandbox with your template:
 
    ```console
-   $ docker sandbox create --template my-sandbox-template:v1 \
-       --pull-template=never \
-       claude ~/project
+   $ docker sandbox create --template my-sandbox-template:v1 claude ~/project
    ```
 
    > [!NOTE]
    > The `--pull-template` flag was introduced in Docker Desktop 4.61 (Sandbox
-   > version 0.12). For Docker Desktop 4.58–4.60, substitute
-   > `--pull-template=never` with `--load-local-template`.
+   > version 0.12). On Docker Desktop 4.58–4.60, use `--load-local-template`
+   > to use a locally-built template image.
 
 5. Run the sandbox:
 

content/manuals/ai/sandboxes/templates.md

@@ -68,11 +68,11 @@ $ docker build -t my-template:v1 .
 Use it directly from your local Docker daemon:
 
 ```console
-$ docker sandbox run --pull-template never -t my-template:v1 claude [PATH]
+$ docker sandbox run -t my-template:v1 claude [PATH]
 ```
 
-The `--pull-template never` flag tells the sandbox to use local template
-images.
+The default `--pull-template missing` policy finds the image in your local
+Docker daemon without pulling from a registry.
 
 To share the template with others, push it to a registry:
 
@@ -92,19 +92,20 @@ Docker Sandboxes caches template images to speed up sandbox creation. The
 
 - `--pull-template missing` (default)
 
-  Pull the image only if it's not already cached locally. First sandbox
-  creation automatically pulls the image, and subsequent sandboxes are created
-  quickly because the image is cached.
+  Use the local image if present, otherwise pull from the registry. Works for
+  both locally-built images and registry images. On first use, registry images
+  are pulled and cached; subsequent sandboxes reuse the cache.
 
 - `--pull-template always`
 
-  Always pull the image from the registry before creating the sandbox, even if
-  it's cached. Slower than `missing` but guarantees freshness.
+  Always pull the latest image from the registry and update the host cache.
+  The VM uses the refreshed cache. Slower than `missing` but guarantees the
+  sandbox uses the latest version. Requires a registry image.
 
 - `--pull-template never`
 
-  Use only cached images. Never pull from a registry. Fails if the image isn't
-  in the cache.
+  Never use the host cache. The sandbox VM pulls the image directly from the
+  registry on every startup. Requires a registry image.
 
 The cache stores template images separately from your host Docker daemon's
 images. Cached images persist across sandbox creation and deletion, but are
@@ -130,11 +131,11 @@ $ docker sandbox save claude-project my-template:v1
 ✓ Saved sandbox as my-template:v1
 ```
 
-This saves the image to your local Docker daemon. Use `--pull-template never`
-to create new sandboxes from it:
+This saves the image to your local Docker daemon. The default pull policy finds
+the image locally:
 
 ```console
-$ docker sandbox run --pull-template never -t my-template:v1 claude ~/other-project
+$ docker sandbox run -t my-template:v1 claude ~/other-project
 ```
 
 To save as a tar file instead (for example, to transfer to another machine):

content/manuals/ai/sandboxes/workflows.md

@@ -117,6 +117,22 @@ To preserve a configured environment, create a [Custom template](templates.md).
 
 ## Security considerations
 
+### Credential security
+
+Set API keys as environment variables on the host rather than authenticating
+interactively inside a sandbox. When you set credentials on the host, Docker
+Sandboxes proxies API calls from the sandbox through the host daemon, so the
+agent never has direct access to the raw key.
+
+When you authenticate interactively, credentials are stored inside the sandbox
+where the agent can read them directly. This creates a risk of credential
+exfiltration if the agent is compromised or behaves unexpectedly.
+
+Interactive authentication also requires you to re-authenticate for each
+workspace separately.
+
+### Workspace trust
+
 Agents running in sandboxes automatically trust the workspace directory without
 prompting. This enables agents to work freely within the isolated environment.
 
@@ -185,6 +201,8 @@ workspace files.
 
 ## Multiple workspaces
 
+{{< summary-bar feature_name="Docker Sandboxes v0.12" >}}
+
 Mount multiple directories into a single sandbox for working with related
 projects or when the agent needs access to documentation and shared libraries.
 

content/reference/cli/docker/sandbox/create/opencode.md

@@ -4,3 +4,5 @@ datafile: docker_sandbox_create_opencode
 title: docker sandbox create opencode
 layout: cli
 ---
+
+{{< summary-bar feature_name="Docker Sandboxes v0.12" >}}

content/reference/cli/docker/sandbox/create/shell.md

@@ -4,3 +4,5 @@ datafile: docker_sandbox_create_shell
 title: docker sandbox create shell
 layout: cli
 ---
+
+{{< summary-bar feature_name="Docker Sandboxes v0.12" >}}

data/summary.yaml

@@ -192,6 +192,9 @@ Docker Projects:
 Docker Sandboxes:
   availability: Experimental
   requires: Docker Desktop [4.58](/manuals/desktop/release-notes.md#4580) or later
+Docker Sandboxes v0.12:
+  availability: Experimental
+  requires: Docker Desktop [4.61](/manuals/desktop/release-notes.md#4610) or later
 Docker Scout exceptions:
   availability: Experimental
   requires: Docker Scout CLI [1.15.0](/manuals/scout/release-notes/cli.md#1150) and later