From db88a4ec1c36d90ddcbbfa3850fe59f342211506 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Thu, 12 Feb 2026 13:06:16 +0100 Subject: [PATCH 01/12] sandboxes: vendor v0.12.0 cli reference Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> --- .../cli/docker/sandbox/create/opencode.md | 6 ++ .../cli/docker/sandbox/create/shell.md | 6 ++ data/sandbox-cli/docker_sandbox_create.yaml | 27 ++++----- .../docker_sandbox_create_cagent.yaml | 3 +- .../docker_sandbox_create_claude.yaml | 3 +- .../docker_sandbox_create_codex.yaml | 3 +- .../docker_sandbox_create_copilot.yaml | 3 +- .../docker_sandbox_create_gemini.yaml | 3 +- .../docker_sandbox_create_kiro.yaml | 3 +- .../docker_sandbox_create_opencode.yaml | 60 +++++++++++++++++++ .../docker_sandbox_create_shell.yaml | 41 +++++++++++++ data/sandbox-cli/docker_sandbox_ls.yaml | 29 --------- .../docker_sandbox_network_proxy.yaml | 13 ++-- data/sandbox-cli/docker_sandbox_reset.yaml | 2 + data/sandbox-cli/docker_sandbox_run.yaml | 50 +++++++++++----- data/sandbox-cli/docker_sandbox_save.yaml | 7 +++ 16 files changed, 186 insertions(+), 73 deletions(-) create mode 100644 content/reference/cli/docker/sandbox/create/opencode.md create mode 100644 content/reference/cli/docker/sandbox/create/shell.md create mode 100644 data/sandbox-cli/docker_sandbox_create_opencode.yaml create mode 100644 data/sandbox-cli/docker_sandbox_create_shell.yaml 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 From 5b6c2e8401b750e269ede56336459e074377a754 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 02/12] sandboxes: update workspace and naming/behavior Update workspace defaults/behavior and automatic sandbox naming. --- content/manuals/ai/sandboxes/_index.md | 3 +- content/manuals/ai/sandboxes/agents.md | 7 +--- content/manuals/ai/sandboxes/claude-code.md | 17 +++++++-- content/manuals/ai/sandboxes/get-started.md | 21 +++++++++--- content/manuals/ai/sandboxes/templates.md | 14 ++++---- content/manuals/ai/sandboxes/workflows.md | 38 ++++++++++++++++++--- 6 files changed, 74 insertions(+), 26 deletions(-) diff --git a/content/manuals/ai/sandboxes/_index.md b/content/manuals/ai/sandboxes/_index.md index 161b89291389..3862b130a842 100644 --- a/content/manuals/ai/sandboxes/_index.md +++ b/content/manuals/ai/sandboxes/_index.md @@ -45,7 +45,8 @@ 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 claude ``` This command creates a sandbox for your workspace (`~/my-project`) and starts diff --git a/content/manuals/ai/sandboxes/agents.md b/content/manuals/ai/sandboxes/agents.md index 8c9d60a77d16..d6c81a0aca69 100644 --- a/content/manuals/ai/sandboxes/agents.md +++ b/content/manuals/ai/sandboxes/agents.md @@ -36,12 +36,7 @@ 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] ``` Each agent runs in its own isolated sandbox. The agent type is bound to the diff --git a/content/manuals/ai/sandboxes/claude-code.md b/content/manuals/ai/sandboxes/claude-code.md index 945dc700c888..13fd375ccfa6 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 89c499bc4653..dd0d9830cdb1 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 @@ -51,10 +51,20 @@ 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 + ``` 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 @@ -120,7 +131,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 diff --git a/content/manuals/ai/sandboxes/templates.md b/content/manuals/ai/sandboxes/templates.md index 60cc476c5a31..ad4ec4c9a81c 100644 --- a/content/manuals/ai/sandboxes/templates.md +++ b/content/manuals/ai/sandboxes/templates.md @@ -68,7 +68,7 @@ $ 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 --load-local-template -t my-template:v1 claude [PATH] ``` The `--load-local-template` flag tells the sandbox to use an image from your @@ -79,7 +79,7 @@ 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`. @@ -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. @@ -157,8 +157,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,7 +187,7 @@ $ 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 diff --git a/content/manuals/ai/sandboxes/workflows.md b/content/manuals/ai/sandboxes/workflows.md index 63888784aad4..740a873b95f4 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 # Creates sandbox named "dev" +$ docker sandbox run --name dev claude # 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 91007e0a9a66415514e0323398962aa76b115c9c 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 03/12] 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 319657874138..72b6561888a7 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 740a873b95f4..a1a7173d6966 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 bb37fe07984f55957bdf5ba45d9ef1d40b87b964 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 04/12] 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 bc7aae314beb..ee30c4ce2728 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 d9ce29de6b016fc040c209db9660a1b3e150fd39 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 05/12] 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 d6c81a0aca69..8abf23bea5b7 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 @@ -44,7 +44,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) From 8b0aa158e68390e84c8173e830c589619cceda19 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Thu, 12 Feb 2026 12:23:51 +0000 Subject: [PATCH 06/12] sandboxes: document multiple workspaces with read-only mounts Add documentation for mounting multiple workspaces to a single sandbox, with support for read-only mounts --- content/manuals/ai/sandboxes/get-started.md | 6 ++ content/manuals/ai/sandboxes/workflows.md | 99 +++++++++++++++++---- 2 files changed, 86 insertions(+), 19 deletions(-) diff --git a/content/manuals/ai/sandboxes/get-started.md b/content/manuals/ai/sandboxes/get-started.md index dd0d9830cdb1..7a4d1277675f 100644 --- a/content/manuals/ai/sandboxes/get-started.md +++ b/content/manuals/ai/sandboxes/get-started.md @@ -66,6 +66,12 @@ Follow these steps to run Claude Code: $ 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. diff --git a/content/manuals/ai/sandboxes/workflows.md b/content/manuals/ai/sandboxes/workflows.md index a1a7173d6966..dce001845b88 100644 --- a/content/manuals/ai/sandboxes/workflows.md +++ b/content/manuals/ai/sandboxes/workflows.md @@ -142,6 +142,25 @@ 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 claude ~/project-b +$ docker sandbox create claude ~/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 Docker automatically generates sandbox names based on the agent and workspace @@ -163,6 +182,67 @@ $ docker sandbox run dev Each maintains separate packages, Docker images, and state, but share the workspace files. +## Multiple workspaces + +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 run claude ~/my-project ~/shared-docs +``` + +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 +$ docker sandbox run claude . /path/to/docs:ro /path/to/lib:readonly +``` + +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 claude ./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 +``` + +Each sandbox runs in isolation with separate configurations while sharing the +same workspace files. + ## Resetting state If you encounter issues with sandbox state, use the reset command to clean up @@ -204,25 +284,6 @@ List all sandboxes: $ docker sandbox ls ``` -## Managing multiple projects - -Create sandboxes for different projects: - -```console -$ docker sandbox create claude ~/project-a -$ docker sandbox create claude ~/project-b -$ docker sandbox create claude ~/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 -``` - ## Next steps - [Custom templates](templates.md) From 9313580df238fb960e832ae2ae0909fbc797e83e Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Thu, 12 Feb 2026 12:24:49 +0000 Subject: [PATCH 07/12] sandboxes: add opencode and shell to supported agents --- content/manuals/ai/sandboxes/_index.md | 2 ++ content/manuals/ai/sandboxes/agents.md | 20 +++++++++++--------- 2 files changed, 13 insertions(+), 9 deletions(-) diff --git a/content/manuals/ai/sandboxes/_index.md b/content/manuals/ai/sandboxes/_index.md index 3862b130a842..92521deb3961 100644 --- a/content/manuals/ai/sandboxes/_index.md +++ b/content/manuals/ai/sandboxes/_index.md @@ -86,6 +86,8 @@ that workspace. Docker Sandboxes works with multiple AI coding agents: - **Claude Code** - Anthropic's coding agent +- **OpenCode** - Multi-provider agent with AGENTS.md support +- **Shell** - Minimal sandbox for manual agent installation - **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) diff --git a/content/manuals/ai/sandboxes/agents.md b/content/manuals/ai/sandboxes/agents.md index 8abf23bea5b7..d2a77cb55750 100644 --- a/content/manuals/ai/sandboxes/agents.md +++ b/content/manuals/ai/sandboxes/agents.md @@ -11,14 +11,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 | +| Shell | `shell` | Experimental | Minimal environment for manual setup | ## Experimental status @@ -36,7 +38,7 @@ Use sandboxes for development and testing, not production workloads. The agent type is specified when creating a sandbox: ```console -$ docker sandbox create AGENT [PATH] +$ docker sandbox create AGENT [PATH] [PATH...] ``` Each agent runs in its own isolated sandbox. The agent type is bound to the From 57910d98a707ee6a3eedac8fe860fb4f492d02a9 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Thu, 12 Feb 2026 12:25:58 +0000 Subject: [PATCH 08/12] sandboxes: document --pull-template flag and image caching Replace deprecated --load-local-template flag with new --pull-template --- content/manuals/ai/sandboxes/migration.md | 15 ++++++--- content/manuals/ai/sandboxes/templates.md | 38 +++++++++++++++++++---- 2 files changed, 42 insertions(+), 11 deletions(-) diff --git a/content/manuals/ai/sandboxes/migration.md b/content/manuals/ai/sandboxes/migration.md index d46937f04fe3..9c2781ddbce6 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 diff --git a/content/manuals/ai/sandboxes/templates.md b/content/manuals/ai/sandboxes/templates.md index ad4ec4c9a81c..fd35ad3eb143 100644 --- a/content/manuals/ai/sandboxes/templates.md +++ b/content/manuals/ai/sandboxes/templates.md @@ -68,11 +68,11 @@ $ 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 [PATH] +$ 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: @@ -82,7 +82,33 @@ $ docker push myorg/my-template:v1 $ 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 @@ -104,11 +130,11 @@ $ 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): From 88d39af5198a49be92d11d4fd20338d87ebd2b9e Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Thu, 12 Feb 2026 12:26:51 +0000 Subject: [PATCH 09/12] sandboxes: update network logging docs --- .../manuals/ai/sandboxes/network-policies.md | 38 ++++++++++++++++++- 1 file changed, 37 insertions(+), 1 deletion(-) diff --git a/content/manuals/ai/sandboxes/network-policies.md b/content/manuals/ai/sandboxes/network-policies.md index ee30c4ce2728..901ab6896dad 100644 --- a/content/manuals/ai/sandboxes/network-policies.md +++ b/content/manuals/ai/sandboxes/network-policies.md @@ -95,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 From 602c71e1bcf9985b1fde26ef0f83bd3d94009877 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Fri, 13 Feb 2026 15:12:04 +0100 Subject: [PATCH 10/12] sandboxes: add agent-specific documentation Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> --- _vale/config/vocabularies/Docker/accept.txt | 3 + content/manuals/ai/sandboxes/_index.md | 26 ++-- .../sandboxes/{agents.md => agents/_index.md} | 31 +++-- content/manuals/ai/sandboxes/agents/cagent.md | 109 +++++++++++++++ .../ai/sandboxes/{ => agents}/claude-code.md | 39 ++---- content/manuals/ai/sandboxes/agents/codex.md | 105 ++++++++++++++ .../manuals/ai/sandboxes/agents/copilot.md | 114 +++++++++++++++ content/manuals/ai/sandboxes/agents/gemini.md | 130 ++++++++++++++++++ content/manuals/ai/sandboxes/agents/kiro.md | 107 ++++++++++++++ .../manuals/ai/sandboxes/agents/opencode.md | 116 ++++++++++++++++ content/manuals/ai/sandboxes/agents/shell.md | 126 +++++++++++++++++ content/manuals/ai/sandboxes/get-started.md | 13 +- content/manuals/ai/sandboxes/migration.md | 4 +- .../manuals/ai/sandboxes/troubleshooting.md | 2 +- content/manuals/ai/sandboxes/workflows.md | 37 +++-- 15 files changed, 889 insertions(+), 73 deletions(-) rename content/manuals/ai/sandboxes/{agents.md => agents/_index.md} (74%) create mode 100644 content/manuals/ai/sandboxes/agents/cagent.md rename content/manuals/ai/sandboxes/{ => agents}/claude-code.md (68%) create mode 100644 content/manuals/ai/sandboxes/agents/codex.md create mode 100644 content/manuals/ai/sandboxes/agents/copilot.md create mode 100644 content/manuals/ai/sandboxes/agents/gemini.md create mode 100644 content/manuals/ai/sandboxes/agents/kiro.md create mode 100644 content/manuals/ai/sandboxes/agents/opencode.md create mode 100644 content/manuals/ai/sandboxes/agents/shell.md 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 92521deb3961..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 @@ -46,12 +46,12 @@ To create and run a sandbox: ```console $ cd ~/my-project -$ docker sandbox run claude +$ 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 @@ -85,14 +85,16 @@ that workspace. Docker Sandboxes works with multiple AI coding agents: -- **Claude Code** - Anthropic's coding agent -- **OpenCode** - Multi-provider agent with AGENTS.md support +- **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 -- **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) + +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 74% rename from content/manuals/ai/sandboxes/agents.md rename to content/manuals/ai/sandboxes/agents/_index.md index d2a77cb55750..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 --- @@ -20,7 +21,7 @@ inside microVMs with private Docker daemons. | cagent | `cagent` | Experimental | In development | | Kiro | `kiro` | Experimental | In development | | OpenCode | `opencode` | Experimental | In development | -| Shell | `shell` | Experimental | Minimal environment for manual setup | +| Custom shell | `shell` | Experimental | Minimal environment for manual setup | ## Experimental status @@ -44,6 +45,19 @@ $ 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 Each agent has its own credential requirements and authentication flow. @@ -52,7 +66,14 @@ 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 68% rename from content/manuals/ai/sandboxes/claude-code.md rename to content/manuals/ai/sandboxes/agents/claude-code.md index 13fd375ccfa6..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: @@ -42,8 +47,7 @@ This starts Claude and immediately processes the prompt. ## Authentication -Claude Code requires an Anthropic API key. Credentials are scoped per sandbox -and must be provided through environment variables or interactive login. +Claude Code requires an Anthropic API key. Credentials are scoped per sandbox. ### Environment variable (recommended) @@ -85,7 +89,7 @@ When using interactive authentication: - 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 @@ -104,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/get-started.md b/content/manuals/ai/sandboxes/get-started.md index 7a4d1277675f..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 @@ -24,7 +26,7 @@ Before you begin, ensure you have: ## 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. @@ -148,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 9c2781ddbce6..68d4ceea3c1e 100644 --- a/content/manuals/ai/sandboxes/migration.md +++ b/content/manuals/ai/sandboxes/migration.md @@ -194,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/troubleshooting.md b/content/manuals/ai/sandboxes/troubleshooting.md index 72b6561888a7..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. diff --git a/content/manuals/ai/sandboxes/workflows.md b/content/manuals/ai/sandboxes/workflows.md index dce001845b88..4df3b8f398de 100644 --- a/content/manuals/ai/sandboxes/workflows.md +++ b/content/manuals/ai/sandboxes/workflows.md @@ -15,22 +15,21 @@ Create a sandbox for your project: ```console $ cd ~/my-project -$ docker sandbox run claude +$ docker sandbox run AGENT ``` -The workspace defaults to your current directory when omitted. You can also -specify an explicit path: +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 claude ~/my-project +$ 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 claude ~/my-project # Creates sandbox -$ docker sandbox run claude ~/my-project # Reuses same sandbox +$ 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 @@ -45,8 +44,8 @@ When using the `--name` flag, the behavior is also idempotent based on the name: ```console -$ docker sandbox run --name dev claude # Creates sandbox named "dev" -$ docker sandbox run --name dev claude # Reuses sandbox "dev" +$ docker sandbox run --name dev AGENT # Creates sandbox named "dev" +$ docker sandbox run --name dev AGENT # Reuses sandbox "dev" ``` ## Installing dependencies @@ -55,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. @@ -77,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 ``` @@ -90,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 @@ -148,8 +147,8 @@ Create sandboxes for different projects: ```console $ docker sandbox create claude ~/project-a -$ docker sandbox create claude ~/project-b -$ docker sandbox create claude ~/work/client-project +$ docker sandbox create codex ~/project-b +$ docker sandbox create copilot ~/work/client-project ``` Each sandbox is completely isolated. Switch between them by running the @@ -168,14 +167,14 @@ 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 ``` @@ -188,7 +187,7 @@ 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 run claude ~/my-project ~/shared-docs +$ docker sandbox run AGENT ~/my-project ~/shared-docs ``` The primary workspace (first argument) is always mounted read-write. Additional @@ -199,7 +198,7 @@ workspaces are mounted read-write by default. Mount additional workspaces as read-only by appending `:ro` or `:readonly`: ```console -$ docker sandbox run claude . /path/to/docs:ro /path/to/lib:readonly +$ docker sandbox run AGENT . /path/to/docs:ro /path/to/lib:readonly ``` The primary workspace remains fully writable while read-only workspaces are @@ -214,7 +213,7 @@ Example: ```console $ cd /Users/bob/projects -$ docker sandbox run claude ./app ~/docs:ro +$ docker sandbox run AGENT ./app ~/docs:ro ``` Inside the sandbox: From d97f161de177f3900150aa12783351b95fe1a34d Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Fri, 13 Feb 2026 15:12:22 +0100 Subject: [PATCH 11/12] sandboxes: explain proxy credential injection Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> --- content/manuals/ai/sandboxes/architecture.md | 23 ++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/content/manuals/ai/sandboxes/architecture.md b/content/manuals/ai/sandboxes/architecture.md index a6453edc29f7..890178f43eef 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 From c75e3d647837ef7064ab7a29cb4f4eb51086a71a Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Fri, 13 Feb 2026 15:37:50 +0100 Subject: [PATCH 12/12] sandboxes(chore): clean up "next steps" sections Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> --- content/manuals/ai/sandboxes/architecture.md | 6 ------ content/manuals/ai/sandboxes/network-policies.md | 6 ------ content/manuals/ai/sandboxes/templates.md | 6 ------ content/manuals/ai/sandboxes/workflows.md | 6 ------ 4 files changed, 24 deletions(-) diff --git a/content/manuals/ai/sandboxes/architecture.md b/content/manuals/ai/sandboxes/architecture.md index 890178f43eef..12816511ae72 100644 --- a/content/manuals/ai/sandboxes/architecture.md +++ b/content/manuals/ai/sandboxes/architecture.md @@ -223,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/network-policies.md b/content/manuals/ai/sandboxes/network-policies.md index 901ab6896dad..5424aba0f63a 100644 --- a/content/manuals/ai/sandboxes/network-policies.md +++ b/content/manuals/ai/sandboxes/network-policies.md @@ -385,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 fd35ad3eb143..79ac29cc179b 100644 --- a/content/manuals/ai/sandboxes/templates.md +++ b/content/manuals/ai/sandboxes/templates.md @@ -218,9 +218,3 @@ $ 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/workflows.md b/content/manuals/ai/sandboxes/workflows.md index 4df3b8f398de..c4a27d440d7b 100644 --- a/content/manuals/ai/sandboxes/workflows.md +++ b/content/manuals/ai/sandboxes/workflows.md @@ -282,9 +282,3 @@ List all sandboxes: ```console $ docker sandbox ls ``` - -## Next steps - -- [Custom templates](templates.md) -- [Architecture](architecture.md) -- [Network policies](network-policies.md)