diff --git a/_vale/config/vocabularies/Docker/accept.txt b/_vale/config/vocabularies/Docker/accept.txt index cdbf04825fac..0fff18d94036 100644 --- a/_vale/config/vocabularies/Docker/accept.txt +++ b/_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 diff --git a/content/manuals/ai/sandboxes/_index.md b/content/manuals/ai/sandboxes/_index.md index 161b89291389..777938c25591 100644 --- a/content/manuals/ai/sandboxes/_index.md +++ b/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,13 @@ 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 AGENT ``` 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. +the agent inside it. The agent can now work with your code, install tools, and +run containers inside the isolated sandbox. ## How it works @@ -84,12 +85,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 diff --git a/content/manuals/ai/sandboxes/agents.md b/content/manuals/ai/sandboxes/agents/_index.md similarity index 56% rename from content/manuals/ai/sandboxes/agents.md rename to content/manuals/ai/sandboxes/agents/_index.md index 8c9d60a77d16..7ebeba1064ac 100644 --- a/content/manuals/ai/sandboxes/agents.md +++ b/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) diff --git a/content/manuals/ai/sandboxes/agents/cagent.md b/content/manuals/ai/sandboxes/agents/cagent.md new file mode 100644 index 000000000000..d5505047cf3f --- /dev/null +++ b/content/manuals/ai/sandboxes/agents/cagent.md @@ -0,0 +1,109 @@ +--- +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 provider. + +## 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 +``` + +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 -- 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. + +## Development status + +cagent is in active development. Known considerations: + +- Features may change between Docker Desktop versions +- Multi-provider support is experimental +- Configuration format may evolve +- Some advanced features may be incomplete +- YOLO mode disables safety checks - use with caution + +Report issues and provide feedback through the Docker Sandboxes feedback +channels. diff --git a/content/manuals/ai/sandboxes/claude-code.md b/content/manuals/ai/sandboxes/agents/claude-code.md similarity index 58% rename from content/manuals/ai/sandboxes/claude-code.md rename to content/manuals/ai/sandboxes/agents/claude-code.md index 945dc700c888..180c33ea2103 100644 --- a/content/manuals/ai/sandboxes/claude-code.md +++ b/content/manuals/ai/sandboxes/agents/claude-code.md @@ -1,7 +1,10 @@ --- -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" >}} @@ -9,6 +12,8 @@ weight: 30 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 -- --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. diff --git a/content/manuals/ai/sandboxes/agents/codex.md b/content/manuals/ai/sandboxes/agents/codex.md new file mode 100644 index 000000000000..cfbfaf59dc13 --- /dev/null +++ b/content/manuals/ai/sandboxes/agents/codex.md @@ -0,0 +1,105 @@ +--- +title: Codex sandbox +description: | + Use OpenAI Codex in Docker Sandboxes with API key authentication and YOLO + mode configuration. +keywords: docker, sandboxes, codex, openai, ai agent, authentication, yolo mode +weight: 20 +--- + +{{< summary-bar feature_name="Docker Sandboxes" >}} + +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 +$ docker sandbox run codex ~/my-project +``` + +The workspace parameter is optional and defaults to the current directory: + +```console +$ cd ~/my-project +$ docker sandbox run codex +``` + +## Authentication + +Codex requires an OpenAI API key. Credentials are scoped per sandbox. + +Set the `OPENAI_API_KEY` environment variable in your shell configuration file. + +Docker Sandboxes use a daemon process that doesn't inherit environment +variables from your current shell session. To make your API key available to +sandboxes, set it globally in your shell configuration file. + +Add the API key to your shell configuration file: + +```plaintext {title="~/.bashrc or ~/.zshrc"} +export OPENAI_API_KEY=sk-xxxxx +``` + +Apply the changes: + +1. Source your shell configuration: `source ~/.bashrc` (or `~/.zshrc`) +2. Restart Docker Desktop so the daemon picks up the new environment variable +3. Create and run your sandbox: + +```console +$ docker sandbox create codex ~/project +$ docker sandbox run +``` + +The sandbox detects the environment variable and uses it automatically. + +## Configuration + +Codex supports a YOLO mode that disables safety checks and approval prompts. +This mode grants the agent full access to your sandbox environment without +interactive confirmation. + +Configure YOLO mode in `~/.codex/config.toml`: + +```toml +approval_policy = "never" +sandbox_mode = "danger-full-access" +``` + +With these settings, Codex runs without approval prompts. + +### Pass options at runtime + +Pass Codex CLI options after the sandbox name and a `--` separator: + +```console +$ docker sandbox run -- --dangerously-bypass-approvals-and-sandbox +``` + +This flag enables YOLO mode for a single session without modifying the +configuration file. + +## Base image + +Template: `docker/sandbox-templates:codex` + +Codex launches with `--dangerously-bypass-approvals-and-sandbox` by default when YOLO mode is configured. + +See [Custom templates](../templates.md) to build your own agent images. + +## Development status + +Codex is in active development. Known considerations: + +- Features may change between Docker Desktop versions +- Configuration format may evolve +- Some advanced features may be incomplete +- YOLO mode disables safety checks - use with caution + +Report issues and provide feedback through the Docker Sandboxes feedback +channels. diff --git a/content/manuals/ai/sandboxes/agents/copilot.md b/content/manuals/ai/sandboxes/agents/copilot.md new file mode 100644 index 000000000000..36d6afa589c0 --- /dev/null +++ b/content/manuals/ai/sandboxes/agents/copilot.md @@ -0,0 +1,114 @@ +--- +title: Copilot sandbox +description: | + Use GitHub Copilot in Docker Sandboxes with GitHub token authentication and + trusted folder configuration. +keywords: docker, sandboxes, copilot, github, ai agent, authentication, trusted folders +weight: 30 +--- + +{{< summary-bar feature_name="Docker Sandboxes" >}} + +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 +$ docker sandbox run copilot ~/my-project +``` + +The workspace parameter is optional and defaults to the current directory: + +```console +$ cd ~/my-project +$ docker sandbox run copilot +``` + +## Authentication + +Copilot requires a GitHub token with Copilot access. Credentials are scoped +per sandbox and must be provided through environment variables on the host. + +### Environment variable (recommended) + +Set the `GH_TOKEN` or `GITHUB_TOKEN` environment variable in your shell +configuration file. + +Docker Sandboxes use a daemon process that doesn't inherit environment +variables from your current shell session. To make your token available to +sandboxes, set it globally in your shell configuration file. + +Add the token to your shell configuration file: + +```plaintext {title="~/.bashrc or ~/.zshrc"} +export GH_TOKEN=ghp_xxxxx +``` + +Or use `GITHUB_TOKEN`: + +```plaintext {title="~/.bashrc or ~/.zshrc"} +export GITHUB_TOKEN=ghp_xxxxx +``` + +Apply the changes: + +1. Source your shell configuration: `source ~/.bashrc` (or `~/.zshrc`) +2. Restart Docker Desktop so the daemon picks up the new environment variable +3. Create and run your sandbox: + +```console +$ docker sandbox create copilot ~/project +$ docker sandbox run +``` + +The sandbox detects the environment variable and uses it automatically. + +## Configuration + +Copilot can be configured to trust specific folders, disabling safety prompts +for those locations. Configure trusted folders in `~/.copilot/config.json`: + +```json +{ + "trusted_folders": ["/workspace", "/home/agent/projects"] +} +``` + +Workspaces are mounted at `/workspace` by default, so trusting this path +allows Copilot to operate without repeated confirmations. + +### Pass options at runtime + +Pass Copilot CLI options after the sandbox name and a `--` separator: + +```console +$ docker sandbox run -- --yolo +``` + +The `--yolo` flag disables approval prompts for a single session without +modifying the configuration file. + +## Base image + +Template: `docker/sandbox-templates:copilot` + +Copilot launches with `--yolo` by default when trusted folders are configured. + +See [Custom templates](../templates.md) to build your own agent images. + +## Development status + +Copilot is in active development. Known considerations: + +- Features may change between Docker Desktop versions +- Configuration format may evolve +- Some advanced features may be incomplete +- Requires active GitHub Copilot subscription + +Report issues and provide feedback through the Docker Sandboxes feedback +channels. diff --git a/content/manuals/ai/sandboxes/agents/gemini.md b/content/manuals/ai/sandboxes/agents/gemini.md new file mode 100644 index 000000000000..c5bbd51e0f83 --- /dev/null +++ b/content/manuals/ai/sandboxes/agents/gemini.md @@ -0,0 +1,130 @@ +--- +title: Gemini sandbox +description: | + Use Google Gemini in Docker Sandboxes with proxy-managed authentication and + API key configuration. +keywords: docker, sandboxes, gemini, google, ai agent, authentication, proxy +weight: 40 +--- + +{{< summary-bar feature_name="Docker Sandboxes" >}} + +This guide covers authentication, configuration, and usage of Google Gemini in +a sandboxed environment. + +Official documentation: [Gemini CLI](https://geminicli.com/docs/) + +## Quick start + +Create a sandbox and run Gemini for a project directory: + +```console +$ docker sandbox run gemini ~/my-project +``` + +The workspace parameter is optional and defaults to the current directory: + +```console +$ cd ~/my-project +$ docker sandbox run gemini +``` + +## Authentication + +Gemini uses proxy-managed authentication. Docker Sandboxes intercepts API +requests and injects credentials transparently. You provide your API key +through environment variables on the host, and the sandbox handles credential +management. + +### Environment variable (recommended) + +Set the `GEMINI_API_KEY` or `GOOGLE_API_KEY` environment variable in your +shell configuration file. + +Docker Sandboxes use a daemon process that doesn't inherit environment +variables from your current shell session. To make your API key available to +sandboxes, set it globally in your shell configuration file. + +Add the API key to your shell configuration file: + +```plaintext {title="~/.bashrc or ~/.zshrc"} +export GEMINI_API_KEY=AIzaSyxxxxx +``` + +Or use `GOOGLE_API_KEY`: + +```plaintext {title="~/.bashrc or ~/.zshrc"} +export GOOGLE_API_KEY=AIzaSyxxxxx +``` + +Apply the changes: + +1. Source your shell configuration: `source ~/.bashrc` (or `~/.zshrc`) +2. Restart Docker Desktop so the daemon picks up the new environment variable +3. Create and run your sandbox: + +```console +$ docker sandbox create gemini ~/project +$ docker sandbox run +``` + +The sandbox detects the environment variable and uses it automatically. + +### Interactive authentication + +If neither `GEMINI_API_KEY` nor `GOOGLE_API_KEY` is set, Gemini prompts you to +sign in when it starts. + +When using interactive authentication: + +- 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, set the `GEMINI_API_KEY` or `GOOGLE_API_KEY` environment variable. + +## Configuration + +Configure Gemini behavior in `~/.gemini/settings.json`: + +```json +{ + "disable_sandbox_tool": true, + "trusted_folders": ["/workspace"] +} +``` + +These settings disable safety checks and allow Gemini to operate without +repeated confirmations for workspace files. + +### Pass options at runtime + +Pass Gemini CLI options after the sandbox name and a `--` separator: + +```console +$ docker sandbox run -- --yolo +``` + +The `--yolo` flag disables approval prompts for a single session without +modifying the configuration file. + +## Base image + +Template: `docker/sandbox-templates:gemini` + +Gemini is configured to disable its built-in OAuth flow. Authentication is managed through the Docker Sandbox proxy with API keys. + +See [Custom templates](../templates.md) to build your own agent images. + +## Development status + +Gemini is in active development. Known considerations: + +- Features may change between Docker Desktop versions +- Proxy authentication is a workaround for CLI limitations +- Configuration format may evolve +- Some advanced features may be incomplete + +Report issues and provide feedback through the Docker Sandboxes feedback +channels. diff --git a/content/manuals/ai/sandboxes/agents/kiro.md b/content/manuals/ai/sandboxes/agents/kiro.md new file mode 100644 index 000000000000..3adc5807c845 --- /dev/null +++ b/content/manuals/ai/sandboxes/agents/kiro.md @@ -0,0 +1,107 @@ +--- +title: Kiro sandbox +description: | + Use Kiro in Docker Sandboxes with device flow authentication for interactive + AI-assisted development. +keywords: docker, sandboxes, kiro, ai agent, authentication, device flow +weight: 70 +--- + +{{< summary-bar feature_name="Docker Sandboxes" >}} + +This guide covers authentication, configuration, and usage of Kiro in a +sandboxed environment. + +Official documentation: [Kiro CLI](https://kiro.dev/docs/cli/) + +## Quick start + +Create a sandbox and run Kiro for a project directory: + +```console +$ docker sandbox run kiro ~/my-project +``` + +The workspace parameter is optional and defaults to the current directory: + +```console +$ cd ~/my-project +$ docker sandbox run kiro +``` + +On first run, Kiro prompts you to authenticate using device flow. + +## Authentication + +Kiro uses device flow authentication, which requires interactive login through +a web browser. This method provides secure authentication without storing API +keys directly. + +### Device flow login + +When you first run Kiro, it prompts you to authenticate: + +1. Kiro displays a URL and a verification code +2. Open the URL in your web browser +3. Enter the verification code +4. Complete the authentication flow in your browser +5. Return to the terminal - Kiro proceeds automatically + +The authentication session is persisted in the sandbox and doesn't require +repeated login unless you destroy and recreate the sandbox. + +### Manual login + +You can trigger the login flow manually: + +```console +$ docker sandbox run -- login --use-device-flow +``` + +This command initiates device flow authentication without starting a coding +session. + +### Authentication persistence + +Kiro stores authentication state in `~/.local/share/kiro-cli/data.sqlite3` +inside the sandbox. This database persists as long as the sandbox exists. If +you destroy the sandbox, you'll need to authenticate again when you recreate +it. + +## Configuration + +Kiro requires minimal configuration. The agent runs with trust-all-tools mode +by default, which allows it to execute commands without repeated approval +prompts. + +### Pass options at runtime + +Pass Kiro CLI options after the sandbox name and a `--` separator: + +```console +$ docker sandbox run -- chat --trust-all-tools +``` + +The `chat --trust-all-tools` command starts Kiro with approval prompts +disabled. + +## Base image + +Template: `docker/sandbox-templates:kiro` + +Kiro manages authentication through an interactive device flow. The authentication database is persisted across sandbox restarts. Launches with `chat --trust-all-tools` by default. + +See [Custom templates](../templates.md) to build your own agent images. + +## Development status + +Kiro is in active development. Known considerations: + +- Features may change between Docker Desktop versions +- Device flow authentication requires web browser access +- Configuration format may evolve +- Some advanced features may be incomplete +- Authentication persistence tied to sandbox lifecycle + +Report issues and provide feedback through the Docker Sandboxes feedback +channels. diff --git a/content/manuals/ai/sandboxes/agents/opencode.md b/content/manuals/ai/sandboxes/agents/opencode.md new file mode 100644 index 000000000000..ac10c1ca3116 --- /dev/null +++ b/content/manuals/ai/sandboxes/agents/opencode.md @@ -0,0 +1,116 @@ +--- +title: OpenCode sandbox +description: | + Use OpenCode in Docker Sandboxes with multi-provider authentication and TUI + interface for AI development. +keywords: docker, sandboxes, opencode, ai agent, multi-provider, authentication, tui +weight: 50 +--- + +{{< summary-bar feature_name="Docker Sandboxes" >}} + +This guide covers authentication, configuration, and usage of OpenCode in a +sandboxed environment. + +Official documentation: [OpenCode](https://opencode.ai/docs) + +## Quick start + +Create a sandbox and run OpenCode for a project directory: + +```console +$ docker sandbox run opencode ~/my-project +``` + +The workspace parameter is optional and defaults to the current directory: + +```console +$ cd ~/my-project +$ docker sandbox run opencode +``` + +OpenCode launches a TUI (text user interface) where you can select your +preferred LLM provider and interact with the agent. + +## Authentication + +OpenCode 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 on the host, 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 GROQ_API_KEY=gsk_xxxxx +export AWS_ACCESS_KEY_ID=AKIA_xxxxx +export AWS_SECRET_ACCESS_KEY=xxxxx +export AWS_REGION=us-west-2 +``` + +You only need to configure the providers you want to use. OpenCode detects +available credentials and offers those providers in the TUI. + +### 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 opencode ~/project +$ docker sandbox run +``` + +The sandbox detects the environment variables and uses them automatically. + +## Configuration + +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. + +### TUI mode + +OpenCode launches in TUI mode by default. The interface shows: + +- Available LLM providers (based on configured credentials) +- Current conversation history +- File operations and tool usage +- Real-time agent responses + +Use keyboard shortcuts to navigate the interface and interact with the agent. + +## Base image + +Template: `docker/sandbox-templates:opencode` + +OpenCode supports multiple LLM providers with automatic credential injection +through the sandbox proxy. + +See [Custom templates](../templates.md) to build your own agent images. + +## Development status + +OpenCode is in active development. Known considerations: + +- Features may change between Docker Desktop versions +- Multi-provider support is experimental +- Configuration format may evolve +- Some advanced features may be incomplete +- TUI interface requires terminal compatibility + +Report issues and provide feedback through the Docker Sandboxes feedback +channels. diff --git a/content/manuals/ai/sandboxes/agents/shell.md b/content/manuals/ai/sandboxes/agents/shell.md new file mode 100644 index 000000000000..38419a8622a2 --- /dev/null +++ b/content/manuals/ai/sandboxes/agents/shell.md @@ -0,0 +1,126 @@ +--- +title: Custom shell +description: | + Use the custom shell sandbox for manual agent installation and custom + development environments in Docker Sandboxes. +keywords: docker, sandboxes, shell, custom, manual setup, development environment +weight: 80 +--- + +{{< summary-bar feature_name="Docker Sandboxes" >}} + +This guide covers the Shell sandbox, a minimal environment for custom agent +installation and development. Unlike other agent sandboxes, Shell doesn't +include a pre-installed agent binary. Instead, it provides a clean environment +where you can install and configure any agent or tool. + +## Quick start + +Create a sandbox and launch a shell environment: + +```console +$ docker sandbox run shell ~/my-project +``` + +The workspace parameter is optional and defaults to the current directory: + +```console +$ cd ~/my-project +$ docker sandbox run shell +``` + +This launches a bash login shell inside the sandbox. + +## Use cases + +The Shell sandbox serves several purposes: + +- Custom agent installation + + Install agents not officially supported by Docker Sandboxes. The environment + includes package managers and development tools for installing arbitrary + software. + +- Agent development + + Test custom agent implementations or modifications in an isolated environment + with a private Docker daemon. + +- Manual configuration + + Configure agents with complex setup requirements or custom authentication + flows that aren't supported by the standard templates. + +- Troubleshooting + + Debug agent issues by manually running commands and inspecting the sandbox + environment. + +## Authentication + +The Shell sandbox uses proxy credential injection. The proxy automatically +injects credentials into API requests for supported providers (OpenAI, +Anthropic, Google, GitHub, etc.). + +Set your API keys in your shell configuration file: + +```plaintext {title="~/.bashrc or ~/.zshrc"} +export OPENAI_API_KEY=sk-xxxxx +export ANTHROPIC_API_KEY=sk-ant-xxxxx +export GOOGLE_API_KEY=AIzaSyxxxxx +export GH_TOKEN=ghp_xxxxx +``` + +Apply the changes: + +1. Source your shell configuration: `source ~/.bashrc` (or `~/.zshrc`) +2. Restart Docker Desktop so the daemon picks up the environment variables +3. Create and run your sandbox: + +```console +$ docker sandbox create shell ~/project +$ docker sandbox run +``` + +The proxy reads credentials from your host environment and injects them into +API requests automatically. Credentials are never stored inside the sandbox. + +## Installing agents + +Once inside the shell sandbox, install agents using their standard installation +methods. + +### Example: Installing Continue + +[Continue](https://continue.dev) is an AI code assistant. Since Node.js is +pre-installed, you can install it directly: + +```console +$ npm install -g @continuedev/cli +$ cn --version +1.5.43 +``` + +For containerized agents or complex setups, consider creating a [custom +template](../templates.md) based on the shell template instead of installing +interactively. + +## Running commands + +Pass shell options after the `--` separator to execute commands: + +```console +$ docker sandbox run -- -c "echo 'Hello from sandbox'" +``` + +## Base image + +Template: `docker/sandbox-templates:shell` + +The shell template provides the base environment without a pre-installed agent, +making it suitable for manual agent installation. + +See [Custom templates](../templates.md) to build your own agent images. + +The minimal nature of this template makes it suitable as a base for any custom +agent installation. diff --git a/content/manuals/ai/sandboxes/architecture.md b/content/manuals/ai/sandboxes/architecture.md index a6453edc29f7..12816511ae72 100644 --- a/content/manuals/ai/sandboxes/architecture.md +++ b/content/manuals/ai/sandboxes/architecture.md @@ -153,6 +153,29 @@ An HTTP/HTTPS filtering proxy runs on your host and is available at web requests. You can configure network policies to control which destinations are allowed. See [Network policies](network-policies.md). +### Credential injection + +The HTTP/HTTPS proxy automatically injects credentials into API requests for +supported providers (OpenAI, Anthropic, Google, GitHub, etc.). When you set +environment variables like `OPENAI_API_KEY` or `ANTHROPIC_API_KEY` on your +host, the proxy intercepts outbound requests to those services and adds the +appropriate authentication headers. + +This approach keeps credentials on your host system - they're never stored +inside the sandbox VM. The agent makes API requests without credentials, and +the proxy injects them transparently. When the sandbox is removed, no +credentials remain inside. + +For multi-provider agents (OpenCode, cagent), the proxy automatically selects +the correct credentials based on the API endpoint being called. See individual +[agent configuration](agents/) for credential setup instructions. + +When building custom templates or installing agents manually in the shell +sandbox, some agents may require environment variables like `OPENAI_API_KEY` +to be set before they start. Set these to placeholder values (e.g., +`proxy-managed`) if needed - the proxy will inject actual credentials +regardless of the environment variable value. + ### Sandbox isolation Sandboxes cannot communicate with each other. Each VM has its own private @@ -200,9 +223,3 @@ Sandboxes trade higher resource overhead (VM + daemon) for complete isolation. Use containers when you need lightweight packaging without Docker access. Use sandboxes when you need to give something autonomous full Docker capabilities without trusting it with your host environment. - -## Next steps - -- [Network policies](network-policies.md) -- [Custom templates](templates.md) -- [Using sandboxes effectively](workflows.md) diff --git a/content/manuals/ai/sandboxes/get-started.md b/content/manuals/ai/sandboxes/get-started.md index 89c499bc4653..bd6f17b86e33 100644 --- a/content/manuals/ai/sandboxes/get-started.md +++ b/content/manuals/ai/sandboxes/get-started.md @@ -1,13 +1,15 @@ --- title: Get started with Docker Sandboxes linkTitle: Get started -description: Run Claude Code in an isolated sandbox. Quick setup guide with prerequisites and essential commands. +description: Run AI coding agents in isolated sandboxes. Quick setup guide using Claude Code as an example. weight: 20 --- {{< summary-bar feature_name="Docker Sandboxes" >}} -This guide shows how to run Claude Code in an isolated sandbox for the first time. +This guide shows how to run an AI coding agent in an isolated sandbox for the +first time, using Claude Code as an example. The same concepts apply to +[other supported agents](agents/). > [!NOTE] > Upgrading from an earlier version of Docker Desktop? See the @@ -19,12 +21,12 @@ This guide shows how to run Claude Code in an isolated sandbox for the first tim Before you begin, ensure you have: - Docker Desktop 4.58 or later -- macOS, or Windows {{< badge color=violet text=Experimental >}} +- macOS or Windows {{< badge color=violet text=Experimental >}} - A Claude API key (can be provided via environment variable or interactively) ## Run your first sandbox -Follow these steps to run Claude Code: +Follow these steps to run a sandbox with Claude Code: 1. (Optional but recommended) Set your Anthropic API key as an environment variable. @@ -51,10 +53,26 @@ Follow these steps to run Claude Code: 2. Create and run a sandbox for Claude Code for your workspace: ```console - $ docker sandbox run claude ~/my-project + $ docker sandbox run claude [PATH] ``` - This creates a microVM sandbox. Docker assigns it a name automatically. + This creates a microVM sandbox. Docker assigns it a name automatically based + on the agent and workspace directory (`claude-somedir`). If that name is + already in use, Docker appends a number. + + The workspace parameter is optional and defaults to your current directory + if omitted: + + ```console + $ cd ~/my-project + $ docker sandbox run claude + ``` + + You can also mount multiple workspaces. Append `:ro` for read-only access: + + ```console + $ docker sandbox run claude ~/my-project ~/docs:ro + ``` 3. Claude Code starts and you can begin working. The first run takes longer while Docker initializes the microVM and pulls the template image. @@ -86,7 +104,8 @@ Here are essential commands to manage your sandboxes: $ docker sandbox ls ``` -Shows all your sandboxes with their IDs, names, status, and creation time. +Shows all your sandboxes with their IDs, names, status, workspace paths, and +creation time. Workspace paths are shown for both running and stopped sandboxes. > [!NOTE] > Sandboxes don't appear in `docker ps` because they're microVMs, not @@ -120,7 +139,7 @@ To start fresh with a clean environment, remove and recreate the sandbox: ```console $ docker sandbox rm -$ docker sandbox run claude ~/project +$ docker sandbox run claude [PATH] ``` Configuration like custom templates and workspace paths are set when you create @@ -131,10 +150,9 @@ For a complete list of commands and options, see the ## Next steps -Now that you have Claude running in a sandbox, learn more about: +Now that you have an agent running in a sandbox, learn more about: -- [Claude Code configuration](claude-code.md) -- [Supported agents](agents.md) +- [Supported agents](agents/_index.md) - [Using sandboxes effectively](workflows.md) - [Custom templates](templates.md) - [Network policies](network-policies.md) diff --git a/content/manuals/ai/sandboxes/migration.md b/content/manuals/ai/sandboxes/migration.md index d46937f04fe3..68d4ceea3c1e 100644 --- a/content/manuals/ai/sandboxes/migration.md +++ b/content/manuals/ai/sandboxes/migration.md @@ -6,9 +6,9 @@ weight: 100 {{< summary-bar feature_name="Docker Sandboxes" >}} -Docker Desktop 4.58 introduces microVM-based sandboxes, replacing the previous -container-based implementation. This guide helps you migrate from legacy -sandboxes to the new architecture. +The most recent versions of Docker Desktop creates microVM-based sandboxes, +replacing the container-based implementation released in earlier versions. This +guide helps you migrate from legacy sandboxes to the new architecture. ## What changed @@ -20,7 +20,7 @@ policies. > If you need to use legacy container-based sandboxes, install > [Docker Desktop 4.57](/desktop/release-notes/#4570). -After upgrading to Docker Desktop 4.58: +After upgrading to Docker Desktop 4.58 or later: - Old sandboxes don't appear in `docker sandbox ls` - They still exist as regular Docker containers and volumes @@ -121,10 +121,15 @@ template. ```console $ docker sandbox create --template my-sandbox-template:v1 \ - --load-local-template \ + --pull-template=never \ 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`. + 5. Run the sandbox: ```console @@ -189,5 +194,5 @@ New command structure: $ docker sandbox run claude ~/project ``` -The agent name (`claude`, `codex`, `gemini`, `cagent`, `kiro`) is now a -required parameter when creating sandboxes, and you run the sandbox by name. +The agent name is now a required parameter when creating sandboxes, and you run +the sandbox by name. diff --git a/content/manuals/ai/sandboxes/network-policies.md b/content/manuals/ai/sandboxes/network-policies.md index bc7aae314beb..5424aba0f63a 100644 --- a/content/manuals/ai/sandboxes/network-policies.md +++ b/content/manuals/ai/sandboxes/network-policies.md @@ -61,6 +61,32 @@ the allow-list (e.g., `localhost:1234`). HTTP requests to `host.docker.internal` are rewritten to `localhost`, so only the name `localhost` will work in the allow-list. +## Default policy + +New sandboxes use this default policy unless you configure a custom policy: + +**Policy mode:** `allow` (permit all traffic except what's explicitly blocked) + +**Blocked CIDRs:** + +- `10.0.0.0/8` - Private network (Class A) +- `127.0.0.0/8` - Loopback addresses +- `169.254.0.0/16` - Link-local addresses +- `172.16.0.0/12` - Private network (Class B) +- `192.168.0.0/16` - Private network (Class C) +- `::1/128` - IPv6 loopback +- `fc00::/7` - IPv6 unique local addresses +- `fe80::/10` - IPv6 link-local addresses + +**Allowed hosts:** + +- `*.anthropic.com` - Claude API and services +- `platform.claude.com:443` - Claude platform services + +The default policy blocks access to private networks, localhost, and cloud +metadata services while allowing internet access. Explicitly allowed hosts +bypass CIDR checks for performance. + ## Monitor network activity View what your agent is accessing and whether requests are being blocked: @@ -69,7 +95,43 @@ View what your agent is accessing and whether requests are being blocked: $ docker sandbox network log ``` -Network logs help you understand agent behavior and define policies. +The network log shows aggregated summaries of HTTP/HTTPS network requests: + +- **Allowed requests** - Requests that were permitted by your network policy +- **Blocked requests** - Requests that were denied by your network policy + +For each host accessed, the log shows: + +- **Sandbox** - Name of the sandbox making the request +- **Host** - The destination (hostname and port) +- **Rule** - The policy rule that matched this request (or ``) +- **Last Seen** - When this host was most recently accessed +- **Count** - Number of requests to this host since tracking began + +Use network logs to understand agent behavior, identify blocked requests that +should be allowed, and debug network policy issues. The logs are especially +helpful when defining policies - they show exactly what your agent is trying to +access. + +### Example log output + +```console +$ docker sandbox network log +Blocked requests: +SANDBOX HOST RULE LAST SEEN COUNT +my-sandbox internal.corp.com:443 14:30:15 12-Feb 3 +my-sandbox 192.168.1.100:22 14:25:10 12-Feb 1 + +Allowed requests: +SANDBOX HOST RULE LAST SEEN COUNT +my-sandbox api.anthropic.com:443 api.anthropic.com 14:35:21 12-Feb 15 +my-sandbox registry.npmjs.org:443 *.npmjs.org 14:32:18 12-Feb 8 +my-sandbox raw.githubusercontent.com:443 *.githubusercontent.com 14:30:45 12-Feb 2 +``` + +The log displays both blocked and allowed requests in separate sections. Use +`--json` for machine-readable output, `--quiet` to suppress headers, or +`--limit N` to show only the first N entries. ## Applying policies @@ -100,16 +162,8 @@ This policy: > [!NOTE] > These CIDR blocks are already blocked by default. The example above shows how -> to explicitly configure them if needed. The default policy blocks: -> -> - `10.0.0.0/8` -> - `127.0.0.0/8` -> - `169.254.0.0/16` -> - `172.16.0.0/12` -> - `192.168.0.0/16` -> - `::1/128` -> - `fc00::/7` -> - `fe80::/10` +> to explicitly configure them. See [Default policy](#default-policy) for the +> complete list. ### Example: Restrict to package managers only @@ -317,8 +371,7 @@ first sandbox starts, but only if it doesn't already exist. The current default policy is `allow`, which permits all outbound connections except to blocked CIDR ranges (private networks, localhost, and cloud metadata -services). This default will change to `deny` in a future release to provide -more restrictive defaults. +services). You can modify the default policy: @@ -332,9 +385,3 @@ You can modify the default policy: Review and customize the default policy to match your security requirements before creating new sandboxes. Once created, the default policy file won't be modified by upgrades, preserving your custom configuration. - -## Next steps - -- [Architecture](architecture.md) -- [Using sandboxes effectively](workflows.md) -- [Custom templates](templates.md) diff --git a/content/manuals/ai/sandboxes/templates.md b/content/manuals/ai/sandboxes/templates.md index 60cc476c5a31..79ac29cc179b 100644 --- a/content/manuals/ai/sandboxes/templates.md +++ b/content/manuals/ai/sandboxes/templates.md @@ -68,21 +68,47 @@ $ docker build -t my-template:v1 . Use it directly from your local Docker daemon: ```console -$ docker sandbox run --load-local-template -t my-template:v1 claude ~/project +$ docker sandbox run --pull-template never -t my-template:v1 claude [PATH] ``` -The `--load-local-template` flag tells the sandbox to use an image from your -local Docker daemon. Without it, the sandbox looks for the image in a registry. +The `--pull-template never` flag tells the sandbox to use local template +images. To share the template with others, push it to a registry: ```console $ docker tag my-template:v1 myorg/my-template:v1 $ docker push myorg/my-template:v1 -$ docker sandbox run -t myorg/my-template:v1 claude ~/project +$ docker sandbox run -t myorg/my-template:v1 claude [PATH] ``` -Once pushed to a registry, you don't need `--load-local-template`. +For registry images, the default `--pull-template missing` policy automatically +pulls if not cached. + +## Template caching and pull policies + +Docker Sandboxes caches template images to speed up sandbox creation. The +`--pull-template` flag controls when images are pulled from registries. + +- `--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. + +- `--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. + +- `--pull-template never` + + Use only cached images. Never pull from a registry. Fails if the image isn't + in the cache. + +The cache stores template images separately from your host Docker daemon's +images. Cached images persist across sandbox creation and deletion, but are +removed when you run `docker sandbox reset`. ## Creating templates from existing sandboxes @@ -100,21 +126,21 @@ Inside the sandbox, ask the agent to install tools and configure the environment. Once everything works, exit and save the sandbox as a template: ```console -$ docker sandbox save claude-sandbox-2026-02-02-123456 my-template:v1 +$ docker sandbox save claude-project my-template:v1 ✓ Saved sandbox as my-template:v1 ``` -This saves the image to your local Docker daemon. Use `--load-local-template` +This saves the image to your local Docker daemon. Use `--pull-template never` to create new sandboxes from it: ```console -$ docker sandbox run --load-local-template -t my-template:v1 claude ~/other-project +$ docker sandbox run --pull-template never -t my-template:v1 claude ~/other-project ``` To save as a tar file instead (for example, to transfer to another machine): ```console -$ docker sandbox save -o template.tar claude-sandbox-2026-02-02-123456 my-template:v1 +$ docker sandbox save -o template.tar claude-project my-template:v1 ``` Use a Dockerfile when you want a clear record of how the environment is built. @@ -157,8 +183,8 @@ base, but they don't include agent binaries or sandbox configuration. Using a standard image directly creates the sandbox but fails at runtime: ```console -$ docker sandbox create --template python:3-slim claude ~/project -✓ Created sandbox claude-sandbox-2026-01-16-170525 in VM claude-project +$ docker sandbox create --template python:3-slim claude [PATH] +✓ Created sandbox claude-project $ docker sandbox run claude-project agent binary "claude" not found in sandbox: verify this is the correct sandbox type @@ -187,14 +213,8 @@ $ docker push myorg/my-template:v1.0 Team members use the template by referencing the registry image: ```console -$ docker sandbox run -t myorg/sandbox-templates:python-v1.0 claude ~/project +$ docker sandbox run -t myorg/sandbox-templates:python-v1.0 claude [PATH] ``` Use version tags like `:v1.0` instead of `:latest` for consistency across your team. - -## Next steps - -- [Using sandboxes effectively](workflows.md) -- [Architecture](architecture.md) -- [Network policies](network-policies.md) diff --git a/content/manuals/ai/sandboxes/troubleshooting.md b/content/manuals/ai/sandboxes/troubleshooting.md index 319657874138..686f2d02e3fc 100644 --- a/content/manuals/ai/sandboxes/troubleshooting.md +++ b/content/manuals/ai/sandboxes/troubleshooting.md @@ -6,7 +6,7 @@ weight: 50 {{< summary-bar feature_name="Docker Sandboxes" >}} -This guide helps you resolve common issues when sandboxing Claude Code locally. +This guide helps you resolve common issues when using Docker Sandboxes with AI coding agents. @@ -119,3 +119,17 @@ If this happens, recover by closing the OpenVMM processes: To avoid this issue, launch sandboxes one at a time rather than creating multiple sandboxes concurrently. + +## Persistent issues or corrupted state + +If sandboxes behave unexpectedly or fail to start, reset all sandbox state: + +```console +$ docker sandbox reset +``` + +This stops all running VMs and deletes all sandbox data. The daemon continues +running. After reset, create fresh sandboxes as needed. + +Use reset when troubleshooting persistent problems or to reclaim disk space from +all sandboxes at once. diff --git a/content/manuals/ai/sandboxes/workflows.md b/content/manuals/ai/sandboxes/workflows.md index 63888784aad4..c4a27d440d7b 100644 --- a/content/manuals/ai/sandboxes/workflows.md +++ b/content/manuals/ai/sandboxes/workflows.md @@ -15,14 +15,37 @@ Create a sandbox for your project: ```console $ cd ~/my-project -$ docker sandbox run claude . +$ docker sandbox run AGENT ``` -The sandbox persists. Stop and restart it without losing installed packages or +Replace `AGENT` with your chosen agent (`claude`, `codex`, `copilot`, etc.). The workspace defaults to your current directory when omitted. You can also specify an explicit path: + +```console +$ docker sandbox run AGENT ~/my-project +``` + +The `docker sandbox run` command is idempotent. Running the same command +multiple times reuses the existing sandbox instead of creating a new one: + +```console +$ docker sandbox run AGENT ~/my-project # Creates sandbox +$ docker sandbox run AGENT ~/my-project # Reuses same sandbox +``` + +This works with workspace path (absolute or relative) or omitted workspace. The +sandbox persists. Stop and restart it without losing installed packages or configuration: ```console -$ docker sandbox run # Reconnect later +$ docker sandbox run # Reconnect by name +``` + +When using the `--name` flag, the behavior is also idempotent based on the +name: + +```console +$ docker sandbox run --name dev AGENT # Creates sandbox named "dev" +$ docker sandbox run --name dev AGENT # Reuses sandbox "dev" ``` ## Installing dependencies @@ -31,10 +54,10 @@ Ask the agent to install what's needed: ```plaintext You: "Install pytest and black" -Claude: [Installs packages via pip] +Agent: [Installs packages via pip] You: "Install build-essential" -Claude: [Installs via apt] +Agent: [Installs via apt] ``` The agent has sudo access. Installed packages persist for the sandbox lifetime. @@ -53,7 +76,7 @@ runs inside the sandbox's private Docker daemon. ```plaintext You: "Build the Docker image and run the tests" -Claude: *runs* +Agent: *runs* docker build -t myapp:test . docker run myapp:test npm test ``` @@ -66,7 +89,7 @@ don't appear in your host's `docker ps`. ```plaintext You: "Start the application with docker-compose and run integration tests" -Claude: *runs* +Agent: *runs* docker-compose up -d docker-compose exec api pytest tests/integration docker-compose down @@ -92,6 +115,9 @@ To preserve a configured environment, create a [Custom template](templates.md). ## Security considerations +Agents running in sandboxes automatically trust the workspace directory without +prompting. This enables agents to work freely within the isolated environment. + Agents can create and modify any files in your mounted workspace, including scripts, configuration files, and hidden files. @@ -115,68 +141,144 @@ Check for untracked files and be aware that some changes, like Git hooks in This is the same trust model used by editors like Visual Studio Code, which warn when opening new workspaces for similar reasons. +## Managing multiple projects + +Create sandboxes for different projects: + +```console +$ docker sandbox create claude ~/project-a +$ docker sandbox create codex ~/project-b +$ docker sandbox create copilot ~/work/client-project +``` + +Each sandbox is completely isolated. Switch between them by running the +appropriate sandbox name. + +Remove unused sandboxes to reclaim disk space: + +```console +$ docker sandbox rm +``` + ## Named sandboxes -Use meaningful names for sandboxes you'll reuse: +Docker automatically generates sandbox names based on the agent and workspace +directory (for example, `claude-my-project`). You can also specify custom names +using the `--name` flag: ```console -$ docker sandbox run --name myproject claude ~/project +$ docker sandbox run --name myproject AGENT ~/project ``` Create multiple sandboxes for the same workspace: ```console $ docker sandbox create --name dev claude ~/project -$ docker sandbox create --name staging claude ~/project +$ docker sandbox create --name staging codex ~/project $ docker sandbox run dev ``` Each maintains separate packages, Docker images, and state, but share the workspace files. -## Debugging +## Multiple workspaces -Access the sandbox directly with an interactive shell: +Mount multiple directories into a single sandbox for working with related +projects or when the agent needs access to documentation and shared libraries. ```console -$ docker sandbox exec -it bash +$ docker sandbox run AGENT ~/my-project ~/shared-docs ``` -Inside the shell, you can inspect the environment, manually install packages, -or check Docker containers: +The primary workspace (first argument) is always mounted read-write. Additional +workspaces are mounted read-write by default. + +### Read-only mounts + +Mount additional workspaces as read-only by appending `:ro` or `:readonly`: ```console -agent@sandbox:~$ docker ps -agent@sandbox:~$ docker images +$ docker sandbox run AGENT . /path/to/docs:ro /path/to/lib:readonly ``` -List all sandboxes: +The primary workspace remains fully writable while read-only workspaces are +protected from changes. + +### Path resolution + +Workspaces are mounted at their absolute paths inside the sandbox. Relative +paths are resolved to absolute paths before mounting. + +Example: ```console +$ cd /Users/bob/projects +$ docker sandbox run AGENT ./app ~/docs:ro +``` + +Inside the sandbox: + +- `/Users/bob/projects/app` - Primary workspace (read-write) +- `/Users/bob/docs` - Additional workspace (read-only) + +Changes to `/Users/bob/projects/app` sync back to your host, while +`/Users/bob/docs` remains read-only. + +### Sharing workspaces across sandboxes + +A single path can be included in multiple sandboxes simultaneously: + +```console +$ docker sandbox create --name sb1 claude ./project-a +$ docker sandbox create --name sb2 claude ./project-a ./project-b +$ docker sandbox create --name sb3 cagent ./project-a $ docker sandbox ls +SANDBOX AGENT STATUS WORKSPACE +sb1 claude running /Users/bob/src/project-a +sb2 claude running /Users/bob/src/project-a, /Users/bob/src/project-b +sb3 cagent running /Users/bob/src/project-a ``` -## Managing multiple projects +Each sandbox runs in isolation with separate configurations while sharing the +same workspace files. -Create sandboxes for different projects: +## Resetting state + +If you encounter issues with sandbox state, use the reset command to clean up +all VMs and registries: ```console -$ docker sandbox create claude ~/project-a -$ docker sandbox create claude ~/project-b -$ docker sandbox create claude ~/work/client-project +$ docker sandbox reset ``` -Each sandbox is completely isolated. Switch between them by running the -appropriate sandbox name. +This command: -Remove unused sandboxes to reclaim disk space: +- Stops all running sandbox VMs +- Deletes all VM state and registries +- Continues running the sandbox daemon (does not shut it down) +- Warns about directories it cannot remove + +After reset, you can create fresh sandboxes. Use this when troubleshooting +persistent issues or reclaiming disk space from all sandboxes at once. + +## Debugging + +Access the sandbox directly with an interactive shell: ```console -$ docker sandbox rm +$ docker sandbox exec -it bash ``` -## Next steps +Inside the shell, you can inspect the environment, manually install packages, +or check Docker containers: -- [Custom templates](templates.md) -- [Architecture](architecture.md) -- [Network policies](network-policies.md) +```console +agent@sandbox:~$ docker ps +agent@sandbox:~$ docker images +``` + +List all sandboxes: + +```console +$ docker sandbox ls +``` diff --git a/content/reference/cli/docker/sandbox/create/opencode.md b/content/reference/cli/docker/sandbox/create/opencode.md new file mode 100644 index 000000000000..8304378227fd --- /dev/null +++ b/content/reference/cli/docker/sandbox/create/opencode.md @@ -0,0 +1,6 @@ +--- +datafolder: sandbox-cli +datafile: docker_sandbox_create_opencode +title: docker sandbox create opencode +layout: cli +--- diff --git a/content/reference/cli/docker/sandbox/create/shell.md b/content/reference/cli/docker/sandbox/create/shell.md new file mode 100644 index 000000000000..72ea45746f91 --- /dev/null +++ b/content/reference/cli/docker/sandbox/create/shell.md @@ -0,0 +1,6 @@ +--- +datafolder: sandbox-cli +datafile: docker_sandbox_create_shell +title: docker sandbox create shell +layout: cli +--- diff --git a/data/sandbox-cli/docker_sandbox_create.yaml b/data/sandbox-cli/docker_sandbox_create.yaml index c5722369f093..20ad68bb39ad 100644 --- a/data/sandbox-cli/docker_sandbox_create.yaml +++ b/data/sandbox-cli/docker_sandbox_create.yaml @@ -14,6 +14,8 @@ cname: - docker sandbox create copilot - docker sandbox create gemini - docker sandbox create kiro + - docker sandbox create opencode + - docker sandbox create shell clink: - docker_sandbox_create_cagent.yaml - docker_sandbox_create_claude.yaml @@ -21,23 +23,24 @@ clink: - docker_sandbox_create_copilot.yaml - docker_sandbox_create_gemini.yaml - docker_sandbox_create_kiro.yaml + - docker_sandbox_create_opencode.yaml + - docker_sandbox_create_shell.yaml options: - - option: load-local-template - value_type: bool - default_value: "false" + - option: name + value_type: string description: | - Load a locally built template image into the sandbox (useful for testing local changes) - details_url: '#load-local-template' + Name for the sandbox (default: -, letters, numbers, hyphens, underscores, periods, plus signs and minus signs only) deprecated: false hidden: false experimental: false experimentalcli: false kubernetes: false swarm: false - - option: name + - option: pull-template value_type: string + default_value: missing description: | - Name for the sandbox (default: -, letters, numbers, hyphens, and underscores) + Template image pull policy: always (always pull from registry), missing (pull only if not cached), never (use only cached images) deprecated: false hidden: false experimental: false @@ -116,16 +119,6 @@ examples: |- By default, each agent uses a pre-configured image. - ### Use locally built template (--load-local-template) {#load-local-template} - - Load a locally built template image for testing: - - ```console - $ docker sandbox create --load-local-template claude ~/my-project - ``` - - This is useful when developing or testing changes to sandbox templates. - ### Create and run immediately After creating a sandbox, use `run` to start the agent: diff --git a/data/sandbox-cli/docker_sandbox_create_cagent.yaml b/data/sandbox-cli/docker_sandbox_create_cagent.yaml index 146f1c3abb44..028fe3f32e6e 100644 --- a/data/sandbox-cli/docker_sandbox_create_cagent.yaml +++ b/data/sandbox-cli/docker_sandbox_create_cagent.yaml @@ -4,9 +4,10 @@ long: |- Create a sandbox with access to a host workspace for cagent. The workspace path is required and will be exposed inside the sandbox at the same path as on the host. + Additional workspaces can be provided as extra arguments. Append ":ro" to mount them read-only. Use 'docker sandbox run SANDBOX' to start cagent after creation. -usage: docker sandbox create cagent WORKSPACE +usage: docker sandbox create cagent WORKSPACE [EXTRA_WORKSPACE...] pname: docker sandbox create plink: docker_sandbox_create.yaml inherited_options: diff --git a/data/sandbox-cli/docker_sandbox_create_claude.yaml b/data/sandbox-cli/docker_sandbox_create_claude.yaml index feefd7d80dc9..f06eb2f1202e 100644 --- a/data/sandbox-cli/docker_sandbox_create_claude.yaml +++ b/data/sandbox-cli/docker_sandbox_create_claude.yaml @@ -4,9 +4,10 @@ long: |- Create a sandbox with access to a host workspace for claude. The workspace path is required and will be exposed inside the sandbox at the same path as on the host. + Additional workspaces can be provided as extra arguments. Append ":ro" to mount them read-only. Use 'docker sandbox run SANDBOX' to start claude after creation. -usage: docker sandbox create claude WORKSPACE +usage: docker sandbox create claude WORKSPACE [EXTRA_WORKSPACE...] pname: docker sandbox create plink: docker_sandbox_create.yaml options: diff --git a/data/sandbox-cli/docker_sandbox_create_codex.yaml b/data/sandbox-cli/docker_sandbox_create_codex.yaml index df70fb07dcb8..14d1129deb5a 100644 --- a/data/sandbox-cli/docker_sandbox_create_codex.yaml +++ b/data/sandbox-cli/docker_sandbox_create_codex.yaml @@ -4,9 +4,10 @@ long: |- Create a sandbox with access to a host workspace for codex. The workspace path is required and will be exposed inside the sandbox at the same path as on the host. + Additional workspaces can be provided as extra arguments. Append ":ro" to mount them read-only. Use 'docker sandbox run SANDBOX' to start codex after creation. -usage: docker sandbox create codex WORKSPACE +usage: docker sandbox create codex WORKSPACE [EXTRA_WORKSPACE...] pname: docker sandbox create plink: docker_sandbox_create.yaml inherited_options: diff --git a/data/sandbox-cli/docker_sandbox_create_copilot.yaml b/data/sandbox-cli/docker_sandbox_create_copilot.yaml index da5a0e07b333..1a633fff2637 100644 --- a/data/sandbox-cli/docker_sandbox_create_copilot.yaml +++ b/data/sandbox-cli/docker_sandbox_create_copilot.yaml @@ -4,9 +4,10 @@ long: |- Create a sandbox with access to a host workspace for copilot. The workspace path is required and will be exposed inside the sandbox at the same path as on the host. + Additional workspaces can be provided as extra arguments. Append ":ro" to mount them read-only. Use 'docker sandbox run SANDBOX' to start copilot after creation. -usage: docker sandbox create copilot WORKSPACE +usage: docker sandbox create copilot WORKSPACE [EXTRA_WORKSPACE...] pname: docker sandbox create plink: docker_sandbox_create.yaml inherited_options: diff --git a/data/sandbox-cli/docker_sandbox_create_gemini.yaml b/data/sandbox-cli/docker_sandbox_create_gemini.yaml index 7491928a4820..73444fe73ccb 100644 --- a/data/sandbox-cli/docker_sandbox_create_gemini.yaml +++ b/data/sandbox-cli/docker_sandbox_create_gemini.yaml @@ -4,9 +4,10 @@ long: |- Create a sandbox with access to a host workspace for gemini. The workspace path is required and will be exposed inside the sandbox at the same path as on the host. + Additional workspaces can be provided as extra arguments. Append ":ro" to mount them read-only. Use 'docker sandbox run SANDBOX' to start gemini after creation. -usage: docker sandbox create gemini WORKSPACE +usage: docker sandbox create gemini WORKSPACE [EXTRA_WORKSPACE...] pname: docker sandbox create plink: docker_sandbox_create.yaml inherited_options: diff --git a/data/sandbox-cli/docker_sandbox_create_kiro.yaml b/data/sandbox-cli/docker_sandbox_create_kiro.yaml index 1eac3307e530..b82560234f79 100644 --- a/data/sandbox-cli/docker_sandbox_create_kiro.yaml +++ b/data/sandbox-cli/docker_sandbox_create_kiro.yaml @@ -4,9 +4,10 @@ long: |- Create a sandbox with access to a host workspace for kiro. The workspace path is required and will be exposed inside the sandbox at the same path as on the host. + Additional workspaces can be provided as extra arguments. Append ":ro" to mount them read-only. Use 'docker sandbox run SANDBOX' to start kiro after creation. -usage: docker sandbox create kiro WORKSPACE +usage: docker sandbox create kiro WORKSPACE [EXTRA_WORKSPACE...] pname: docker sandbox create plink: docker_sandbox_create.yaml inherited_options: diff --git a/data/sandbox-cli/docker_sandbox_create_opencode.yaml b/data/sandbox-cli/docker_sandbox_create_opencode.yaml new file mode 100644 index 000000000000..9480dfcff54c --- /dev/null +++ b/data/sandbox-cli/docker_sandbox_create_opencode.yaml @@ -0,0 +1,60 @@ +command: docker sandbox create opencode +short: Create a sandbox for opencode +long: |- + Create a sandbox with access to a host workspace for opencode. + + The workspace path is required and will be exposed inside the sandbox at the same path as on the host. + Additional workspaces can be provided as extra arguments. Append ":ro" to mount them read-only. + + Use 'docker sandbox run SANDBOX' to start opencode after creation. +usage: docker sandbox create opencode WORKSPACE [EXTRA_WORKSPACE...] +pname: docker sandbox create +plink: docker_sandbox_create.yaml +inherited_options: + - option: debug + shorthand: D + value_type: bool + default_value: "false" + description: Enable debug logging + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: socket + value_type: string + description: | + Connect to daemon at specific socket path (for development/debugging) + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +examples: |- + ### Create an OpenCode sandbox in the current directory + + ```console + $ docker sandbox create opencode . + ``` + + ### Create with an absolute path + + ```console + $ docker sandbox create opencode /home/user/my-project + ``` + + ### Create and then run + + ```console + $ docker sandbox create --name my-opencode opencode ~/my-project + $ docker sandbox run my-opencode + ``` +deprecated: false +hidden: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false + diff --git a/data/sandbox-cli/docker_sandbox_create_shell.yaml b/data/sandbox-cli/docker_sandbox_create_shell.yaml new file mode 100644 index 000000000000..71380a5f6b24 --- /dev/null +++ b/data/sandbox-cli/docker_sandbox_create_shell.yaml @@ -0,0 +1,41 @@ +command: docker sandbox create shell +short: Create a sandbox for shell +long: |- + Create a sandbox with access to a host workspace for shell. + + The workspace path is required and will be exposed inside the sandbox at the same path as on the host. + Additional workspaces can be provided as extra arguments. Append ":ro" to mount them read-only. + + Use 'docker sandbox run SANDBOX' to start shell after creation. +usage: docker sandbox create shell WORKSPACE [EXTRA_WORKSPACE...] +pname: docker sandbox create +plink: docker_sandbox_create.yaml +inherited_options: + - option: debug + shorthand: D + value_type: bool + default_value: "false" + description: Enable debug logging + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: socket + value_type: string + description: | + Connect to daemon at specific socket path (for development/debugging) + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +deprecated: false +hidden: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false + diff --git a/data/sandbox-cli/docker_sandbox_ls.yaml b/data/sandbox-cli/docker_sandbox_ls.yaml index e633f9ac24d3..61f9383eefb9 100644 --- a/data/sandbox-cli/docker_sandbox_ls.yaml +++ b/data/sandbox-cli/docker_sandbox_ls.yaml @@ -16,17 +16,6 @@ options: experimentalcli: false kubernetes: false swarm: false - - option: no-trunc - value_type: bool - default_value: "false" - description: Don't truncate output - details_url: '#no-trunc' - deprecated: false - hidden: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false - option: quiet shorthand: q value_type: bool @@ -85,24 +74,6 @@ examples: |- gemini-vm ``` - ### Don't truncate output (--no-trunc) {#no-trunc} - - ```text - --no-trunc - ``` - - By default, long VM IDs, workspace paths, and socket paths are truncated for readability. Use `--no-trunc` to display the full values: - - ```console - $ docker sandbox ls - VM ID NAME STATUS WORKSPACE SOCKET PATH SANDBOXES AGENTS - abc123def claude-vm running /home/user/.../my-project ...sandboxes/vm/claude-vm/docker.sock 2 claude - - $ docker sandbox ls --no-trunc - VM ID NAME STATUS WORKSPACE SOCKET PATH SANDBOXES AGENTS - abc123def456ghi789jkl claude-vm running /home/user/very/long/path/to/my-project /Users/user/.docker/sandboxes/vm/claude-vm/docker-1764682554072.sock 2 claude - ``` - ### JSON output (--json) ```text diff --git a/data/sandbox-cli/docker_sandbox_network_proxy.yaml b/data/sandbox-cli/docker_sandbox_network_proxy.yaml index 8accbb6a7400..34f47ad6e179 100644 --- a/data/sandbox-cli/docker_sandbox_network_proxy.yaml +++ b/data/sandbox-cli/docker_sandbox_network_proxy.yaml @@ -48,7 +48,7 @@ options: - option: bypass-cidr value_type: string description: | - Bypass proxy for an IP range in CIDR notation (can be specified multiple times) + Bypass MITM proxy for an IP range in CIDR notation (can be specified multiple times) details_url: '#bypass-cidr' deprecated: false hidden: false @@ -58,7 +58,8 @@ options: swarm: false - option: bypass-host value_type: string - description: Bypass proxy for a domain or IP (can be specified multiple times) + description: | + Bypass MITM proxy for a domain or IP (can be specified multiple times) details_url: '#bypass-host' deprecated: false hidden: false @@ -139,25 +140,25 @@ examples: |- --allow-host api.trusted-service.com ``` - ### Bypass proxy for domain (--bypass-host) {#bypass-host} + ### Bypass MITM proxy for domain (--bypass-host) {#bypass-host} ```text --bypass-host DOMAIN ``` - Bypass proxy for specific domains: + Bypass MITM proxy for specific domains: ```console $ docker sandbox network proxy my-sandbox --bypass-host localhost ``` - ### Bypass proxy for IP range (--bypass-cidr) {#bypass-cidr} + ### Bypass MITM proxy for IP range (--bypass-cidr) {#bypass-cidr} ```text --bypass-cidr CIDR ``` - Bypass proxy for an IP range: + Bypass MITM proxy for an IP range: ```console $ docker sandbox network proxy my-sandbox --bypass-cidr 127.0.0.0/8 diff --git a/data/sandbox-cli/docker_sandbox_reset.yaml b/data/sandbox-cli/docker_sandbox_reset.yaml index 007204af9504..543950dc8ef6 100644 --- a/data/sandbox-cli/docker_sandbox_reset.yaml +++ b/data/sandbox-cli/docker_sandbox_reset.yaml @@ -6,12 +6,14 @@ long: |- This command will: - Stop all running VMs gracefully (30s timeout) - Delete all VM state directories in ~/.docker/sandboxes/vm/ + - Clear image cache in ~/.docker/sandboxes/image-cache/ - Clear all internal registries The daemon will continue running with fresh state after reset. ⚠️ WARNING: This is a destructive operation that cannot be undone! All running agents will be forcefully terminated and their work will be lost. + Cached image tars will be deleted and will need to be recreated on next use. By default, you will be prompted to confirm (y/N). Use --force to skip the confirmation prompt. diff --git a/data/sandbox-cli/docker_sandbox_run.yaml b/data/sandbox-cli/docker_sandbox_run.yaml index a32d82d8c34e..b800274623a0 100644 --- a/data/sandbox-cli/docker_sandbox_run.yaml +++ b/data/sandbox-cli/docker_sandbox_run.yaml @@ -4,7 +4,24 @@ long: |- Run an agent in a sandbox. Create the sandbox if it does not exist. Pass agent arguments after the "--" separator. -usage: docker sandbox run SANDBOX [-- AGENT_ARGS...] | AGENT WORKSPACE [-- AGENT_ARGS...] + Additional workspaces can be provided as extra arguments. Append ":ro" to mount them read-only. + + Examples: + # Create and run a sandbox with claude in current directory + docker sandbox run claude + + # Create and run a sandbox with claude in current directory (explicit) + docker sandbox run claude . + + # Create and run with additional workspaces (read-only) + docker sandbox run claude . /path/to/docs:ro + + # Run an existing sandbox + docker sandbox run existing-sandbox + + # Run a sandbox with agent arguments + docker sandbox run claude -- --continue +usage: docker sandbox run SANDBOX [-- AGENT_ARGS...] | AGENT [WORKSPACE] [EXTRA_WORKSPACE...] [-- AGENT_ARGS...] pname: docker sandbox plink: docker_sandbox.yaml options: @@ -19,20 +36,31 @@ options: experimentalcli: false kubernetes: false swarm: false - - option: load-local-template + - option: name + value_type: string + description: 'Name for the sandbox (default: -)' + details_url: '#name' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: patch-settings value_type: bool default_value: "false" - description: Load a locally built template image into the sandbox + description: Intercept claude settings API call and patch payload deprecated: false - hidden: false + hidden: true experimental: false experimentalcli: false kubernetes: false swarm: false - - option: name + - option: pull-template value_type: string - description: 'Name for the sandbox (default: -)' - details_url: '#name' + default_value: missing + description: | + Template image pull policy: always (always pull from registry), missing (pull only if not cached), never (use only cached images) deprecated: false hidden: false experimental: false @@ -128,14 +156,6 @@ examples: |- ```console $ docker sandbox run claude . -- -p "What version are you running?" ``` - - ### Run with locally built template - - Use `--load-local-template` to test local template changes: - - ```console - $ docker sandbox run --load-local-template claude . - ``` deprecated: false hidden: false experimental: false diff --git a/data/sandbox-cli/docker_sandbox_save.yaml b/data/sandbox-cli/docker_sandbox_save.yaml index 253c6c577936..1c11f37851c7 100644 --- a/data/sandbox-cli/docker_sandbox_save.yaml +++ b/data/sandbox-cli/docker_sandbox_save.yaml @@ -5,6 +5,13 @@ long: |- By default, the image is loaded into the host's Docker daemon (requires Docker to be running). Use --output to save the image to a tar file instead. + + Examples: + # Load into host Docker (requires host Docker running) + docker sandbox save my-sandbox myimage:v1.0 + + # Save to file (works without host Docker) + docker sandbox save my-sandbox myimage:v1.0 --output /tmp/myimage.tar usage: docker sandbox save SANDBOX TAG pname: docker sandbox plink: docker_sandbox.yaml