Merge pull request #24102 from dvdksn/sandboxes-461

sandboxes v0.12.0

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: <agent>-<workdir>, 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: <agent>-<workdir>, 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:

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:

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:

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:

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:

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:

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:

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
+

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
+

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

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

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.

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
-      value_type: bool
-      default_value: "false"
-      description: Load a locally built template image into the sandbox
+    - option: name
+      value_type: string
+      description: 'Name for the sandbox (default: <agent>-<workdir>)'
+      details_url: '#name'
       deprecated: false
       hidden: false
       experimental: false
       experimentalcli: false
       kubernetes: false
       swarm: false
-    - option: name
+    - option: patch-settings
+      value_type: bool
+      default_value: "false"
+      description: Intercept claude settings API call and patch payload
+      deprecated: false
+      hidden: true
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
+    - option: pull-template
       value_type: string
-      description: 'Name for the sandbox (default: <agent>-<workdir>)'
-      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

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