sandboxes: add sbx documentation

Add full documentation for the sbx CLI sandbox experience including
get-started, usage guide, architecture, agents (claude-code, codex,
copilot, gemini, kiro, opencode, cagent, custom-environments),
security (isolation, credentials, policy, workspace trust),
troubleshooting, and FAQ. Update _index.md as the section landing
page.

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

Author: dvdksn

_vale/config/vocabularies/Docker/accept.txt

@@ -237,6 +237,7 @@ Turtlesim
 typesafe
 Ubuntu
 ufw
+uv
 umask
 uncaptured
 Uncaptured
@@ -259,6 +260,9 @@ windowsfilter
 WireMock
 workdir
 WORKDIR
+[Ww]orktrees?
+[Pp]assthrough
+[Pp]reconfigured
 Xdebug
 xUnit
 XQuartz

content/manuals/ai/sandboxes/_index.md

@@ -5,11 +5,66 @@ weight: 20
 params:
   sidebar:
     group: AI
+    badge:
+      color: violet
+      text: Experimental
 ---
 
-Docker Sandboxes let you run AI coding agents in isolated environments using
-the `docker sandbox` command. Sandboxes require Docker Desktop and run agents
-in microVMs with private Docker daemons.
+{{< summary-bar feature_name="Docker Sandboxes sbx" >}}
 
-For setup instructions and usage details, see the
-[Docker Desktop sandboxes](docker-desktop.md) page.
+Docker Sandboxes run AI coding agents in isolated microVM sandboxes. Each
+sandbox gets its own Docker daemon, filesystem, and network — the agent can
+build containers, install packages, and modify files without touching your host
+system.
+
+## Get started
+
+Install the `sbx` CLI and sign in:
+
+{{< tabs >}}
+{{< tab name="macOS" >}}
+
+```console
+$ brew install docker/tap/sbx
+$ sbx login
+```
+
+{{< /tab >}}
+{{< tab name="Windows" >}}
+
+```powershell
+> winget install -h Docker.sbx
+> sbx login
+```
+
+{{< /tab >}}
+{{< /tabs >}}
+
+Then launch an agent in a sandbox:
+
+```console
+$ cd ~/my-project
+$ sbx run claude
+```
+
+See the [get started guide](get-started.md) for a full walkthrough, or jump to
+the [usage guide](usage.md) for common patterns.
+
+## Learn more
+
+- [Agents](agents/) — supported agents and per-agent configuration
+- [Custom environments](agents/custom-environments.md) — build reusable sandbox
+  images with pre-installed tools
+- [Architecture](architecture.md) — microVM isolation, workspace mounting,
+  networking
+- [Security](security/) — isolation model, credential handling, network
+  policies, workspace trust
+- [CLI reference](/reference/cli/sbx/) — full list of `sbx` commands and options
+- [Troubleshooting](troubleshooting.md) — common issues and fixes
+- [FAQ](faq.md) — login requirements, telemetry, etc
+
+## Docker Desktop integration
+
+Docker Desktop also includes a [built-in sandbox command](docker-desktop.md)
+(`docker sandbox`) with a subset of features. The `sbx` CLI is recommended for
+most use cases.

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

@@ -0,0 +1,21 @@
+---
+title: Supported agents
+linkTitle: Agents
+weight: 30
+description: AI coding agents supported by Docker Sandboxes.
+---
+
+{{< summary-bar feature_name="Docker Sandboxes sbx" >}}
+
+Docker Sandboxes runs the following agents out of the box:
+
+- [Claude Code](claude-code/)
+- [Codex](codex/)
+- [Copilot](copilot/)
+- [Gemini](gemini/)
+- [Kiro](kiro/)
+- [OpenCode](opencode/)
+- [Docker Agent](docker-agent/)
+
+Want to pre-install tools or customize an agent's environment?
+See [Custom environments](custom-environments/).

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

@@ -0,0 +1,72 @@
+---
+title: Claude Code
+weight: 10
+description: |
+  Use Claude Code in Docker Sandboxes with authentication, configuration, and
+  YOLO mode for AI-assisted development.
+---
+
+{{< summary-bar feature_name="Docker Sandboxes sbx" >}}
+
+Official documentation: [Claude Code](https://code.claude.com/docs)
+
+## Quick start
+
+Launch Claude Code in a sandbox by pointing it at a project directory:
+
+```console
+$ sbx run claude ~/my-project
+```
+
+The workspace parameter defaults to the current directory, so `sbx run claude`
+from inside your project works too. To start Claude with a specific prompt:
+
+```console
+$ sbx run claude --name my-sandbox -- "Add error handling to the login function"
+```
+
+Everything after `--` is passed directly to Claude Code. You can also pipe in a
+prompt from a file with `-- "$(cat prompt.txt)"`.
+
+## Authentication
+
+Claude Code requires either an Anthropic API key or a Claude subscription.
+
+**API key**: Store your key using
+[stored secrets](../security/credentials.md#stored-secrets):
+
+```console
+$ sbx secret set -g anthropic
+```
+
+Alternatively, export the `ANTHROPIC_API_KEY` environment variable in your
+shell before running the sandbox. See
+[Credentials](../security/credentials.md) for details on both methods.
+
+**Claude subscription**: If no API key is set, Claude Code prompts you to
+authenticate interactively using OAuth. The proxy handles the OAuth flow, so
+credentials aren't stored inside the sandbox.
+
+## Configuration
+
+Sandboxes don't pick up user-level configuration from your host, such as
+`~/.claude`. Only project-level configuration in the working directory is
+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:
+
+```console
+$ sbx run claude --name my-sandbox -- --continue
+```
+
+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
+[Custom environments](custom-environments.md) to build your own image on
+top of this base.

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

@@ -0,0 +1,66 @@
+---
+title: Codex
+weight: 20
+description: |
+  Use OpenAI Codex in Docker Sandboxes with API key authentication and YOLO
+  mode configuration.
+---
+
+{{< summary-bar feature_name="Docker Sandboxes sbx" >}}
+
+This guide covers authentication, configuration, and usage of Codex in a
+sandboxed environment.
+
+Official documentation: [Codex CLI](https://developers.openai.com/codex/cli)
+
+## Quick start
+
+Create a sandbox and run Codex for a project directory:
+
+```console
+$ sbx run codex ~/my-project
+```
+
+The workspace parameter is optional and defaults to the current directory:
+
+```console
+$ cd ~/my-project
+$ sbx run codex
+```
+
+## Authentication
+
+Codex requires an OpenAI API key. Store your key using
+[stored secrets](../security/credentials.md#stored-secrets):
+
+```console
+$ sbx secret set -g openai
+```
+
+Alternatively, export the `OPENAI_API_KEY` environment variable in your shell
+before running the sandbox. See
+[Credentials](../security/credentials.md) for details on both methods.
+
+## Configuration
+
+Sandboxes don't pick up user-level configuration from your host, such as
+`~/.codex`. Only project-level configuration in the working directory is
+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 `--`:
+
+```console
+$ sbx run codex --name <sandbox-name> -- <codex-options>
+```
+
+## Base image
+
+Template: `docker/sandbox-templates:codex`
+
+Preconfigured to run without approval prompts.
+
+See [Custom environments](custom-environments.md) to pre-install tools or
+customize this environment.

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

@@ -0,0 +1,70 @@
+---
+title: Copilot
+weight: 30
+description: |
+  Use GitHub Copilot in Docker Sandboxes with GitHub token authentication and
+  trusted folder configuration.
+---
+
+{{< summary-bar feature_name="Docker Sandboxes sbx" >}}
+
+This guide covers authentication, configuration, and usage of GitHub Copilot
+in a sandboxed environment.
+
+Official documentation: [GitHub Copilot CLI](https://docs.github.com/en/copilot/how-tos/copilot-cli)
+
+## Quick start
+
+Create a sandbox and run Copilot for a project directory:
+
+```console
+$ sbx run copilot ~/my-project
+```
+
+The workspace parameter is optional and defaults to the current directory:
+
+```console
+$ cd ~/my-project
+$ sbx run copilot
+```
+
+## Authentication
+
+Copilot requires a GitHub token with Copilot access. Store your token using
+[stored secrets](../security/credentials.md#stored-secrets):
+
+```console
+$ echo "$(gh auth token)" | sbx secret set -g github
+```
+
+Alternatively, export the `GH_TOKEN` or `GITHUB_TOKEN` environment variable in
+your shell before running the sandbox. See
+[Credentials](../security/credentials.md) for details on both methods.
+
+## Configuration
+
+Sandboxes don't pick up user-level configuration from your host. Only
+project-level configuration in the working directory is 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.
+
+Copilot is configured to trust the workspace directory by default, so it
+operates without repeated confirmations for workspace files.
+
+### Pass options at runtime
+
+Pass Copilot CLI options after `--`:
+
+```console
+$ sbx run copilot --name <sandbox-name> -- <copilot-options>
+```
+
+## Base image
+
+Template: `docker/sandbox-templates:copilot`
+
+Preconfigured to trust the workspace directory and run without approval prompts.
+
+See [Custom environments](custom-environments.md) to pre-install tools or
+customize this environment.