docs: sync sbx v0.42.0-rc1 CLI reference

data/sbx_cli/sbx.yaml

@@ -6,6 +6,14 @@ description: |-
     Run without a command to launch interactive mode, or pass a command for CLI usage.
 usage: sbx COMMAND
 options:
+    - name: cloud
+      default_value: "false"
+      usage: |
+        Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list)
+    - name: cloud-api-url
+      default_value: https://api.sandboxes-cloud.docker.com/v1
+      usage: |
+        Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override.
     - name: debug
       shorthand: D
       default_value: "false"
@@ -15,18 +23,20 @@ options:
       default_value: "false"
       usage: help for sbx
 see_also:
+    - sbx attach - Attach to a running cloud sandbox
     - sbx completion - Generate the autocompletion script for the specified shell
     - sbx cp - Copy files or directories between a sandbox and the host
     - sbx create - Create a sandbox for an agent
     - sbx daemon - Manage sandboxd daemon
     - sbx diagnose - Diagnose common issues with your sbx installation
-    - sbx env - (Experimental) Manage sandboxes declaratively from a .sbxenv.yaml file
+    - sbx env - (Experimental) Manage sandboxes declaratively from an sbxenv.yaml file
     - sbx exec - Execute a command inside a sandbox
     - sbx kit - (Experimental) Manage kit artifacts
     - sbx login - Sign in to Docker
     - sbx logout - Stop all running sandboxes and sign out of Docker
     - sbx ls - List sandboxes
     - sbx mcp - Manage MCP servers
+    - sbx move - Move a sandbox between local and cloud
     - sbx policy - Manage sandbox policies
     - sbx ports - Manage sandbox port publishing
     - sbx prune - Remove all stopped sandboxes
@@ -35,8 +45,10 @@ see_also:
     - sbx run - Run an agent in a sandbox
     - sbx secret - Manage stored secrets
     - sbx setup - (Experimental) Detect host configuration and prepare Docker Sandboxes
-    - sbx skills - (Experimental) Manage skills shared across sandboxes
+    - sbx skills - (Experimental) Manage skills available in sandboxes
     - sbx stop - Stop one or more sandboxes without removing them
     - sbx template - Manage sandbox templates
+    - sbx ttl - Inspect or extend a cloud sandbox's TTL
     - sbx tui - Open the interactive TUI dashboard
     - sbx version - Show Docker Sandboxes version information
+    - sbx volume - Manage persistent volumes (cloud-only)

data/sbx_cli/sbx_attach.yaml

@@ -0,0 +1,40 @@
+name: sbx attach
+synopsis: Attach to a running cloud sandbox
+description: |-
+    Attach an interactive terminal session to a running cloud sandbox.
+
+    SANDBOX is the cloud sandbox ID (sbx_*) or name from "sbx --cloud ls".
+
+    Opens a PTY-backed exec session against the sandbox's agent process. The
+    sandbox must already exist and be in a running state; use `sbx --cloud run`
+    to create a sandbox and attach in one step.
+
+    Only supported with --cloud. See https://docs.docker.com/ai/sandboxes/ for the cloud sandbox model.
+usage: sbx attach SANDBOX [flags]
+options:
+    - name: detach-keys
+      usage: |
+        Override the detach gesture that leaves the agent running (Docker-style, e.g. "ctrl-\", "ctrl-x,ctrl-d"). Default: Ctrl-\. Use this when the default collides with an agent's keymap (cloud only).
+    - name: help
+      shorthand: h
+      default_value: "false"
+      usage: help for attach
+inherited_options:
+    - name: cloud
+      default_value: "false"
+      usage: |
+        Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list)
+    - name: cloud-api-url
+      default_value: https://api.sandboxes-cloud.docker.com/v1
+      usage: |
+        Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override.
+    - name: debug
+      shorthand: D
+      default_value: "false"
+      usage: Enable debug logging
+example: |4-
+      # Attach to a running sandbox by ID or name
+      sbx --cloud attach sbx_abc123
+      sbx --cloud attach claude/my-sandbox
+see_also:
+    - sbx - Manage AI coding agent sandboxes.

data/sbx_cli/sbx_completion.yaml

@@ -10,6 +10,14 @@ options:
       default_value: "false"
       usage: help for completion
 inherited_options:
+    - name: cloud
+      default_value: "false"
+      usage: |
+        Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list)
+    - name: cloud-api-url
+      default_value: https://api.sandboxes-cloud.docker.com/v1
+      usage: |
+        Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override.
     - name: debug
       shorthand: D
       default_value: "false"

data/sbx_cli/sbx_completion_bash.yaml

@@ -31,6 +31,14 @@ options:
       default_value: "false"
       usage: disable completion descriptions
 inherited_options:
+    - name: cloud
+      default_value: "false"
+      usage: |
+        Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list)
+    - name: cloud-api-url
+      default_value: https://api.sandboxes-cloud.docker.com/v1
+      usage: |
+        Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override.
     - name: debug
       shorthand: D
       default_value: "false"

data/sbx_cli/sbx_completion_fish.yaml

@@ -22,6 +22,14 @@ options:
       default_value: "false"
       usage: disable completion descriptions
 inherited_options:
+    - name: cloud
+      default_value: "false"
+      usage: |
+        Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list)
+    - name: cloud-api-url
+      default_value: https://api.sandboxes-cloud.docker.com/v1
+      usage: |
+        Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override.
     - name: debug
       shorthand: D
       default_value: "false"

data/sbx_cli/sbx_completion_powershell.yaml

@@ -19,6 +19,14 @@ options:
       default_value: "false"
       usage: disable completion descriptions
 inherited_options:
+    - name: cloud
+      default_value: "false"
+      usage: |
+        Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list)
+    - name: cloud-api-url
+      default_value: https://api.sandboxes-cloud.docker.com/v1
+      usage: |
+        Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override.
     - name: debug
       shorthand: D
       default_value: "false"

data/sbx_cli/sbx_completion_zsh.yaml

@@ -33,6 +33,14 @@ options:
       default_value: "false"
       usage: disable completion descriptions
 inherited_options:
+    - name: cloud
+      default_value: "false"
+      usage: |
+        Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list)
+    - name: cloud-api-url
+      default_value: https://api.sandboxes-cloud.docker.com/v1
+      usage: |
+        Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override.
     - name: debug
       shorthand: D
       default_value: "false"

data/sbx_cli/sbx_cp.yaml

@@ -2,7 +2,9 @@ name: sbx cp
 synopsis: Copy files or directories between a sandbox and the host
 description: |-
     Either SRC or DST must be a sandbox path, written as SANDBOX:PATH.
-    The other must be a local path. Copying between two sandboxes is not supported.
+    The other must be a local path. Copying between two sandboxes is not supported. Or — with --cloud — the cloud sandbox
+    ID (sbx_*) or name from "sbx --cloud ls". Cloud transfers go through the Docker
+    Sandboxes Cloud file API instead of the local sandboxd.
 
     When copying a directory, the directory itself is placed at the destination.
     If the destination path does not exist it is created; if it already exists
@@ -18,6 +20,14 @@ options:
       default_value: "false"
       usage: help for cp
 inherited_options:
+    - name: cloud
+      default_value: "false"
+      usage: |
+        Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list)
+    - name: cloud-api-url
+      default_value: https://api.sandboxes-cloud.docker.com/v1
+      usage: |
+        Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override.
     - name: debug
       shorthand: D
       default_value: "false"
@@ -31,5 +41,9 @@ example: |4-
 
       # Copy a directory
       sbx cp ./src/ my-sandbox:/home/user/src
+
+      # Copy to/from a cloud sandbox
+      sbx --cloud cp ./config.json sbx_abc:/workspace/config.json
+      sbx --cloud cp sbx_abc:/workspace/out.log ./
 see_also:
     - sbx - Manage AI coding agent sandboxes.

data/sbx_cli/sbx_create.yaml

@@ -3,9 +3,23 @@ synopsis: Create a sandbox for an agent
 description: |-
     Create a sandbox with access to a host workspace for an agent.
 
+    The first positional argument may be a built-in agent name or a sandbox kit
+    reference. Sandbox kit references may be local directories, ZIP files, git
+    repositories, or OCI references. Relative local references must be explicit
+    paths such as ./my-kit or ../my-kit.zip.
+
+    Omit the path to create a sandbox without a workspace bind mount: the agent
+    then works in the container's own filesystem instead of on your files.
+
     Use "sbx run --name SANDBOX" to attach to the agent after creation.
-usage: sbx create [flags] AGENT PATH [PATH...]
+
+    Without --cpus/--memory a cloud sandbox defaults to 2 CPUs and 4 GiB.
+usage: sbx create [flags] AGENT|SANDBOX_KIT [PATH...]
 options:
+    - name: allow-network
+      default_value: '[]'
+      usage: |
+        Network pattern to allow for cloud sandbox egress (cloud only; can be specified multiple times)
     - name: clone
       default_value: "false"
       usage: |
@@ -31,18 +45,37 @@ options:
       shorthand: h
       default_value: "false"
       usage: help for create
+    - name: image-ref
+      usage: |
+        OCI image reference for inline-mode cloud create (mutually exclusive with --template; requires --cpus and --memory)
     - name: kit
       default_value: '[]'
       experimental: true
       usage: |
-        Kit reference (directory, ZIP, or OCI). Can be specified multiple times
+        Additional kit reference (must be a mixin; directory, ZIP, git, or OCI). Can be specified multiple times
+    - name: kit-arg
+      default_value: '[]'
+      experimental: true
+      usage: |
+        Value for an argument the kit declares, as name=value for every kit or kit.name=value for one (can be repeated)
+    - name: kit-args-file
+      default_value: '[]'
+      experimental: true
+      usage: |
+        File of name=value kit arguments, one per line (can be repeated); --kit-arg overrides
     - name: memory
       shorthand: m
       usage: |
         Memory limit in binary units (e.g., 1024m, 8g). Default: 50% of host memory, max 32 GiB
     - name: name
       usage: |
         Name for the sandbox (defaults to <agent>-<workdir>; at least two characters, starting with a letter or number, containing only letters, numbers, hyphens and periods; 'default' is reserved)
+    - name: on-timeout
+      usage: |
+        What happens when --ttl lapses: 'delete' (default) tombstones the sandbox, or 'stop' stops it in place so it can be started again later (cloud only; 'stop' requires your account to be entitled to it).
+    - name: platform
+      usage: |
+        Target platform: linux/amd64 or linux/arm64 (cloud only). With --image-ref, omitting it lets the server resolve the platform from the image and the CLI sends the local CPU as a hint for multi-platform images. With --template, omitting it inherits the template platform.
     - name: publish
       shorthand: p
       default_value: '[]'
@@ -56,7 +89,25 @@ options:
       shorthand: t
       usage: |
         Container image to use for the sandbox (default: agent-specific image)
+    - name: ttl
+      default_value: 0s
+      usage: |
+        Cloud sandbox time-to-live before it times out (e.g. 30m, 2h; cloud only; default: server-side)
+    - name: volume
+      shorthand: v
+      default_value: '[]'
+      experimental: true
+      usage: |
+        Attach an existing persistent volume, NAME:MOUNTPATH (cloud only, experimental; repeatable)
 inherited_options:
+    - name: cloud
+      default_value: "false"
+      usage: |
+        Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list)
+    - name: cloud-api-url
+      default_value: https://api.sandboxes-cloud.docker.com/v1
+      usage: |
+        Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override.
     - name: debug
       shorthand: D
       default_value: "false"
@@ -71,17 +122,24 @@ example: |4-
       # Create with additional read-only workspaces
       sbx create claude . /path/to/docs:ro
 
+      # Create without a workspace bind mount
+      sbx create claude
+
+      # Create from a local sandbox kit
+      sbx create ../path/to/my-agent/
+
+      # Add a mixin to a built-in agent
+      sbx create claude --kit ./my-mixin/
+
       # Run the agent on an in-container clone of the host repo, wired back via a git-daemon
       sbx create --clone claude .
 see_also:
     - sbx - Manage AI coding agent sandboxes.
     - sbx create claude - Create a sandbox for claude
     - sbx create codex - Create a sandbox for codex
-    - sbx create copilot - Create a sandbox for copilot
     - sbx create cursor - Create a sandbox for cursor
+    - sbx create devin - Create a sandbox for devin
     - sbx create docker-agent - Create a sandbox for docker-agent
-    - sbx create droid - Create a sandbox for droid
     - sbx create gemini - Create a sandbox for gemini
-    - sbx create kiro - Create a sandbox for kiro
     - sbx create opencode - Create a sandbox for opencode
     - sbx create shell - Create a sandbox for shell