docs: vendor sbx v0.42.0 CLI reference

content/manuals/ai/sandboxes/release-notes.md

@@ -16,6 +16,110 @@ the full release history, including pre-releases and downloads, see the
 
 <!-- BEGIN GENERATED RELEASES -->
 
+## 0.42.0
+
+{{< release-date date="2026-09-07" >}}
+
+[GitHub release](https://github.com/docker/sbx-releases/releases/tag/v0.42.0)
+
+### Highlights
+
+- **Cloud sandboxes.** Docker Sandboxes 0.42.0 introduces `sbx --cloud` for running AI agents on Docker-managed cloud infrastructure. Use the `sbx` CLI to create and manage hosted sandboxes alongside your local sandboxes.
+
+  Cloud sandboxes have separate resources, credentials, and network policies from local sandboxes. Cloud compute requires an active Docker Agentic Platform plan and is billed based on usage. Model inference is billed separately by your model provider.
+- BREAKING: `sbx ports --publish` and kit-declared ports now default to `tcp4` instead of dual-stack `tcp`, so a published port no longer listens on `::1` unless you name the protocol explicitly (`--publish 8080:3000/tcp`); this makes `http://localhost:<port>/` reach a sandbox service that listens only on IPv4.
+- `sbx run` and `sbx create` now accept sandbox kit references as the agent positional: `sbx run <sandbox-kit-ref>`. The old form `sbx run <sandbox-kit-name> --kit <sandbox-kit-ref>` is deprecated; use the `--kit` flag for mixins.
+- Sandboxes can now be created without a workspace bind mount by omitting the path in `sbx create`. Note that this only affects the `create` command; `sbx run` still defaults to mounting the current directory as the primary workspace.
+
+### What's New
+
+#### Cloud sandboxes
+
+- Run agents in the cloud with commands such as `sbx --cloud run claude --name cloud-project`.
+- Transfer files with `sbx --cloud cp`, publish services through public HTTPS URLs, and connect using SSH.
+- Configure cloud-specific credentials and outbound network policy with `sbx --cloud secret` and `sbx --cloud policy`.
+- Use `sbx move` to copy a sandbox filesystem between local and cloud environments.
+
+#### CLI
+
+- Read-only `sbx` commands including `secret ls`, `version`, `mcp ls`, `skills ls`, `policy inspect` and the `kit` verification commands now accept `--json` for machine-readable output.
+- Clipboard commands inside local sandboxes can now copy text to the host clipboard.
+- Add, update, list, and remove sandbox skills directly from Git repositories with `sbx skills`.
+
+#### Environment files
+
+- `sbx env` now reads a non-hidden `sbxenv.yaml` in preference to `.sbxenv.yaml` when a directory holds both, and merges an `sbxenv.yaml` from your home directory beneath the project file as defaults shared across projects.
+- `sbx env` now shows a plan of everything an environment file changes on the host — host `lifecycle:` commands, credentials, bindings, MCP servers, workspaces, kits, ports and the sandbox itself — asks before applying it and asks again for every run of a command on this machine unless `env.rememberHostCommands` is set, binds the environment file read-only into the sandbox it describes, and reads a directory for `sbxenv.yaml` alone with `~/.sbxenv.yaml` as the user-level base beneath it.
+- `sbx env`: an environment file that declares no `workspace:` now creates a sandbox with no workspace bind mount instead of mounting the directory holding the file; write `workspace: .` to mount the project directory.
+- Environment files can now declare their own arguments in an `args:` block, referenced as `${{ env.args.NAME }}` and supplied with `sbx env --env-arg`; `${VAR}` interpolation in `.sbxenv.yaml` is no longer expanded.
+- Relative kit paths in an environment file now resolve against the file's directory instead of the directory `sbx` was run from.
+- `sbx env create` now shares imported skills by default and accepts display, GPU, and USB options in `sbxenv.yaml`.
+
+#### Daemon
+
+- Sandboxes now get a 10 GB Docker volume instead of 50 GB, which significantly reduces host disk usage; set `DOCKER_SANDBOXES_DOCKER_SIZE` to change it.
+
+#### Agents
+
+- Added Devin as a built-in agent.
+
+#### Kits
+
+- Kits can now declare their arguments in an `args:` block and receive values with `--kit-arg name=value`, or `--kit-arg kit.name=value` to target a single kit.
+- A `kits:` entry in sbxenv.yaml carries the arguments for that kit under `kits[].args`.
+
+#### Bug fixes
+
+- Docker Sandboxes no longer opens the setup wizard automatically; run `sbx setup` to launch it explicitly.
+- Fixed a vulnerability where a sandboxed process could get the daemon to open a host D-Bus transport and execute an arbitrary command on the host.
+- On macOS, sbx now accepts a workspace path whose casing differs from the spelling on disk instead of failing to create the sandbox.
+- Fixed a rare case where a spotty network right after your computer woke
+from sleep could cause an unexpected Docker Hub sign-out.
+- Agent crashes now identify the terminating signal and provide scoped recovery guidance.
+- Fixed a vulnerability where a malicious sandbox could hijack another sandbox's OAuth login by pre-claiming its callback port.
+- Removing or pruning a local sandbox now also deletes its sandbox-scoped secrets.
+- `sbx secret ls` no longer prints a stored secret unmasked when its value happens to match one of the status labels the listing displays.
+- `sbx` now warns when a stored credential is not sent to a sandbox because no binding authorizes it, instead of starting the sandbox and failing later with an authentication error.
+- Fixed several MCP-related bugs.
+- Standardized error message formatting for `sbx rm`, `sbx stop`, MCP authorization, and `sbx reset`.
+- Sandbox and agent not-found errors now use one sentence pattern and quote style across commands: sandbox '<name>' not found.
+- Docker Hub template pulls created through the TUI now use your Docker Sandboxes login credentials.
+- `sbx ports --publish` now automatically starts stopped local sandboxes before publishing ports.
+- Docker volume sizes below 512 MiB are now rejected before sandbox creation.
+- Creating a sandbox from a Docker Hardened Image template no longer results in a delay.
+- Fixed OAuth authentication for custom agent kits that declare resource hosts without a fallback API key.
+- Kits can now set a sandbox's CPU and memory limits through the `sandbox.resources` block in their spec.
+- Fixed SSH connections from editors by keeping non-interactive probes quiet and delivering their exit status before closing the channel.
+- Deleting a sandbox now reliably reclaims its disk volumes, and creating a new sandbox that reuses a deleted sandbox's name no longer inherits its files, Docker images, or agent session history.
+- Running `sbx setup` explicitly no longer causes the setup screen to appear again on the next interactive command.
+- Fixed sandbox connections to a server that sends data first — including passive FTP transfers and a serial console relayed to the host — failing with a timeout instead of receiving the server's output.
+- `sbx kit push` no longer uploads an empty payload layer for kits that ship no files.
+- `sbx kit push` now authenticates from the sbx credential store, so a single `sbx login` or `docker login` is enough for pushing, signing, and attaching provenance.
+- Kits using `extends:` now inherit the parent's setup commands, credentials, network allowlist, volumes, and environment variables instead of replacing them when the child declares its own.
+- Fixed Docker Hub credential refresh retrying without backoff after a rate limit, and a non-interactive login discarding the stored OAuth refresh token.
+- Nightly Homebrew installs no longer fail with checksum mismatches while a nightly publish is in flight: the sbx@nightly cask now downloads from immutable per-build release URLs.
+
+#### Other
+
+- Docker Sandboxes now provides a machine-wide Windows MSI for administrator-managed installations.
+- A declined `@requireApproval` prompt on a local MCP server now gets its own audit record, with policy attribution and a context digest, instead of leaving the original approval-required decision as the only trace of the exchange.
+- A registry mirror configured with `platform.images.registryMirror` is now also used by Docker running inside a sandbox, when the value is a bare host (no path prefix) that is not a loopback or wildcard address.
+- `sbx version --json` now reports a `server.state` of `running` or `unavailable`, so scripts can check whether the backend was reachable without parsing the error text.
+- SSH agent forwarding can be explicitly disabled and use either each client's current agent socket or a fixed socket path.
+- `sbx` terminal output now adapts colors for light terminal backgrounds and
+uses a distinct pink spinner glyph; CJK and combining-mark column widths in
+table output are now measured correctly; piped and JSON output is unchanged
+for ASCII-only content.
+- `sbx mcp add` now accepts `--skip-auth` (the old `--skip_auth` still works), and a `--url` on a private, loopback, or cloud-metadata address is resolved and registered with a warning instead of being rejected.
+- On Linux hosts without an available OS keychain, newly stored secrets are now read and written much faster; secrets already on disk keep their previous cost until they are next written.
+- Fixed a gateway defect where a remote MCP server's reconnect could silently wipe its tool routing, causing the server's tools to disappear from agents and be denied by organization MCP policy as unrecognized built-in tools until the daemon was restarted.
+- Docker Sandboxes can now upload a diagnostics bundle automatically when the daemon hits an error, after you opt in.
+- Governance resolution issues are now shown in sbx policy output and the dashboard.
+- `sbx mcp auth` now requests only the scopes you chose (or the set the resource itself requires, suppressible with the new `--no-scope` flag) instead of every scope a server advertises, explains which scopes a server refused along with a narrower retry command, and reports the scope sets of an existing grant in `sbx mcp auth status`: what was granted, what was requested, and what the server supports — with scopes sorted, duplicates collapsed, and differences such as unrequested or no-longer-advertised grants called out.
+- Sandbox listing and creation output now share one rendering package; on a terminal, `sbx ls` column headers are now styled bold.
+- Sandbox agent instruction files no longer include generic language-specific development guidance.
+- The sandboxd runtime state directory left behind by versions before v0.25.0 is now migrated to its current name instead of being used in place.
+
 ## 0.39.0
 
 {{< release-date date="2026-08-19" >}}
@@ -183,71 +287,6 @@ Run a sandbox with NVIDIA VFIO GPU passthrough on Linux using `sbx run --gpu`. E
 
 Run Claude Code against a local GGUF model with `sbx run --model <name> claude`. To use a model from an existing Ollama installation, prefix the model name with `ollama/`. See [Claude Code > Use a local model](https://docs.docker.com/ai/sandboxes/agents/claude-code/#use-a-local-model).
 
-## 0.37.1
-
-{{< release-date date="2026-07-29" >}}
-
-[GitHub release](https://github.com/docker/sbx-releases/releases/tag/v0.37.1)
-
-### Highlights
-
-This patch release stops SSH sessions from **forwarding credential environment variables into sandboxes by default**. Variables such as `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, and `GH_TOKEN` are no longer sent from the client to the sandbox unless explicitly allowed via the `ssh.acceptEnv` setting.
-
-### What's New
-
-#### Bug Fixes
-
-- SSH sessions no longer forward credential environment variables (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GH_TOKEN`, ...) from the client into the sandbox by default; use the `ssh.acceptEnv` setting to opt back in for specific variables
-
-## 0.37.0
-
-{{< release-date date="2026-07-24" >}}
-
-[GitHub release](https://github.com/docker/sbx-releases/releases/tag/v0.37.0)
-
-### Highlights
-
-**SSH access to sandboxes (experimental).** Docker Sandboxes can now be used as SSH targets. After enabling SSH access, run `sbx setup ssh` once, then connect to an existing sandbox by name with `ssh my-sandbox.sbx`. Use the connection for interactive shells, one-shot commands, and SSH-based remote development.
-
-**Shared agent skills.** Docker Sandboxes can now import skills from supported host agents into a persistent store shared across sandboxes. Run sbx skills import to import them. New sandboxes mount the store read-write by default; use --no-share-skills to opt out.
-
-### What's New
-
-#### SSH
-
-- `sbx setup ssh` adds a managed `*.sbx` entry to your SSH config, making existing sandboxes available at `<name>.sbx`.
-- SSH connections start the local Docker Sandboxes daemon and the target sandbox automatically when needed.
-- Connect using OpenSSH-compatible clients and remote-development tools such as VS Code, Cursor, Claude Desktop, and ChatGPT.
-
-#### Shared skills
-
-- `sbx skills import` discovers and imports skills from the host and makes them available to sandboxed agents. Use `--dry-run` to preview imports and `--force` to replace existing skills.
-- Imported skills persist after sandbox deletion and are mounted into new sandboxes for supported agents.
-- Pass `--no-share-skills` to `sbx run` or `sbx create` when creating a sandbox to opt out.
-
-#### CLI
-
-- `sbx create` and `sbx run` accept `-p/--publish` to publish sandbox ports at creation time.
-
-#### Networking & Policy
-
-- `DOCKER_SANDBOXES_PROXY=system` routes sandbox egress through the host operating system's proxy configuration (macOS/Windows), including any PAC auto-config URL.
-- Governance-policy denials can now display an organization-configured support message (for example, who to contact).
-
-#### Security & Audit
-
-- Audit now emits execution-outcome records for network egress (per allowed connection) and filesystem mounts (per allowed path) — success, latency, and error class — alongside the policy-attributed decision records.
-- sandboxd excludes itself from Windows Error Reporting so daemon crash dumps cannot capture in-memory credentials.
-
-#### Performance
-
-- `sbx secret ls` and sandbox startup are faster on Linux hosts without an OS keychain — stored secrets are no longer all decrypted just to list or resolve credentials.
-
-### Bug Fixes
-
-- Fixed sandboxd failing to start on Linux hosts without an OS keychain, where the on-disk secret store's key derivation could peg a CPU during startup and the CLI would kill the still-starting daemon.
-- Fixed an intermittent "failed to fully delete sandbox" error when removing a running sandbox, caused by a network-teardown race with the engine's endpoint cleanup.
-
 <!-- END GENERATED RELEASES -->
 
 ## Earlier releases

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
+      usage: |
+        Cloud Sandboxes API base URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com). Set DOCKER_CLOUD_API_URL or pass this flag to override; a legacy value ending in /v1 is accepted.
     - name: debug
       shorthand: D
       default_value: "false"
@@ -15,12 +23,13 @@ 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
@@ -35,8 +44,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
+      usage: |
+        Cloud Sandboxes API base URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com). Set DOCKER_CLOUD_API_URL or pass this flag to override; a legacy value ending in /v1 is accepted.
+    - 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
+      usage: |
+        Cloud Sandboxes API base URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com). Set DOCKER_CLOUD_API_URL or pass this flag to override; a legacy value ending in /v1 is accepted.
     - 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
+      usage: |
+        Cloud Sandboxes API base URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com). Set DOCKER_CLOUD_API_URL or pass this flag to override; a legacy value ending in /v1 is accepted.
     - name: debug
       shorthand: D
       default_value: "false"