docker · dvdksn · Feb 9, 2026 · Feb 9, 2026 · Feb 9, 2026 · Feb 9, 2026
@@ -11,14 +11,14 @@
 
 ## 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 @@
 
 ## 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)

@@ -17,6 +17,13 @@
 $ 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 @@
 
 ## 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 @@
 
 ### 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.
 

@@ -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

@@ -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:
 

@@ -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

@@ -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.
@@ -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 <sandbox-name>  # Reconnect later
+$ docker sandbox run <sandbox-name>  # 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,25 @@ $ 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
 
 Access the sandbox directly with an interactive shell: