Merge pull request #24044 from docker/agent/issue-24043

docs: address issue #24043

Author: dvdksn

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

@@ -35,21 +35,23 @@ This starts Claude and immediately processes the prompt.
 
 ## Authentication
 
-Claude Code needs an Anthropic API key to work. The recommended approach is to
-set the `ANTHROPIC_API_KEY` environment variable in your shell configuration
-file.
+Claude Code requires an Anthropic API key. You can authenticate using an environment variable (recommended) or through interactive login.
 
-Docker Sandboxes run through a daemon process that doesn't inherit environment
+### Environment variable (recommended)
+
+The recommended approach is to set the `ANTHROPIC_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, you need to set it globally in your shell configuration file.
+sandboxes, set it globally in your shell configuration file.
 
 Add the API key to your shell configuration file:
 
 ```plaintext {title="~/.bashrc or ~/.zshrc"}
 export ANTHROPIC_API_KEY=sk-ant-api03-xxxxx
 ```
 
-Then apply the changes:
+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
@@ -60,16 +62,19 @@ $ docker sandbox create claude ~/project
 $ docker sandbox run <sandbox-name>
 ```
 
-The sandbox will detect the environment variable and use it automatically.
+The sandbox detects the environment variable and uses it automatically.
 
 ### Interactive authentication
 
-If no credentials are found, Claude Code prompts you to authenticate when it
-starts. You'll need to authenticate for each workspace separately when using
-this method.
+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.
+
+When using interactive authentication:
+
+- You'll need to authenticate for each workspace/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
 
-To avoid repeated authentication, use the `ANTHROPIC_API_KEY` environment
-variable method described above.
+To avoid repeated authentication, use the `ANTHROPIC_API_KEY` environment variable method described above.
 
 ## Configuration
 

content/manuals/ai/sandboxes/get-started.md

@@ -7,7 +7,7 @@ weight: 20
 
 {{< summary-bar feature_name="Docker Sandboxes" >}}
 
-This guide runs Claude Code in an isolated sandbox for the first time.
+This guide shows how to run Claude Code in an isolated sandbox for the first time.
 
 > [!NOTE]
 > Upgrading from an earlier version of Docker Desktop? See the
@@ -20,13 +20,13 @@ Before you begin, ensure you have:
 
 - Docker Desktop 4.58 or later
 - macOS, or Windows {{< badge color=violet text=Experimental >}}
-- A Claude API key
+- A Claude API key (can be provided via environment variable or interactively)
 
 ## Run your first sandbox
 
 Follow these steps to run Claude Code:
 
-1. Set your Anthropic API key as an environment variable.
+1. (Optional but recommended) Set your Anthropic API key as an environment variable.
 
    Add the API key to your shell configuration file:
 
@@ -39,10 +39,15 @@ Follow these steps to run Claude Code:
    in your current session will not work. You must set it globally in your
    shell configuration file to ensure the daemon can access it.
 
-   Then apply the changes:
+   Apply the changes:
    1. Source your shell configuration.
    2. Restart Docker Desktop so the daemon picks up the new environment variable.
 
+   Alternatively, you can skip this step and authenticate interactively when
+   Claude Code starts. If no credentials are found, you'll be prompted to log
+   in. Note that interactive authentication requires you to authenticate for
+   each workspace separately.
+
 2. Create and run a sandbox for Claude Code for your workspace:
 
    ```console