From 546686293c2614a4f1ac443c46171181366b93ff Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Thu, 6 Nov 2025 08:23:57 +0100 Subject: [PATCH 1/2] cli: add reference docs for docker sandbox Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> --- .../reference/cli/docker/sandbox/_index.md | 6 + .../reference/cli/docker/sandbox/inspect.md | 6 + content/reference/cli/docker/sandbox/ls.md | 6 + content/reference/cli/docker/sandbox/rm.md | 6 + content/reference/cli/docker/sandbox/run.md | 6 + .../reference/cli/docker/sandbox/version.md | 6 + data/sandbox-cli/docker_sandbox.yaml | 37 +++ data/sandbox-cli/docker_sandbox_inspect.yaml | 59 +++++ data/sandbox-cli/docker_sandbox_ls.yaml | 65 +++++ data/sandbox-cli/docker_sandbox_rm.yaml | 49 ++++ data/sandbox-cli/docker_sandbox_run.yaml | 232 ++++++++++++++++++ data/sandbox-cli/docker_sandbox_version.yaml | 25 ++ 12 files changed, 503 insertions(+) create mode 100644 content/reference/cli/docker/sandbox/_index.md create mode 100644 content/reference/cli/docker/sandbox/inspect.md create mode 100644 content/reference/cli/docker/sandbox/ls.md create mode 100644 content/reference/cli/docker/sandbox/rm.md create mode 100644 content/reference/cli/docker/sandbox/run.md create mode 100644 content/reference/cli/docker/sandbox/version.md create mode 100644 data/sandbox-cli/docker_sandbox.yaml create mode 100644 data/sandbox-cli/docker_sandbox_inspect.yaml create mode 100644 data/sandbox-cli/docker_sandbox_ls.yaml create mode 100644 data/sandbox-cli/docker_sandbox_rm.yaml create mode 100644 data/sandbox-cli/docker_sandbox_run.yaml create mode 100644 data/sandbox-cli/docker_sandbox_version.yaml diff --git a/content/reference/cli/docker/sandbox/_index.md b/content/reference/cli/docker/sandbox/_index.md new file mode 100644 index 000000000000..5fec0ca171dd --- /dev/null +++ b/content/reference/cli/docker/sandbox/_index.md @@ -0,0 +1,6 @@ +--- +datafolder: sandbox-cli +datafile: docker_sandbox +title: docker sandbox +layout: cli +--- diff --git a/content/reference/cli/docker/sandbox/inspect.md b/content/reference/cli/docker/sandbox/inspect.md new file mode 100644 index 000000000000..1e337eda06fc --- /dev/null +++ b/content/reference/cli/docker/sandbox/inspect.md @@ -0,0 +1,6 @@ +--- +datafolder: sandbox-cli +datafile: docker_sandbox_inspect +title: docker sandbox inspect +layout: cli +--- diff --git a/content/reference/cli/docker/sandbox/ls.md b/content/reference/cli/docker/sandbox/ls.md new file mode 100644 index 000000000000..687a513f914c --- /dev/null +++ b/content/reference/cli/docker/sandbox/ls.md @@ -0,0 +1,6 @@ +--- +datafolder: sandbox-cli +datafile: docker_sandbox_ls +title: docker sandbox ls +layout: cli +--- diff --git a/content/reference/cli/docker/sandbox/rm.md b/content/reference/cli/docker/sandbox/rm.md new file mode 100644 index 000000000000..8c9cf5474184 --- /dev/null +++ b/content/reference/cli/docker/sandbox/rm.md @@ -0,0 +1,6 @@ +--- +datafolder: sandbox-cli +datafile: docker_sandbox_rm +title: docker sandbox rm +layout: cli +--- diff --git a/content/reference/cli/docker/sandbox/run.md b/content/reference/cli/docker/sandbox/run.md new file mode 100644 index 000000000000..249d177ad93e --- /dev/null +++ b/content/reference/cli/docker/sandbox/run.md @@ -0,0 +1,6 @@ +--- +datafolder: sandbox-cli +datafile: docker_sandbox_run +title: docker sandbox run +layout: cli +--- diff --git a/content/reference/cli/docker/sandbox/version.md b/content/reference/cli/docker/sandbox/version.md new file mode 100644 index 000000000000..fa95deba087d --- /dev/null +++ b/content/reference/cli/docker/sandbox/version.md @@ -0,0 +1,6 @@ +--- +datafolder: sandbox-cli +datafile: docker_sandbox_version +title: docker sandbox version +layout: cli +--- diff --git a/data/sandbox-cli/docker_sandbox.yaml b/data/sandbox-cli/docker_sandbox.yaml new file mode 100644 index 000000000000..151e981725a7 --- /dev/null +++ b/data/sandbox-cli/docker_sandbox.yaml @@ -0,0 +1,37 @@ +command: docker sandbox +short: Docker Sandbox +long: Local sandbox environments for AI agents, using Docker. +usage: docker sandbox +pname: docker +plink: docker.yaml +cname: + - docker sandbox inspect + - docker sandbox ls + - docker sandbox rm + - docker sandbox run + - docker sandbox version +clink: + - docker_sandbox_inspect.yaml + - docker_sandbox_ls.yaml + - docker_sandbox_rm.yaml + - docker_sandbox_run.yaml + - docker_sandbox_version.yaml +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 +deprecated: false +hidden: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false + diff --git a/data/sandbox-cli/docker_sandbox_inspect.yaml b/data/sandbox-cli/docker_sandbox_inspect.yaml new file mode 100644 index 000000000000..6e18e67102c0 --- /dev/null +++ b/data/sandbox-cli/docker_sandbox_inspect.yaml @@ -0,0 +1,59 @@ +command: docker sandbox inspect +short: Display detailed information on one or more sandboxes +long: |- + Display detailed information on one or more sandboxes. + + This command retrieves and displays detailed information about the specified + sandboxes using the Docker API. Each sandbox is identified by its unique ID or name. +usage: docker sandbox inspect [OPTIONS] SANDBOX [SANDBOX...] +pname: docker sandbox +plink: docker_sandbox.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 +examples: |- + ### Inspect a sandbox + + ```console + $ docker sandbox inspect abc123def + [ + { + "id": "abc123def69b16c5c0dab4cf699e26f8d01e1ace3aeee06254e0999492e11647", + "name": "claude-sandbox-2025-11-04-170333", + "created_at": "2025-11-04T16:03:33.910642347Z", + "status": "running", + "template": "docker/sandbox-templates:claude-code", + "labels": { + "com.docker.sandbox.agent": "claude", + "com.docker.sandbox.workingDirectory": "/Users/moby/code/docker/sandboxes", + "com.docker.sandbox.workingDirectoryInode": "3041007", + "com.docker.sandboxes": "templates", + "com.docker.sandboxes.base": "ubuntu:questing", + "com.docker.sandboxes.flavor": "claude-code", + "com.docker.sdk": "true", + "com.docker.sdk.client": "0.1.0-alpha011", + "com.docker.sdk.container": "0.1.0-alpha012", + "com.docker.sdk.lang": "go", + "docker/sandbox": "true", + "org.opencontainers.image.ref.name": "ubuntu", + "org.opencontainers.image.version": "25.10" + } + } + ] + ``` +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 new file mode 100644 index 000000000000..e951bfabab88 --- /dev/null +++ b/data/sandbox-cli/docker_sandbox_ls.yaml @@ -0,0 +1,65 @@ +command: docker sandbox ls +aliases: docker sandbox ls, docker sandbox list +short: List sandboxes +long: |- + List all sandboxes. + + This command lists all sandboxes using the Docker API. +usage: docker sandbox ls +pname: docker sandbox +plink: docker_sandbox.yaml +options: + - option: quiet + shorthand: q + value_type: bool + default_value: "false" + description: Only display sandbox IDs + details_url: '#quiet' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +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 +examples: |- + ### List all sandboxes + + ```console + $ docker sandbox ls + SANDBOX ID NAME WORKSPACE CREATED + abc123def my-project /home/user/my-project 2 hours ago + def456ghi ml-work /home/user/ml-projects 1 day ago + ``` + + ### Show only sandbox IDs (--quiet) {#quiet} + + ```text + --quiet + ``` + + Output only sandbox IDs: + + ```console + $ docker sandbox ls --quiet + abc123def + def456ghi + ``` +deprecated: false +hidden: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false + diff --git a/data/sandbox-cli/docker_sandbox_rm.yaml b/data/sandbox-cli/docker_sandbox_rm.yaml new file mode 100644 index 000000000000..5a7a40882373 --- /dev/null +++ b/data/sandbox-cli/docker_sandbox_rm.yaml @@ -0,0 +1,49 @@ +command: docker sandbox rm +short: Remove one or more sandboxes +long: |- + Remove one or more sandboxes by their IDs or names. + + This command removes the specified sandboxes. Each sandbox is identified by its unique ID or name. +usage: docker sandbox rm [OPTIONS] SANDBOX [SANDBOX...] +pname: docker sandbox +plink: docker_sandbox.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 +examples: |- + ### Remove a sandbox + + ```console + $ docker sandbox rm abc123def + abc123def + ``` + + ### Remove multiple sandboxes + + ```console + $ docker sandbox rm abc123def def456ghi + abc123def + def456ghi + ``` + + ### Remove all sandboxes + + ```console + $ docker sandbox rm $(docker sandbox ls -q) + ``` +deprecated: false +hidden: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false + diff --git a/data/sandbox-cli/docker_sandbox_run.yaml b/data/sandbox-cli/docker_sandbox_run.yaml new file mode 100644 index 000000000000..f32380102f98 --- /dev/null +++ b/data/sandbox-cli/docker_sandbox_run.yaml @@ -0,0 +1,232 @@ +command: docker sandbox run +short: Run an AI agent inside a sandbox +long: |- + Run an AI agent inside a sandbox with access to a host workspace. + + The agent argument must be one of: claude, gemini. + Agent-specific options can be passed after the agent name. + If no workspace is specified via the "--workspace" option, the current working directory is used. + The workspace is exposed inside the sandbox at the same path as on the host. +usage: docker sandbox run [options] [agent-options] +pname: docker sandbox +plink: docker_sandbox.yaml +options: + - option: credentials + value_type: string + default_value: sandbox + description: Credentials source (host, sandbox, or none) + details_url: '#credentials' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: detached + shorthand: d + value_type: bool + default_value: "false" + description: Create sandbox without running agent interactively + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: env + shorthand: e + value_type: stringSlice + default_value: '[]' + description: 'Set environment variables (format: KEY=VALUE)' + details_url: '#env' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: mount-docker-socket + value_type: bool + default_value: "false" + description: Mount the host's Docker socket into the sandbox + details_url: '#mount-docker-socket' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: name + value_type: string + description: Name for the sandbox + details_url: '#name' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: quiet + shorthand: q + value_type: bool + default_value: "false" + description: Suppress verbose output + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: template + shorthand: t + value_type: string + description: | + Container image to use for the sandbox (default: agent-specific image) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: volume + shorthand: v + value_type: stringSlice + default_value: '[]' + description: | + Bind mount a volume or host file or directory into the sandbox (format: hostpath:sandboxpath[:readonly|:ro]) + details_url: '#volume' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: workspace + shorthand: w + value_type: string + default_value: . + description: Workspace path + details_url: '#workspace' + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +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 +examples: |- + ### Run Claude in the current directory + + ```console + $ docker sandbox run claude + ``` + + ### Specify a workspace directory (-w, --workspace) {#workspace} + + ```text + --workspace PATH + ``` + + Run the agent in a specific directory: + + ```console + $ docker sandbox run --workspace ~/projects/my-app claude + ``` + + The workspace directory is mounted at the same absolute path inside the sandbox. + + ### Enable Docker-in-Docker (--mount-docker-socket) {#mount-docker-socket} + + ```text + --mount-docker-socket + ``` + + Mount the host's Docker socket into the sandbox, giving the agent access to Docker commands: + + ```console + $ docker sandbox run --mount-docker-socket claude + ``` + + > [!CAUTION] + > This grants the agent full access to your Docker daemon with root-level + > privileges. Only use when you trust the code being executed. + + The agent can now build images, run containers, and manage your Docker environment. + + ### Set environment variables (-e, --env) {#env} + + ```text + --env KEY=VALUE + ``` + + Pass environment variables to the sandbox: + + ```console + $ docker sandbox run \ + --env NODE_ENV=development \ + --env DATABASE_URL=postgresql://localhost/myapp \ + claude + ``` + + ### Mount additional volumes (-v, --volume) {#volume} + + ```text + --volume HOST_PATH:CONTAINER_PATH[:ro] + ``` + + Mount additional directories or files into the sandbox: + + ```console + $ docker sandbox run \ + --volume ~/datasets:/data:ro \ + --volume ~/models:/models \ + claude + ``` + + Use `:ro` or `:readonly` to make mounts read-only. + + ### Configure credential access (--credentials) {#credentials} + + ```text + --credentials MODE + ``` + + Control how the agent accesses credentials. Valid modes are: + + - `sandbox` (default): Authenticate once and share credentials across sandboxes + - `host`: Share host credentials (~/.gitconfig, ~/.ssh, etc.) + - `none`: Handle authentication manually + + ```console + $ docker sandbox run --credentials host claude + ``` + + ### Name the sandbox (--name) {#name} + + ```text + --name NAME + ``` + + Assign a custom name to the sandbox for easier identification: + + ```console + $ docker sandbox run --name my-project claude + ``` +deprecated: false +hidden: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false + diff --git a/data/sandbox-cli/docker_sandbox_version.yaml b/data/sandbox-cli/docker_sandbox_version.yaml new file mode 100644 index 000000000000..286d5860a60b --- /dev/null +++ b/data/sandbox-cli/docker_sandbox_version.yaml @@ -0,0 +1,25 @@ +command: docker sandbox version +short: Show sandboxd version information +long: Show sandboxd version information +usage: docker sandbox version +pname: docker sandbox +plink: docker_sandbox.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 +deprecated: false +hidden: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false + From fabb108e1f80cd61e7b6c1d2bc5541b0a706e9d1 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Wed, 5 Nov 2025 14:01:09 +0100 Subject: [PATCH 2/2] ai: add docs for local agent sandboxes Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> --- _vale/config/vocabularies/Docker/accept.txt | 4 +- content/manuals/ai/compose/_index.md | 4 +- content/manuals/ai/gordon/_index.md | 2 +- .../ai/mcp-catalog-and-toolkit/_index.md | 2 +- .../{sandboxes.md => e2b-sandboxes.md} | 141 ++++---- content/manuals/ai/model-runner/_index.md | 2 +- content/manuals/ai/sandboxes/_index.md | 70 ++++ .../manuals/ai/sandboxes/advanced-config.md | 305 ++++++++++++++++++ content/manuals/ai/sandboxes/claude-code.md | 153 +++++++++ content/manuals/ai/sandboxes/get-started.md | 94 ++++++ .../manuals/ai/sandboxes/troubleshooting.md | 121 +++++++ data/sandbox-cli/docker_sandbox_ls.yaml | 29 ++ data/sandbox-cli/docker_sandbox_run.yaml | 16 + data/summary.yaml | 3 + 14 files changed, 861 insertions(+), 85 deletions(-) rename content/manuals/ai/mcp-catalog-and-toolkit/{sandboxes.md => e2b-sandboxes.md} (67%) create mode 100644 content/manuals/ai/sandboxes/_index.md create mode 100644 content/manuals/ai/sandboxes/advanced-config.md create mode 100644 content/manuals/ai/sandboxes/claude-code.md create mode 100644 content/manuals/ai/sandboxes/get-started.md create mode 100644 content/manuals/ai/sandboxes/troubleshooting.md diff --git a/_vale/config/vocabularies/Docker/accept.txt b/_vale/config/vocabularies/Docker/accept.txt index 3a8096944aaf..f7c665667fe7 100644 --- a/_vale/config/vocabularies/Docker/accept.txt +++ b/_vale/config/vocabularies/Docker/accept.txt @@ -1,5 +1,7 @@ (?i)[A-Z]{2,}'?s - +jq +ripgrep +sandboxing Adreno Aleksandrov Amazon diff --git a/content/manuals/ai/compose/_index.md b/content/manuals/ai/compose/_index.md index a861d426a60e..45e017bcaf08 100644 --- a/content/manuals/ai/compose/_index.md +++ b/content/manuals/ai/compose/_index.md @@ -2,8 +2,8 @@ build: render: never title: AI and Docker Compose -weight: 40 +weight: 50 params: sidebar: group: AI ---- \ No newline at end of file +--- diff --git a/content/manuals/ai/gordon/_index.md b/content/manuals/ai/gordon/_index.md index 7cb8e931e850..b9d02f5a2207 100644 --- a/content/manuals/ai/gordon/_index.md +++ b/content/manuals/ai/gordon/_index.md @@ -1,7 +1,7 @@ --- title: Ask Gordon description: Streamline your workflow with Docker's AI-powered assistant in Docker Desktop and CLI. -weight: 10 +weight: 40 params: sidebar: badge: diff --git a/content/manuals/ai/mcp-catalog-and-toolkit/_index.md b/content/manuals/ai/mcp-catalog-and-toolkit/_index.md index 14926e5ef58e..da239fd8f9ad 100644 --- a/content/manuals/ai/mcp-catalog-and-toolkit/_index.md +++ b/content/manuals/ai/mcp-catalog-and-toolkit/_index.md @@ -7,7 +7,7 @@ params: badge: color: blue text: Beta -weight: 30 +weight: 10 description: Learn about Docker's MCP catalog on Docker Hub keywords: Docker, ai, mcp servers, ai agents, extension, docker desktop, llm, docker hub grid: diff --git a/content/manuals/ai/mcp-catalog-and-toolkit/sandboxes.md b/content/manuals/ai/mcp-catalog-and-toolkit/e2b-sandboxes.md similarity index 67% rename from content/manuals/ai/mcp-catalog-and-toolkit/sandboxes.md rename to content/manuals/ai/mcp-catalog-and-toolkit/e2b-sandboxes.md index 90b00b8624fe..ee08b485f935 100644 --- a/content/manuals/ai/mcp-catalog-and-toolkit/sandboxes.md +++ b/content/manuals/ai/mcp-catalog-and-toolkit/e2b-sandboxes.md @@ -1,37 +1,18 @@ --- -title: Sandboxes -description: "Learn how sandboxes provide secure, isolated execution environments for AI agents in the MCP ecosystem, enabling safe code execution and protecting production systems." -keywords: Sandboxes, E2B, MCP Gateway, isolated environment, AI agent security -params: - sidebar: - badge: - color: green - text: New -weight: 50 +title: E2B sandboxes +description: Cloud-based secure sandboxes for AI agents with built-in Docker MCP Gateway integration +keywords: E2B, cloud sandboxes, MCP Gateway, AI agents, MCP Catalog +aliases: + - /ai/mcp-catalog-and-toolkit/sandboxes/ --- -Sandboxes are isolated execution environments that provide secure, controlled spaces for running code and applications without affecting the host system. They create strict boundaries around executing processes, preventing access to unauthorized resources while providing consistent, reproducible environments. Think of it as a virtual "playground" with clearly defined boundaries, where code can execute freely within those boundaries but cannot escape to impact other systems or access sensitive data. +Docker has partnered with [E2B](https://e2b.dev/), a provider of secure cloud sandboxes for AI agents. Through this partnership, every E2B sandbox includes direct access to Docker's [MCP Catalog](https://hub.docker.com/mcp), a collection of 200+ tools from publishers including GitHub, Notion, and Stripe. -In the Model Context Protocol ecosystem, sandboxes address several critical challenges that arise when AI agents need to execute code or interact with external systems. They enable safe code execution for AI-generated scripts, secure tool validation for MCP servers, and multi-tenant isolation when multiple agents share infrastructure. This ensures that sensitive credentials and data remain protected within appropriate security boundaries while maintaining compliance and audit requirements. - -## Key features - -- Isolation and Security: Complete separation between executing code and the host environment, with strict controls over file access, network connections, and system calls. -- Resource Management: Fine-grained control over CPU, memory, disk space, and network usage to prevent resource exhaustion. -- Reproducible Environments: Consistent, predictable execution environments. Code that runs successfully in one sandbox instance will behave identically in another. -- Ephemeral Environments: Temporary, disposable environments that can be destroyed after task completion, leaving no persistent artifacts. - -## E2B sandboxes - -Docker has partnered with [E2B](https://e2b.dev/), a provider of secure cloud sandboxes for AI agents. Through this partnership, every E2B sandbox now includes direct access to Docker’s [MCP Catalog](https://hub.docker.com/mcp), a collection of 200+ tools, including ones from known publishers such as GitHub, Notion, and Stripe, all enabled through the Docker MCP Gateway. - -When creating a new sandbox, E2B users can specify which MCP tools the sandbox should access. E2B then launches these MCP tools and provides access through the Docker MCP Gateway. - -The following example shows how to set up an E2B sandbox with GitHub and Notion MCP servers. +When you create a sandbox, you specify which MCP tools it should access. E2B launches these tools and provides access through the Docker MCP Gateway. ## Example: Using GitHub and Notion MCP server -The following example demonstrates how to analyze data in Notion and create GitHub issues. By the end, you'll understand how to connect multiple MCP servers in an E2B sandbox and orchestrate cross-platform workflows. +This example demonstrates how to connect multiple MCP servers in an E2B sandbox. You'll analyze data in Notion and create GitHub issues using Claude. ### Prerequisites @@ -40,29 +21,28 @@ Before you begin, make sure you have the following: - [E2B account](https://e2b.dev/docs/quickstart) with API access - Anthropic API key for Claude - >[!Note] - > - > This example uses Claude CLI which comes pre-installed in E2B sandboxes. However, - > you can adapt the example to work with other AI assistants of your choice. See - > [E2B's MCP documentation](https://e2b.dev/docs/mcp/quickstart) for alternative - > connection methods. + > [!NOTE] + > This example uses Claude Code which comes pre-installed in E2B sandboxes. + > However, you can adapt the example to work with other AI assistants of your + > choice. See [E2B's MCP documentation](https://e2b.dev/docs/mcp/quickstart) + > for alternative connection methods. - Node.js 18+ installed on your machine - Notion account with: - A database containing sample data - [Integration token](https://www.notion.com/help/add-and-manage-connections-with-the-api) - GitHub account with: - - A repository for testing - - Personal access token with `repo` scope + - A repository for testing + - Personal access token with `repo` scope ### Set up your environment Create a new directory and initialize a Node.js project: -```bash -mkdir mcp-e2b-quickstart -cd mcp-e2b-quickstart -npm init -y +```console +$ mkdir mcp-e2b-quickstart +$ cd mcp-e2b-quickstart +$ npm init -y ``` Configure your project for ES modules by updating `package.json`: @@ -80,24 +60,26 @@ Configure your project for ES modules by updating `package.json`: Install required dependencies: -```bash -npm install e2b dotenv +```console +$ npm install e2b dotenv ``` Create a `.env` file with your credentials: -```bash +```console +$ cat > .env << 'EOF' E2B_API_KEY=your_e2b_api_key_here ANTHROPIC_API_KEY=your_anthropic_api_key_here NOTION_INTEGRATION_TOKEN=ntn_your_notion_integration_token_here GITHUB_TOKEN=ghp_your_github_pat_here +EOF ``` Protect your credentials: -```bash -echo ".env" >> .gitignore -echo "node_modules/" >> .gitignore +```console +$ echo ".env" >> .gitignore +$ echo "node_modules/" >> .gitignore ``` ### Create an E2B sandbox with MCP servers @@ -108,8 +90,8 @@ echo "node_modules/" >> .gitignore Create a file named `index.ts`: ```typescript -import 'dotenv/config'; -import { Sandbox } from 'e2b'; +import "dotenv/config"; +import { Sandbox } from "e2b"; async function quickstart(): Promise { console.log("Creating E2B sandbox with Notion and GitHub MCP servers...\n"); @@ -120,7 +102,8 @@ async function quickstart(): Promise { }, mcp: { notion: { - internalIntegrationToken: process.env.NOTION_INTEGRATION_TOKEN as string, + internalIntegrationToken: process.env + .NOTION_INTEGRATION_TOKEN as string, }, githubOfficial: { githubPersonalAccessToken: process.env.GITHUB_TOKEN as string, @@ -135,17 +118,17 @@ async function quickstart(): Promise { console.log(`MCP Gateway URL: ${mcpUrl}\n`); // Wait for MCP initialization - await new Promise(resolve => setTimeout(resolve, 1000)); + await new Promise((resolve) => setTimeout(resolve, 1000)); - // Connect Claude CLI to MCP gateway - console.log("Connecting Claude CLI to MCP gateway..."); + // Connect Claude to MCP gateway + console.log("Connecting Claude to MCP gateway..."); await sbx.commands.run( `claude mcp add --transport http e2b-mcp-gateway ${mcpUrl} --header "Authorization: Bearer ${mcpToken}"`, { timeoutMs: 0, onStdout: console.log, - onStderr: console.log - } + onStderr: console.log, + }, ); console.log("\nConnection successful! Cleaning up..."); @@ -157,8 +140,8 @@ quickstart().catch(console.error); Run the script: -```typescript -npx tsx index.ts +```console +$ npx tsx index.ts ``` {{< /tab >}} @@ -200,8 +183,8 @@ async def quickstart(): # Wait for MCP initialization await asyncio.sleep(1) - # Connect Claude CLI to MCP gateway - print("Connecting Claude CLI to MCP gateway...") + # Connect Claude to MCP gateway + print("Connecting Claude to MCP gateway...") def on_stdout(output): print(output, end='') @@ -229,8 +212,8 @@ if __name__ == "__main__": Run the script: -```python -python index.py +```console +$ python index.py ``` {{< /tab >}} @@ -238,13 +221,13 @@ python index.py You should see: -```bash +```console Creating E2B sandbox with Notion and GitHub MCP servers... Sandbox created successfully! MCP Gateway URL: https://50005-xxxxx.e2b.app/mcp -Connecting Claude CLI to MCP gateway... +Connecting Claude to MCP gateway... Added HTTP MCP server e2b-mcp-gateway with URL: https://50005-xxxxx.e2b.app/mcp Connection successful! Cleaning up... @@ -257,7 +240,7 @@ Now, test the setup by running a simple workflow that searches Notion and create {{< tabs group="" >}} {{< tab name="Typescript">}} ->[!IMPORTANT] +> [!IMPORTANT] > > Replace `owner/repo` in the prompt with your actual GitHub username and repository > name (for example, `yourname/test-repo`). @@ -265,8 +248,8 @@ Now, test the setup by running a simple workflow that searches Notion and create Update `index.ts` with the following example: ```typescript -import 'dotenv/config'; -import { Sandbox } from 'e2b'; +import "dotenv/config"; +import { Sandbox } from "e2b"; async function exampleWorkflow(): Promise { console.log("Creating sandbox...\n"); @@ -277,7 +260,8 @@ async function exampleWorkflow(): Promise { }, mcp: { notion: { - internalIntegrationToken: process.env.NOTION_INTEGRATION_TOKEN as string, + internalIntegrationToken: process.env + .NOTION_INTEGRATION_TOKEN as string, }, githubOfficial: { githubPersonalAccessToken: process.env.GITHUB_TOKEN as string, @@ -291,7 +275,7 @@ async function exampleWorkflow(): Promise { console.log("Sandbox created successfully\n"); // Wait for MCP servers to initialize - await new Promise(resolve => setTimeout(resolve, 3000)); + await new Promise((resolve) => setTimeout(resolve, 3000)); console.log("Connecting Claude to MCP gateway...\n"); await sbx.commands.run( @@ -299,8 +283,8 @@ async function exampleWorkflow(): Promise { { timeoutMs: 0, onStdout: console.log, - onStderr: console.log - } + onStderr: console.log, + }, ); console.log("\nRunning example: Search Notion and create GitHub issue...\n"); @@ -315,8 +299,8 @@ async function exampleWorkflow(): Promise { { timeoutMs: 0, onStdout: console.log, - onStderr: console.log - } + onStderr: console.log, + }, ); await sbx.kill(); @@ -327,8 +311,8 @@ exampleWorkflow().catch(console.error); Run the script: -```typescript -npx tsx index.ts +```console +$ npx tsx index.ts ``` {{< /tab >}} @@ -336,7 +320,7 @@ npx tsx index.ts Update `index.py` with this example: ->[!IMPORTANT] +> [!IMPORTANT] > > Replace `owner/repo` in the prompt with your actual GitHub username and repository > name (for example, `yourname/test-repo`). @@ -418,8 +402,8 @@ if __name__ == "__main__": Run the script: -```bash -python workflow.py +```console +$ python workflow.py ``` {{< /tab >}} @@ -427,7 +411,7 @@ python workflow.py You should see: -```bash +```console Creating sandbox... Running example: Search Notion and create GitHub issue... @@ -456,14 +440,13 @@ Successfully created test issue: Both operations completed successfully. The MCP servers are properly configured and working. ``` -You've successfully created an E2B sandbox with multiple MCP servers and used Claude to orchestrate a workflow across Notion and GitHub. - -You can extend this example to combine any of the 200+ MCP servers in the Docker MCP Catalog to build sophisticated automation workflows for your specific needs. +The sandbox connected multiple MCP servers and orchestrated a workflow across Notion and GitHub. You can extend this pattern to combine any of the 200+ MCP servers in the Docker MCP Catalog. ## Related pages - [How to build an AI-powered code quality workflow with SonarQube and E2B](/guides/github-sonarqube-sandbox.md) - [Docker + E2B: Building the Future of Trusted AI](https://www.docker.com/blog/docker-e2b-building-the-future-of-trusted-ai/) +- [Docker Sandboxes](/manuals/ai/sandboxes/_index.md) - [Docker MCP Toolkit and Catalog](/manuals/ai/mcp-catalog-and-toolkit/_index.md) - [Docker MCP Gateway](/manuals/ai/mcp-catalog-and-toolkit/mcp-gateway.md) - [E2B MCP documentation](https://e2b.dev/docs/mcp) diff --git a/content/manuals/ai/model-runner/_index.md b/content/manuals/ai/model-runner/_index.md index f60283c001a1..d0a61b153e99 100644 --- a/content/manuals/ai/model-runner/_index.md +++ b/content/manuals/ai/model-runner/_index.md @@ -4,7 +4,7 @@ linkTitle: Model Runner params: sidebar: group: AI -weight: 20 +weight: 30 description: Learn how to use Docker Model Runner to manage and run AI models. keywords: Docker, ai, model runner, docker desktop, docker engine, llm aliases: diff --git a/content/manuals/ai/sandboxes/_index.md b/content/manuals/ai/sandboxes/_index.md new file mode 100644 index 000000000000..9eecb9e09f09 --- /dev/null +++ b/content/manuals/ai/sandboxes/_index.md @@ -0,0 +1,70 @@ +--- +title: Docker Sandboxes +description: Run AI agents in isolated environments +weight: 20 +params: + sidebar: + group: AI + badge: + color: violet + text: Experimental +--- + +{{< summary-bar feature_name="Docker Sandboxes" >}} + +Docker Sandboxes simplifies running AI agents securely on your local machine. +Designed for developers building with coding agents like Claude Code, Sandboxes +isolate your agents from your local machine while preserving a familiar +development experience. With Docker Sandboxes, agents can execute commands, +install packages, and modify files inside a containerized workspace that +mirrors your local directory. This gives you full agent autonomy without +compromising safety. + +## How it works + +When you run `docker sandbox run `: + +1. Docker creates a container from a template image and mounts your current + working directory into the container at the same path. + +2. Docker discovers your Git `user.name` and `user.email` configuration and + injects it into the container so commits made by the agent are attributed + to you. + +3. On first run, you're prompted to authenticate. Credentials are stored in a + Docker volume and reused for future sandboxed agents. + +4. The agent starts inside the container with bypass permissions enabled. + +### Workspace mounting + +Your workspace directory is mounted into the container at the same absolute path +(on macOS and Linux). For example, `/Users/alice/projects/myapp` on your host +is also `/Users/alice/projects/myapp` in the container. This means: + +- File paths in error messages match your host +- Scripts with hard-coded paths work as expected +- Changes to workspace files are immediately visible on both host and container + +### One sandbox per workspace + +Docker enforces one sandbox per workspace. When you run `docker sandbox run +` in the same directory, Docker reuses the existing container. This +means state (installed packages, temporary files) persists across agent sessions +in that workspace. + +> [!NOTE] +> To change a sandbox's configuration (environment variables, mounted volumes, +> etc.), you need to remove and recreate it. See +> [Managing sandboxes](advanced-config.md#managing-sandboxes) for details. + +## Release status + +Docker Sandboxes is an experimental feature. Features and setup are subject to +change. + +Report issues on [GitHub](https://github.com/docker/desktop-feedback). + +## Get started + +Head to the [Get started guide](get-started.md) to run your first sandboxed agent. diff --git a/content/manuals/ai/sandboxes/advanced-config.md b/content/manuals/ai/sandboxes/advanced-config.md new file mode 100644 index 000000000000..2a733066afa9 --- /dev/null +++ b/content/manuals/ai/sandboxes/advanced-config.md @@ -0,0 +1,305 @@ +--- +title: Advanced configurations +linkTitle: Advanced +description: Docker access, volume mounting, environment variables, custom templates, and sandbox management. +weight: 40 +--- + +{{< summary-bar feature_name="Docker Sandboxes" >}} + +This guide covers advanced configurations for sandboxed agents running locally. + +## Managing sandboxes + +### Recreating sandboxes + +Since Docker enforces one sandbox per workspace, the same sandbox is reused +each time you run `docker sandbox run ` in a given directory. To create +a fresh sandbox, you need to remove the existing one first: + +```console +$ docker sandbox ls # Find the sandbox ID +$ docker sandbox rm +$ docker sandbox run # Creates a new sandbox +``` + +### When to recreate sandboxes + +Sandboxes remember their initial configuration and don't pick up changes from subsequent `docker sandbox run` commands. You must recreate the sandbox to modify: + +- Environment variables (the `-e` flag) +- Volume mounts (the `-v` flag) +- Docker socket access (the `--mount-docker-socket` flag) +- Credentials mode (the `--credentials` flag) + +### Listing and inspecting sandboxes + +View all your sandboxes: + +```console +$ docker sandbox ls +``` + +Get detailed information about a specific sandbox: + +```console +$ docker sandbox inspect +``` + +This shows the sandbox's configuration, including environment variables, volumes, and creation time. + +### Removing sandboxes + +Remove a specific sandbox: + +```console +$ docker sandbox rm +``` + +Remove all sandboxes at once: + +```console +$ docker sandbox rm $(docker sandbox ls -q) +``` + +This is useful for cleanup when you're done with a project or want to start fresh. + +## Giving agents access to Docker + +Mount the Docker socket to give agents access to Docker commands inside the +container. The agent can build images, run containers, and work with Docker +Compose setups. + +> [!CAUTION] +> Mounting the Docker socket grants the agent full access to your Docker daemon, +> which has root-level privileges on your system. The agent can start or stop +> any container, access volumes, and potentially escape the sandbox. Only use +> this option when you fully trust the code the agent is working with. + +### Enable Docker socket access + +Use the `--mount-docker-socket` flag: + +```console +$ docker sandbox run --mount-docker-socket claude +``` + +This mounts your host's Docker socket (`/var/run/docker.sock`) into the +container, giving the agent access to Docker commands. + +> [!IMPORTANT] +> The agent can see and interact with all containers on your host, not just +> those created within the sandbox. + +### Example: Testing a containerized application + +If your project has a Dockerfile, the agent can build and test it: + +```console +$ cd ~/my-docker-app +$ docker sandbox run --mount-docker-socket claude +``` + +Example conversation: + +```plaintext +You: "Build the Docker image and run the tests" + +Claude: *runs* + docker build -t myapp:test . + docker run myapp:test npm test +``` + +### What agents can do with Docker socket access + +With Docker access enabled, agents can: + +- Start multi-container applications with Docker Compose +- Build images for multiple architectures +- Manage existing containers on your host +- Validate Dockerfiles and test build processes + +## Environment variables + +Pass environment variables to configure the sandbox environment with the `-e` +flag: + +```console +$ docker sandbox run \ + -e NODE_ENV=development \ + -e DATABASE_URL=postgresql://localhost/myapp_dev \ + -e DEBUG=true \ + claude +``` + +These variables are available to all processes in the container, including the +agent and any commands it runs. Use multiple `-e` flags for multiple variables. + +### Example: Development environment setup + +Set up a complete development environment: + +```console +$ docker sandbox run \ + -e NODE_ENV=development \ + -e DATABASE_URL=postgresql://localhost/myapp_dev \ + -e REDIS_URL=redis://localhost:6379 \ + -e LOG_LEVEL=debug \ + claude +``` + +Example conversation: + +```plaintext +You: "Run the database migrations and start the development server" + +Claude: *uses DATABASE_URL and other environment variables* + npm run migrate + npm run dev +``` + +### Common use cases + +API keys for testing: + +```console +$ docker sandbox run \ + -e STRIPE_TEST_KEY=sk_test_xxx \ + -e SENDGRID_API_KEY=SG.xxx \ + claude +``` + +> [!CAUTION] +> Only use test/development API keys in sandboxes, never production keys. + +Loading from .env files: + +Sandboxes don't automatically load `.env` files from your workspace, but you can ask Claude to use them: + +```plaintext +You: "Load environment variables from .env.development and start the server" +``` + +Claude can use `dotenv` tools or source the file directly. + +## Volume mounting + +Mount additional directories or files to share data beyond your main workspace. +Use the `-v` flag with the syntax `host-path:container-path`: + +```console +$ docker sandbox run -v ~/datasets:/data claude +``` + +This makes `~/datasets` available at `/data` inside the container. The agent +can read and write files in this location. + +Read-only mounts: + +Add `:ro` to prevent modifications: + +```console +$ docker sandbox run -v ~/configs/app.yml:/config/app.yml:ro claude +``` + +Multiple mounts: + +Use multiple `-v` flags to mount several locations: + +```console +$ docker sandbox run \ + -v ~/datasets:/data:ro \ + -v ~/models:/models \ + -v ~/.cache/pip:/root/.cache/pip \ + claude +``` + +### Example: Machine learning workflow + +Set up an ML environment with shared datasets, model storage, and persistent +caches: + +```console +$ docker sandbox run \ + -v ~/datasets:/data:ro \ + -v ~/models:/models \ + -v ~/.cache/pip:/root/.cache/pip \ + claude +``` + +This provides read-only access to datasets (preventing accidental modifications), +read-write access to save trained models, and a persistent pip cache for faster +package installs across sessions. + +Example conversation: + +```plaintext +You: "Train a model on the MNIST dataset and save it to /models" + +Claude: *runs* + python train.py --data /data/mnist --output /models/mnist_model.h5 +``` + +### Common use cases + +Shared configuration files: + +```console +$ docker sandbox run -v ~/.aws:/root/.aws:ro claude +``` + +Build caches: + +```console +$ docker sandbox run \ + -v ~/.cache/go-build:/root/.cache/go-build \ + -v ~/go/pkg/mod:/go/pkg/mod \ + claude +``` + +Custom tools: + +```console +$ docker sandbox run -v ~/bin:/shared-bin:ro claude +``` + +## Custom templates + +Create custom sandbox templates to reuse configured environments. Instead of +installing tools every time you start an agent, build a Docker image with +everything pre-installed: + +```dockerfile +# syntax=docker/dockerfile:1 +FROM docker/sandbox-templates:claude-code +RUN <}} + +This guide covers authentication, configuration files, and common options for +running Claude Code in a sandboxed environment. + +## Quick start + +The simplest way to start Claude in a sandbox: + +```console +$ docker sandbox run claude +``` + +This starts a sandboxed Claude Code agent with the current working directory as +its workspace. + +Or specify a different workspace: + +```console +$ docker sandbox run -w ~/my-project claude +``` + +## Passing CLI options to Claude + +Claude Code supports various command-line options that you can pass through +`docker sandbox run`. Any arguments after the agent name (`claude`) are passed +directly to Claude Code inside the sandbox. + +### Continue previous conversation + +Resume your most recent conversation: + +```console +$ docker sandbox run claude -c +``` + +Or use the long form: + +```console +$ docker sandbox run claude --continue +``` + +### Pass a prompt directly + +Start Claude with a specific prompt: + +```console +$ docker sandbox run claude "Add error handling to the login function" +``` + +This starts Claude and immediately processes the prompt. + +### Combine options + +You can combine sandbox options with Claude options: + +```console +$ docker sandbox run -e DEBUG=1 claude -c +``` + +This creates a sandbox with `DEBUG` set to `1`, enabling debug output for +troubleshooting, and continues the previous conversation. + +### Available Claude options + +All Claude Code CLI options work through `docker sandbox run`: + +- `-c, --continue` - Continue the most recent conversation +- `-p, --prompt` - Read prompt from stdin (useful for piping) +- `--dangerously-skip-permissions` - Skip permission prompts (enabled by default in sandboxes) +- And more - see the [Claude Code documentation](https://docs.claude.com/en/docs/claude-code) for a complete list + +## Authentication + +Claude sandboxes support the following credential management strategies. + +### Strategy 1: `sandbox` (Default) + +```console +$ docker sandbox run claude +``` + +On first run, Claude prompts you to enter your Anthropic API key. The +credentials are stored in a persistent Docker volume named +`docker-claude-sandbox-data`. All future Claude sandboxes automatically use +these stored credentials, and they persist across sandbox restarts and deletion. + +Sandboxes mount this volume at `/mnt/claude-data` and create symbolic links in +the sandbox user's home directory. + +> [!NOTE] +> If your workspace contains a `.claude.json` file with a `primaryApiKey` +> field, you'll receive a warning about potential conflicts. You can choose to +> remove the `primaryApiKey` field from your `.claude.json` or proceed and +> ignore the warning. + +### Strategy 2: `none` + +No automatic credential management. + +```console +$ docker sandbox run --credentials=none claude +``` + +Docker does not discover, inject, or store any credentials. You must +authenticate manually inside the container. Credentials are not shared with +other sandboxes but persist for the lifetime of the container. + +## Configuration + +Claude Code can be configured through CLI options. Any arguments you pass after +the agent name are passed directly to Claude Code inside the container. + +Pass options after the agent name: + +```console +$ docker sandbox run claude [claude-options] +``` + +For example: + +```console +$ docker sandbox run claude --continue +``` + +See the [Claude Code CLI reference](https://docs.claude.com/en/docs/claude-code/cli-reference) +for a complete list of available options. + +## Advanced usage + +For more advanced configurations including environment variables, volume mounts, +Docker socket access, and custom templates, see +[Advanced configurations](advanced-config.md). + +## Base image + +The `docker/sandbox-templates:claude-code` image includes Claude Code with +automatic credential management, plus development tools (Docker CLI, GitHub +CLI, Node.js, Go, Python 3, Git, ripgrep, jq). It runs as a non-root `agent` +user with `sudo` access and launches Claude with +`--dangerously-skip-permissions` by default. + +## Next Steps + +- [Advanced configurations](advanced-config.md) +- [Troubleshooting](troubleshooting.md) +- [CLI Reference](/reference/cli/docker/sandbox/) diff --git a/content/manuals/ai/sandboxes/get-started.md b/content/manuals/ai/sandboxes/get-started.md new file mode 100644 index 000000000000..922818a94834 --- /dev/null +++ b/content/manuals/ai/sandboxes/get-started.md @@ -0,0 +1,94 @@ +--- +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. +weight: 20 +--- + +{{< summary-bar feature_name="Docker Sandboxes" >}} + +This guide will help you run Claude Code in a sandboxed environment for the first time. + +## Prerequisites + +Before you begin, ensure you have: + +- Docker Desktop 4.50 or later +- A Claude Code subscription + +## Run a sandboxed agent + +Follow these steps to run Claude Code in a sandboxed environment: + +1. Navigate to Your Project + + ```console + $ cd ~/my-project + ``` + +2. Start Claude in a sandbox + + ```console + $ docker sandbox run claude + ``` + +3. Authenticate: on first run, Claude will prompt you to authenticate. + + Once you've authenticated, the credentials are stored in a persistent Docker + volume and reused for future sessions. + +4. Claude Code launches inside the container. + +## What just happened? + +When you ran `docker sandbox run claude`: + +- Docker created a container from a template image +- Your current directory was mounted at the same path inside the container +- Your Git name and email were injected into the container +- Your API key was stored in a Docker volume (`docker-claude-sandbox-data`) +- Claude Code started with bypass permissions enabled + +The container continues running in the background. Running `docker sandbox run +claude` again in the same directory reuses the existing container, allowing the +agent to maintain state (installed packages, temporary files) across sessions. + +## Basic commands + +Here are a few essential commands to manage your sandboxes: + +### List your sandboxes + +```console +$ docker sandbox ls +``` + +Shows all your sandboxes with their IDs, names, status, and creation time. + +### Remove a sandbox + +```console +$ docker sandbox rm +``` + +Deletes a sandbox when you're done with it. Get the sandbox ID from `docker sandbox ls`. + + +### View sandbox details + +```console +$ docker sandbox inspect +``` + +Shows detailed information about a specific sandbox in JSON format. + +For a complete list of all commands and options, see the [CLI reference](/reference/cli/docker/sandbox/). + +## Next Steps + +Now that you have Claude running in a sandboxed environment, learn more about: + +- [Authentication strategies](claude-code.md#authentication) +- [Configuration options](claude-code.md#configuration) +- [Advanced configurations](advanced-config.md) +- [Troubleshooting guide](troubleshooting.md) diff --git a/content/manuals/ai/sandboxes/troubleshooting.md b/content/manuals/ai/sandboxes/troubleshooting.md new file mode 100644 index 000000000000..a59d3d4e9882 --- /dev/null +++ b/content/manuals/ai/sandboxes/troubleshooting.md @@ -0,0 +1,121 @@ +--- +title: Troubleshooting +description: Resolve common issues when sandboxing agents locally. +weight: 50 +--- + +{{< summary-bar feature_name="Docker Sandboxes" >}} + +This guide helps you resolve common issues when sandboxing Claude Code locally. + + + +## 'sandbox' is not a docker command + + + +When you run `docker sandbox`, you see an error saying the command doesn't exist. + +This means the CLI plugin isn't installed or isn't in the correct location. To fix: + +1. Verify the plugin exists: + + ```console + $ ls -la ~/.docker/cli-plugins/docker-sandbox + ``` + + The file should exist and be executable. + +2. If using Docker Desktop, restart it to detect the plugin. + +## "Experimental Features" needs to be enabled by your administrator + +You see an error about beta features being disabled when trying to use sandboxes. + +This happens when your Docker Desktop installation is managed by an +administrator who has locked settings. If your organization uses [Settings Management](/enterprise/security/hardened-desktop/settings-management/), +ask your administrator to [allow beta features](/enterprise/security/hardened-desktop/settings-management/configure-json-file/#beta-features): + +```json +{ + "configurationFileVersion": 2, + "allowBetaFeatures": { + "locked": false, + "value": true + } +} +``` + +## Authentication failure + +Claude can't authenticate, or you see API key errors. + +The API key is likely invalid, expired, or not configured correctly. How to fix depends on your credential mode: + +If using `--credentials=sandbox` (the default): + +1. Remove the stored credentials: + + ```console + $ docker volume rm docker-claude-sandbox-data + ``` + +2. Start a new sandbox and complete the authentication workflow: + + ```console + $ docker sandbox run claude + ``` + +## Workspace contains API key configuration + +You see a warning about conflicting credentials when starting a sandbox. + +This happens when your workspace has a `.claude.json` file with a `primaryApiKey` field. Choose one of these approaches: + +- Remove the `primaryApiKey` field from your `.claude.json`: + + ```json + { + "apiKeyHelper": "/path/to/script", + "env": { + "ANTHROPIC_BASE_URL": "https://api.anthropic.com" + } + } + ``` + +- Or proceed with the warning - workspace credentials will be ignored in favor of sandbox credentials. + +## Permission denied when accessing workspace files + +Claude or commands fail with "Permission denied" errors when accessing files in the workspace. + +This usually means the workspace path isn't accessible to Docker, or file permissions are too restrictive. + +If using Docker Desktop: + +1. Check File Sharing settings at Docker Desktop → **Settings** → **Resources** → **File Sharing**. + +2. Ensure your workspace path (or a parent directory) is listed under Virtual file shares. + +3. If missing, click "+" to add the directory containing your workspace. + +4. Restart Docker Desktop. + +For all platforms, verify file permissions: + +```console +$ ls -la +``` + +Ensure files are readable. If needed: + +```console +$ chmod -R u+r +``` + +Also verify the workspace path exists: + +```console +$ cd +$ pwd +``` diff --git a/data/sandbox-cli/docker_sandbox_ls.yaml b/data/sandbox-cli/docker_sandbox_ls.yaml index e951bfabab88..60b1c1734016 100644 --- a/data/sandbox-cli/docker_sandbox_ls.yaml +++ b/data/sandbox-cli/docker_sandbox_ls.yaml @@ -9,6 +9,17 @@ usage: docker sandbox ls pname: docker sandbox plink: docker_sandbox.yaml options: + - 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 @@ -56,6 +67,24 @@ examples: |- abc123def def456ghi ``` + + ### Don't truncate output (--no-trunc) {#no-trunc} + + ```text + --no-trunc + ``` + + By default, long sandbox IDs and workspace paths are truncated for readability. Use `--no-trunc` to display the full values: + + ```console + $ docker sandbox ls + SANDBOX ID TEMPLATE NAME WORKSPACE STATUS CREATED + abc123def456 ubuntu my-project /home/user/.../my-project running 2 hours ago + + $ docker sandbox ls --no-trunc + SANDBOX ID TEMPLATE NAME WORKSPACE STATUS CREATED + abc123def456ghi789jkl ubuntu my-project /home/user/very/long/path/to/my-project running 2 hours ago + ``` deprecated: false hidden: false experimental: false diff --git a/data/sandbox-cli/docker_sandbox_run.yaml b/data/sandbox-cli/docker_sandbox_run.yaml index f32380102f98..58f67cac7d85 100644 --- a/data/sandbox-cli/docker_sandbox_run.yaml +++ b/data/sandbox-cli/docker_sandbox_run.yaml @@ -82,6 +82,7 @@ options: value_type: string description: | Container image to use for the sandbox (default: agent-specific image) + details_url: '#template' deprecated: false hidden: false experimental: false @@ -212,6 +213,21 @@ examples: |- $ docker sandbox run --credentials host claude ``` + ### Use a custom base image (-t, --template) {#template} + + ```text + --template IMAGE + ``` + + Specify a custom container image to use as the sandbox base: + + ```console + $ docker sandbox run --template python:3-alpine claude + ``` + + By default, each agent uses a pre-configured image. The `--template` option + lets you substitute a different image. + ### Name the sandbox (--name) {#name} ```text diff --git a/data/summary.yaml b/data/summary.yaml index 5e40cfe7ce4f..4069e82ec07e 100644 --- a/data/summary.yaml +++ b/data/summary.yaml @@ -186,6 +186,9 @@ Docker MCP Toolkit: availability: Beta Docker Projects: availability: Beta +Docker Sandboxes: + availability: Experimental + requires: Docker Desktop [4.50](/manuals/desktop/release-notes.md#4500) or later Docker Scout exceptions: availability: Experimental requires: Docker Scout CLI [1.15.0](/manuals/scout/release-notes/cli.md#1150) and later