From a78df76d4a538b25aa682963f089a7c38df1e666 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Mon, 9 Feb 2026 13:02:12 +0000 Subject: [PATCH 1/4] sandboxes: update workspace and naming/behavior Update workspace defaults/behavior and automatic sandbox naming. --- content/manuals/ai/sandboxes/claude-code.md | 17 +++++++-- content/manuals/ai/sandboxes/get-started.md | 17 +++++++-- content/manuals/ai/sandboxes/templates.md | 6 ++-- content/manuals/ai/sandboxes/workflows.md | 38 ++++++++++++++++++--- 4 files changed, 65 insertions(+), 13 deletions(-) diff --git a/content/manuals/ai/sandboxes/claude-code.md b/content/manuals/ai/sandboxes/claude-code.md index 945dc700c88..13fd375ccfa 100644 --- a/content/manuals/ai/sandboxes/claude-code.md +++ b/content/manuals/ai/sandboxes/claude-code.md @@ -17,6 +17,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 +42,8 @@ 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 +and must be provided through environment variables or interactive login. ### Environment variable (recommended) @@ -66,13 +74,16 @@ 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. diff --git a/content/manuals/ai/sandboxes/get-started.md b/content/manuals/ai/sandboxes/get-started.md index 89c499bc465..9926b401c42 100644 --- a/content/manuals/ai/sandboxes/get-started.md +++ b/content/manuals/ai/sandboxes/get-started.md @@ -19,7 +19,7 @@ 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 @@ -54,7 +54,17 @@ Follow these steps to run Claude Code: $ docker sandbox run claude ~/my-project ``` - 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 (for example, `claude-my-project`). 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 + ``` 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 +96,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 diff --git a/content/manuals/ai/sandboxes/templates.md b/content/manuals/ai/sandboxes/templates.md index 60cc476c5a3..53b64442b0b 100644 --- a/content/manuals/ai/sandboxes/templates.md +++ b/content/manuals/ai/sandboxes/templates.md @@ -100,7 +100,7 @@ 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 ``` @@ -114,7 +114,7 @@ $ docker sandbox run --load-local-template -t my-template:v1 claude ~/other-proj 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. @@ -158,7 +158,7 @@ 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 +✓ Created sandbox claude-project $ docker sandbox run claude-project agent binary "claude" not found in sandbox: verify this is the correct sandbox type diff --git a/content/manuals/ai/sandboxes/workflows.md b/content/manuals/ai/sandboxes/workflows.md index 63888784aad..fe156b1044c 100644 --- a/content/manuals/ai/sandboxes/workflows.md +++ b/content/manuals/ai/sandboxes/workflows.md @@ -15,14 +15,38 @@ Create a sandbox for your project: ```console $ cd ~/my-project -$ docker sandbox run claude . +$ docker sandbox run claude ``` -The sandbox persists. Stop and restart it without losing installed packages or +The workspace defaults to your current directory when omitted. You can also +specify an explicit path: + +```console +$ docker sandbox run claude ~/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 claude ~/my-project # Creates sandbox +$ docker sandbox run claude ~/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 claude ~/project # Creates sandbox named "dev" +$ docker sandbox run --name dev claude ~/project # Reuses sandbox "dev" ``` ## Installing dependencies @@ -92,6 +116,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. @@ -117,7 +144,9 @@ warn when opening new workspaces for similar reasons. ## 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 @@ -134,6 +163,7 @@ $ docker sandbox run dev Each maintains separate packages, Docker images, and state, but share the workspace files. + ## Debugging Access the sandbox directly with an interactive shell: From ad7b6ae6bf130384c363a390067e352a10bc7012 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Mon, 9 Feb 2026 13:10:05 +0000 Subject: [PATCH 2/4] sandboxes: document reset command --- .../manuals/ai/sandboxes/troubleshooting.md | 14 ++++++++++++++ content/manuals/ai/sandboxes/workflows.md | 18 ++++++++++++++++++ 2 files changed, 32 insertions(+) diff --git a/content/manuals/ai/sandboxes/troubleshooting.md b/content/manuals/ai/sandboxes/troubleshooting.md index 31965787413..72b6561888a 100644 --- a/content/manuals/ai/sandboxes/troubleshooting.md +++ b/content/manuals/ai/sandboxes/troubleshooting.md @@ -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 fe156b1044c..51a6429bd58 100644 --- a/content/manuals/ai/sandboxes/workflows.md +++ b/content/manuals/ai/sandboxes/workflows.md @@ -163,6 +163,24 @@ $ docker sandbox run dev Each maintains separate packages, Docker images, and state, but share the workspace files. +## Resetting state + +If you encounter issues with sandbox state, use the reset command to clean up +all VMs and registries: + +```console +$ docker sandbox reset +``` + +This command: + +- 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 From b9d77fe2dda55d5d92e833a382410f575b824430 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Mon, 9 Feb 2026 13:10:57 +0000 Subject: [PATCH 3/4] sandboxes: document default network policy Add canonical reference section for default network policy configuration, including policy mode, blocked CIDRs, and allowed hosts. --- .../manuals/ai/sandboxes/network-policies.md | 41 +++++++++++++------ 1 file changed, 29 insertions(+), 12 deletions(-) diff --git a/content/manuals/ai/sandboxes/network-policies.md b/content/manuals/ai/sandboxes/network-policies.md index bc7aae314be..ee30c4ce272 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: @@ -100,16 +126,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 +335,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: From 50e295732da9803940007d357f14d0aa59d4d064 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Mon, 9 Feb 2026 13:11:51 +0000 Subject: [PATCH 4/4] sandboxes: clarify credential scoping Document that credentials are scoped per agent with no fallback authentication methods. --- content/manuals/ai/sandboxes/agents.md | 21 ++++++++++++--------- 1 file changed, 12 insertions(+), 9 deletions(-) diff --git a/content/manuals/ai/sandboxes/agents.md b/content/manuals/ai/sandboxes/agents.md index 8c9d60a77d1..c8c61c92bfe 100644 --- a/content/manuals/ai/sandboxes/agents.md +++ b/content/manuals/ai/sandboxes/agents.md @@ -11,14 +11,14 @@ 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 | ## Experimental status @@ -49,7 +49,10 @@ sandbox when created and cannot be changed later. ## 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)