sandboxes: add agent-specific documentation

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>

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
@@ -196,6 +198,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
 
@@ -49,9 +49,10 @@ $ 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
 
@@ -85,14 +86,16 @@ that workspace.
 
 Docker Sandboxes works with multiple AI coding agents:
 
-- **Claude Code** - Anthropic's coding agent
-- **OpenCode** - Multi-provider agent with AGENTS.md support
+- **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
-- **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)
+
+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
 ---
@@ -20,7 +21,7 @@ inside microVMs with private Docker daemons.
 | cagent      | `cagent`   | Experimental | In development                            |
 | Kiro        | `kiro`     | Experimental | In development                            |
 | OpenCode    | `opencode` | Experimental | In development                            |
-| Shell       | `shell`    | Experimental | Minimal environment for manual setup      |
+| Custom shell | `shell`   | Experimental | Minimal environment for manual setup      |
 
 ## Experimental status
 
@@ -44,6 +45,19 @@ $ 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
 
 Each agent has its own credential requirements and authentication flow.
@@ -52,7 +66,14 @@ 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:
@@ -42,8 +47,7 @@ This starts Claude and immediately processes the prompt.
 
 ## Authentication
 
-Claude Code requires an Anthropic API key. Credentials are scoped per sandbox
-and must be provided through environment variables or interactive login.
+Claude Code requires an Anthropic API key. Credentials are scoped per sandbox.
 
 ### Environment variable (recommended)
 
@@ -85,7 +89,7 @@ When using interactive authentication:
 - 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
 
@@ -104,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.