Merge pull request #24102 from dvdksn/sandboxes-461

sandboxes v0.12.0

Author: dvdksn

_vale/config/vocabularies/Docker/accept.txt

@@ -97,6 +97,7 @@ Google
 Grafana
 Gravatar
 gRPC
+Groq
 Grype
 HyperKit
 inferencing
@@ -115,6 +116,7 @@ JFrog
 JUnit
 Kata
 Kerberos
+Kiro
 Kitematic
 Kubeadm
 kubectl
@@ -198,6 +200,7 @@ stargz
 stdin
 stdout
 subfolder
+sudo
 subvolume
 Syft
 syntaxes

content/manuals/ai/sandboxes/_index.md

@@ -13,8 +13,8 @@ params:
 {{< summary-bar feature_name="Docker Sandboxes" >}}
 
 Docker Sandboxes lets you run AI coding agents in isolated environments on your
-machine. If you're building with agents like Claude Code, Sandboxes provides a
-secure way to give agents autonomy without compromising your system.
+machine. Sandboxes provides a secure way to give agents autonomy without
+compromising your system.
 
 ## Why use Docker Sandboxes
 
@@ -45,12 +45,14 @@ coding agents, see [Comparison to alternatives](./architecture.md#comparison-to-
 To create and run a sandbox:
 
 ```console
-$ docker sandbox run claude ~/my-project
+$ cd ~/my-project
+$ docker sandbox run claude
 ```
 
-This command creates a sandbox for your workspace (`~/my-project`) and starts
-the Claude Code agent inside it. The agent can now work with your code, install
-tools, and run containers inside the isolated sandbox.
+Replace `claude` with your [preferred agent](./agents/_index.md). This command
+creates a sandbox for your workspace (`~/my-project`) and starts the agent. The
+agent can now work with your code, install tools, and run containers inside the
+isolated sandbox.
 
 ## How it works
 
@@ -84,12 +86,16 @@ that workspace.
 
 Docker Sandboxes works with multiple AI coding agents:
 
-- **Claude Code** - Anthropic's coding agent
-- **Codex** - OpenAI's Codex agent (partial support; in development)
-- **Copilot** - GitHub Copilot agent (partial support; in development)
-- **Gemini** - Google's Gemini agent (partial support; in development)
-- **cagent** - Docker's [cagent](/ai/cagent/) (partial support; in development)
-- **Kiro** - by AWS (partial support; in development)
+- **Claude Code** - Anthropic's coding agent (production-ready)
+- **Codex** - OpenAI's Codex agent (in development)
+- **Copilot** - GitHub Copilot agent (in development)
+- **Gemini** - Google's Gemini agent (in development)
+- **OpenCode** - Multi-provider agent with TUI interface (in development)
+- **cagent** - Docker's multi-provider coding agent (in development)
+- **Kiro** - Interactive agent with device flow auth (in development)
+- **Shell** - Minimal sandbox for manual agent installation
+
+For detailed configuration instructions, see [Supported agents](agents/).
 
 ## Get started
 

content/manuals/ai/sandboxes/agents.md …nt/manuals/ai/sandboxes/agents/_index.mdcontent/manuals/ai/sandboxes/agents.md renamed to content/manuals/ai/sandboxes/agents/_index.md content/manuals/ai/sandboxes/agents.md renamed to content/manuals/ai/sandboxes/agents/_index.md

@@ -1,5 +1,6 @@
 ---
 title: Supported agents
+linkTitle: Agents
 description: AI coding agents supported by Docker Sandboxes with experimental status and configuration details.
 weight: 50
 ---
@@ -11,14 +12,16 @@ inside microVMs with private Docker daemons.
 
 ## Supported agents
 
-| Agent       | Command    | Status       | Notes                      |
-| ----------- | ---------- | ------------ | -------------------------- |
-| Claude Code | `claude`   | Experimental | Most tested implementation |
-| Codex       | `codex`    | Experimental | In development             |
-| Copilot     | `copilot`  | Experimental | In development             |
-| Gemini      | `gemini`   | Experimental | In development             |
-| cagent      | `cagent`   | Experimental | In development             |
-| Kiro        | `kiro`     | Experimental | In development             |
+| Agent       | Command    | Status       | Notes                                     |
+| ----------- | ---------- | ------------ | ----------------------------------------- |
+| Claude Code | `claude`   | Experimental | Most tested implementation                |
+| Codex       | `codex`    | Experimental | In development                            |
+| Copilot     | `copilot`  | Experimental | In development                            |
+| Gemini      | `gemini`   | Experimental | In development                            |
+| cagent      | `cagent`   | Experimental | In development                            |
+| Kiro        | `kiro`     | Experimental | In development                            |
+| OpenCode    | `opencode` | Experimental | In development                            |
+| Custom shell | `shell`   | Experimental | Minimal environment for manual setup      |
 
 ## Experimental status
 
@@ -36,23 +39,41 @@ Use sandboxes for development and testing, not production workloads.
 The agent type is specified when creating a sandbox:
 
 ```console
-$ docker sandbox create claude ~/my-project
-$ docker sandbox create codex ~/my-project
-$ docker sandbox create copilot ~/my-project
-$ docker sandbox create gemini ~/my-project
-$ docker sandbox create cagent ~/my-project
-$ docker sandbox create kiro ~/my-project
+$ docker sandbox create AGENT [PATH] [PATH...]
 ```
 
 Each agent runs in its own isolated sandbox. The agent type is bound to the
 sandbox when created and cannot be changed later.
 
+## Template environment
+
+All agent templates share a common base environment:
+
+- Ubuntu 25.10 base
+- Development tools: Docker CLI (with Buildx and Compose), Git, GitHub CLI, Node.js, Go, Python 3, uv, make, jq, ripgrep
+- Non-root `agent` user with sudo access
+- Private Docker daemon for running additional containers
+- Package managers: apt, pip, npm
+
+Individual agents add their specific CLI tools on top of this base. See
+[Custom templates](../templates.md) to build your own agent images.
+
 ## Agent-specific configuration
 
-Different agents may require different authentication methods or configuration.
+Each agent has its own credential requirements and authentication flow.
+Credentials are scoped per agent and must be provided specifically for that
+agent (no fallback authentication methods are used).
+
 See the agent-specific documentation:
 
-- [Claude Code configuration](claude-code.md)
+- [Claude Code](./claude-code.md)
+- [cagent](./cagent.md)
+- [Codex](./codex.md)
+- [Copilot](./copilot.md)
+- [Gemini](./gemini.md)
+- [Kiro](./kiro.md)
+- [OpenCode](./opencode.md)
+- [Custom shell](./shell.md)
 
 ## Requirements
 
@@ -61,9 +82,3 @@ See the agent-specific documentation:
   - macOS with virtualization.framework
   - Windows with Hyper-V {{< badge color=violet text=Experimental >}}
 - API keys or credentials for your chosen agent
-
-## Next steps
-
-- [Claude Code configuration](claude-code.md)
-- [Custom templates](templates.md)
-- [Using sandboxes effectively](workflows.md)

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

@@ -0,0 +1,96 @@
+---
+title: cagent sandbox
+description: |
+  Use Docker cagent in Docker Sandboxes with multi-provider authentication
+  supporting OpenAI, Anthropic, and more.
+keywords: docker, sandboxes, cagent, ai agent, multi-provider, authentication
+weight: 60
+---
+
+{{< summary-bar feature_name="Docker Sandboxes" >}}
+
+This guide covers authentication, configuration, and usage of Docker cagent in
+a sandboxed environment. [cagent](/ai/cagent/) is Docker's open source coding
+agent that supports multiple providers.
+
+## Quick start
+
+Create a sandbox and run cagent for a project directory:
+
+```console
+$ docker sandbox run cagent ~/my-project
+```
+
+The workspace parameter is optional and defaults to the current directory:
+
+```console
+$ cd ~/my-project
+$ docker sandbox run cagent
+```
+
+## Authentication
+
+cagent uses proxy-managed authentication for all supported providers. Docker
+Sandboxes intercepts API requests and injects credentials transparently. You
+provide your API keys through environment variables, and the sandbox handles
+credential management.
+
+### Supported providers
+
+Configure one or more providers by setting environment variables:
+
+```plaintext {title="~/.bashrc or ~/.zshrc"}
+export OPENAI_API_KEY=sk-xxxxx
+export ANTHROPIC_API_KEY=sk-ant-xxxxx
+export GOOGLE_API_KEY=AIzaSyxxxxx
+export XAI_API_KEY=xai-xxxxx
+export NEBIUS_API_KEY=xxxxx
+export MISTRAL_API_KEY=xxxxx
+```
+
+You only need to configure the providers you want to use. cagent detects
+available credentials and routes requests to the appropriate provider.
+
+### Environment variable setup
+
+Docker Sandboxes use a daemon process that doesn't inherit environment
+variables from your current shell session. To make your API keys available to
+sandboxes, set them globally in your shell configuration file.
+
+Apply the changes:
+
+1. Source your shell configuration: `source ~/.bashrc` (or `~/.zshrc`)
+2. Restart Docker Desktop so the daemon picks up the new environment variables
+3. Create and run your sandbox:
+
+```console
+$ docker sandbox create cagent ~/project
+$ docker sandbox run <sandbox-name>
+```
+
+The sandbox detects the environment variables and uses them automatically.
+
+## Configuration
+
+cagent supports YOLO mode that disables safety checks and approval prompts.
+This mode grants the agent full access to your sandbox environment without
+interactive confirmation.
+
+### Pass options at runtime
+
+Pass cagent CLI options after the sandbox name and a `--` separator:
+
+```console
+$ docker sandbox run <sandbox-name> -- run --yolo
+```
+
+The `run --yolo` command starts cagent with approval prompts disabled.
+
+## Base image
+
+Template: `docker/sandbox-templates:cagent`
+
+cagent supports multiple LLM providers with automatic credential injection
+through the sandbox proxy. Launches with `run --yolo` by default.
+
+See [Custom templates](../templates.md) to build your own agent images.

…tent/manuals/ai/sandboxes/claude-code.md …nuals/ai/sandboxes/agents/claude-code.mdcontent/manuals/ai/sandboxes/claude-code.md renamed to content/manuals/ai/sandboxes/agents/claude-code.md content/manuals/ai/sandboxes/claude-code.md renamed to content/manuals/ai/sandboxes/agents/claude-code.md

@@ -1,14 +1,19 @@
 ---
-title: Configure Claude Code
-description: Learn how to configure Claude Code authentication, pass CLI options, and customize your sandboxed agent environment with Docker.
-weight: 30
+title: Claude Code sandbox
+description: |
+  Use Claude Code in Docker Sandboxes with authentication, configuration, and
+  YOLO mode for AI-assisted development.
+keywords: docker, sandboxes, claude code, anthropic, ai agent, authentication, configuration
+weight: 10
 ---
 
 {{< summary-bar feature_name="Docker Sandboxes" >}}
 
 This guide covers authentication, configuration files, and common options for
 running Claude Code in a sandboxed environment.
 
+Official documentation: [Claude Code](https://code.claude.com/docs)
+
 ## Quick start
 
 To create a sandbox and run Claude Code for a project directory:
@@ -17,6 +22,13 @@ To create a sandbox and run Claude Code for a project directory:
 $ docker sandbox run claude ~/my-project
 ```
 
+The workspace parameter is optional and defaults to the current directory:
+
+```console
+$ cd ~/my-project
+$ docker sandbox run claude
+```
+
 ### Pass a prompt directly
 
 Start Claude with a specific prompt:
@@ -35,7 +47,7 @@ This starts Claude and immediately processes the prompt.
 
 ## Authentication
 
-Claude Code requires an Anthropic API key. You can authenticate using an environment variable (recommended) or through interactive login.
+Claude Code requires an Anthropic API key. Credentials are scoped per sandbox.
 
 ### Environment variable (recommended)
 
@@ -66,15 +78,18 @@ The sandbox detects the environment variable and uses it automatically.
 
 ### Interactive authentication
 
-If no credentials are found, Claude Code prompts you to authenticate interactively when it starts. You can also trigger the login flow manually using the `/login` command within Claude Code.
+If the `ANTHROPIC_API_KEY` environment variable is not set, Claude Code prompts
+you to authenticate interactively when it starts. You can also trigger the login
+flow manually using the `/login` command within Claude Code.
 
 When using interactive authentication:
 
-- You'll need to authenticate for each workspace/sandbox separately
+- You must authenticate each sandbox separately
 - If the sandbox is removed or destroyed, you'll need to authenticate again when you recreate it
 - Authentication sessions aren't persisted outside the sandbox
+- No fallback authentication methods are used
 
-To avoid repeated authentication, use the `ANTHROPIC_API_KEY` environment variable method described above.
+To avoid repeated authentication, set the `ANTHROPIC_API_KEY` environment variable.
 
 ## Configuration
 
@@ -93,28 +108,13 @@ For example:
 $ docker sandbox run <sandbox-name> -- --continue
 ```
 
-See the [Claude Code CLI reference](https://docs.claude.com/en/docs/claude-code/cli-reference)
+See the [Claude Code CLI reference](https://code.claude.com/docs/en/cli-reference)
 for available options.
 
 ## Base image
 
-The Claude Code sandbox template is a container image that runs inside the
-sandbox VM. It includes:
-
-- Ubuntu-based environment with Claude Code
-- Development tools: Docker CLI, GitHub CLI, Node.js, Go, Python 3, Git, ripgrep, jq
-- Non-root `agent` user with sudo access
-- Private Docker daemon for running additional containers
-
-Claude launches with `--dangerously-skip-permissions` by default in sandboxes.
-
-You can build custom templates based on `docker/sandbox-templates:claude-code`.
-See [Custom templates](templates.md) for details.
+Template: `docker/sandbox-templates:claude-code`
 
-## Next steps
+Claude Code launches with `--dangerously-skip-permissions` by default in sandboxes.
 
-- [Using sandboxes effectively](workflows.md)
-- [Custom templates](templates.md)
-- [Network policies](network-policies.md)
-- [Troubleshooting](troubleshooting.md)
-- [CLI Reference](/reference/cli/docker/sandbox/)
+See [Custom templates](../templates.md) to build your own agent images.