docker/sbx-releases v0.48.0 on GitHub

Highlights

Docker Sandboxes v0.48.0 updates the CLI across all commands, with consistent terminal output and JSON/YAML formats. This changes flags, structured output, and prompts used by existing scripts. Review the migration details below before upgrading automated workflows.

The release also adds managed Codex and Claude Desktop SSH targets on macOS and Windows, additional v3 kit capabilities, and support for adding kits with startup commands to existing sandboxes.

Breaking changes

CLI flags, output, and automation

The CLI refactor changes both interactive use and scripting interfaces. Existing --json parsers may need updates even if their command lines still work. Scripts that parse human-readable output must switch to --format json or --format yaml.

Update command flags

Command	Previous spelling	Replacement or behavior
`sbx run`, `sbx env run`	`--detached`	Use `--detach` or `-d`. `--detached` is rejected.
`sbx logout`	`--yes`, `-y`	Use `--force` or `-f`.
`sbx env plan`, `sbx env create`, `sbx env run`	`--auto-approve`, `-y`	Use `--force` or `-f`.
`sbx create`	`--quiet`, `-q`	Use `--no-progress`. This suppresses progress, but still prints the creation summary.
`sbx template save`	`-d` for the description	Use `--description`.
`sbx diagnose`	`--output`, `-o`	Use `--format table`, `--format json`, `--format yaml`, or `--format github-issue`.
`sbx secret ls`, `sbx secret rm`	`--env`	Use `--env-name`.
`sbx policy log`	`--quiet`, `-q`	Removed; there is no replacement.

--format, --json, and -q are mutually exclusive on commands that use the shared output flags. Even --json --format json is rejected. Unsupported format values fail during flag parsing instead of falling back to human-readable output.

sbx settings ls is the primary spelling; sbx settings list remains an alias. sbx kit builder history rm keeps --yes / -y because its --force flag is forwarded to Buildx. The deprecated --global and mcp add --skip_auth flags remain accepted but hidden, with a deprecation warning on stderr; use --skip-auth instead of --skip_auth.

Update structured-output parsers

--json is an alias of --format json and emits the same document. JSON output structures have changed for the commands listed in the following table. Output uses snake_case field names; YAML is derived from the same representation.

Command	Output change
`sbx ls`	Returns the sandbox array directly instead of `{"sandboxes": [...]}`. Fields use `snake_case`, `created_at` and `last_used_at` use RFC 3339 timestamps, and rows include `detached`.
`sbx template ls`	Returns the image array directly instead of `{"images": [...]}`, for local and cloud sandboxes.
`sbx mcp ls` locally	Returns the server array directly instead of `{"gateway": {...}, "servers": [...]}`. Each server row carries `gateway`.
`sbx policy log`	Local and cloud output use `{updated_at, allowed: [...], blocked: [...]}`. Entries contain `sandbox_id`, `host`, `proxy_type`, `rule`, `reason`, `count`, `first_seen`, and `last_seen`. `--limit` applies. This replaces local `allowed_hosts` / `blocked_hosts` and the cloud camelCase document.
`sbx --cloud policy ls`	Field names change from camelCase to `snake_case`.
`sbx ports`	Cloud rows use `sandbox_port` instead of `port`, alongside `url`. Local rows use `host_ip`, `host_port`, `sandbox_port`, and `protocol`.
`sbx ports --publish` / `--unpublish` locally	Structured formats emit result rows with `action: published` or `action: unpublished` instead of human-readable lines. Warnings go to stderr.
Cloud `volume create`, `volume ls`, and `volume inspect`	Fields such as `ID`, `Name`, and `CreatedAt` become `id`, `name`, and `created_at`. `volume inspect` defaults to a human-readable details view; request `--format json` for JSON.
`sbx rm`, `sbx stop`, `sbx template rm`, `sbx volume rm`	Structured formats return an array of results with `action`, `resource`, `name`, and optional `id` and `error`. Actions are lowercase: `removed`, `stopped`, `removing`, `stopping`, or `failed`. Missing and failed targets are included.

For example, a script that extracts sandbox names from sbx ls --json must change its filter from .sandboxes[].name to .[].name.

Local and cloud output follow the same conventions. MCP list output still represents different resources: local registrations versus server usage across cloud sandboxes, so those rows differ beyond their shared name and type fields.

sbx prune --dry-run accepts --format json and --format yaml. Cloud ttl --format yaml emits YAML instead of JSON, and sbx diagnose supports YAML. sbx events --json remains an NDJSON stream, and sbx mcp auth --format text|json retains its command-specific formats.

Update non-interactive workflows

Confirmation prompts require terminal input. Piping an answer, such as echo y | sbx secret set …, no longer confirms the operation. Use --force / -f where the command provides it. Commands that require confirmation fail with exit status 1 when stdin is not a terminal.
Declining a confirmation returns a non-zero exit status consistently, including for removal, reset, and prune operations.
Read-only invocations and runs with --force do not start an interactive sign-in flow. Sign in before running automation that requires authentication. Read-only examples include ports SANDBOX, ttl SANDBOX, prune --dry-run, and diagnose; their modifying or upload variants are not read-only.
Without a terminal, sbx diagnose --upload saves the diagnostic bundle but skips uploading it and exits with status 0. A successful exit does not mean that an upload occurred.
Without a terminal, sbx create and sbx run fail if the workspace directory does not exist and print a mkdir -p hint. Create the directory before invoking the command.
Ctrl-D at a selection or free-text prompt cancels instead of accepting the default. Enter still accepts the default.

Terminal output and streams

Human-readable output changes across all commands: headings, status marks, indentation, progress, and result messages use a consistent format. sbx ls includes state marks and a creation-time column; sbx ls and sbx inspect identify detached sandboxes.

Results go to stdout. Errors, warnings, corrective hints, daemon-start progress, image pulls, and kit-build progress go to stderr. Update scripts that depend on exact message text or capture only one stream.

What's new

Security

Fixed sign-in enforcement ignoring allowedOrgs on macOS.
sbx cp blocks local paths that escape a sandbox workspace through symbolic links.
Cloud sbx cp downloads and sbx kit pack preserve restrictive destination permissions without temporarily exposing the replacement file. They account for permissions at completion and do not widen them. On Unix, cloud sbx cp refuses to replace files owned by another user; on Windows, permission preservation covers the read-only attribute. Special permission bits are retained where the kernel permits. This cloud-copy change does not affect local sbx cp.
sbx kit add checks the filesystem mount policy before recreating a sandbox and refuses the operation if its workspace or a saved mount is denied, matching sbx start.
Fixed the daemon crashing on a malformed request sent through an intercepted HTTPS connection.

SSH and desktop integration

On macOS and Windows, sbx setup ssh --auto-create registers Docker Sandbox connections in Codex and Claude Desktop. Each connection creates a dedicated sandbox on first use and reuses it on subsequent connections. These sandboxes have no host workspace mounted. Clone or copy your project into the sandbox to work on it.
Desktop SSH setup warns about missing authentication and provides local sign-in guidance for Codex and Claude. Repeating sbx setup ssh recognizes existing registrations even while the applications are running.
Closing a Cursor or VS Code window connected over SSH no longer stops the daemon and other running sandboxes.
SSH connections no longer fail because the CLI's initial feature lookup timed out before starting the daemon.
SSH-agent forwarding supports Windows OpenSSH and 1Password agents when SSH_AUTH_SOCK is not set.

Kits

V3 kits support capability groups, kit.env references, bundled agent skills, and the ssh-agent@1 and git-identity@1 capabilities. Selected optional groups retain their network rules, lifecycle files, and context; unsupported optional groups are skipped. Bundled skills can use directories outside the agent's home.
sbx kit add accepts kits with startup commands. Those commands run after the kit is added and on each subsequent sandbox start.
Sandbox containers expose the provisioned agent's name through SBX_AGENT for kit hooks and scripts.
sbx kit validate rejects kits whose credentials route the same host, identifying the conflicting services. The daemon logs the collision during sandbox creation.
Sandbox creation supports kits whose resolved lock exceeds Docker's container-label size limit.
sbx kit pack excludes its output from the archive, prevents writes into the kit's files/ directory, and handles Windows 8.3 output paths without renaming the destination or including a previous archive. The output path must end in .zip and cannot be a named pipe, socket, or device node.
An unresolvable kit-file path no longer causes sbx kit push to fail.
Kits that declare an agent-context directory now have their agent instructions file written in that directory instead of beside the workspace, and large workload and mixin kit combinations no longer fail to create with "failed to run sandbox container".

Sandbox lifecycle and workspaces

Creating a sandbox from a local snapshot saved with this version avoids registry requests by default, including when using the daemon API.
sbx exec, sbx run, sbx cp, and SSH report an unresponsive guest with stop-and-start guidance instead of hanging. sbx ls marks the sandbox as not responding.
Commands against an already-running sandbox reuse guest setup instead of repeating it on every exec, run, or cp invocation. Setup runs once per container start or daemon restart.
sbx reset no longer leaves stray sandbox resources or stalls when another sandbox operation is in progress.
Sandbox startup identifies files still in use from a previous run instead of reporting a generic failure.
sbx exec accepts empty command arguments.
sbx cp preserves dot-prefixed paths and restrictive directory permissions. On Windows, downloads can replace a read-only destination instead of failing with “Access is denied”.
sbx run and sbx create support workspace directories whose names start with a dot.

Cloud sandboxes

sbx move --to cloud and sbx --cloud env create accept --ttl and --on-timeout restart, extending always-on support beyond sbx --cloud create.
Fixed on_timeout response decoding errors when using --on-timeout.

Authentication, agents, and MCP

Sandbox-scoped custom secrets can override global secrets that use the same environment variable name.
Fixed Docker Hub sign-outs on macOS when the host sleeps or wakes during login-token refresh.
The built-in Codex kit registers the MCP gateway with supported settings, removing ignored-setting warnings and sending the gateway its Authorization header. Recreate existing Codex sandboxes with sbx rm and sbx create to receive the change.
sbx mcp unload NAME --sandbox SANDBOX detaches a loaded MCP server without restarting the sandbox's agent.
MCP connections and discovery probes identify as docker-sbx, and backend recovery respects rate limits to avoid reconnect storms.
sbx run --model --provider uses the API key stored with sbx secret set <provider> without exposing it to the sandbox. sbx run --variant selects a model thinking variant.
Fixed sbx run --model failing with “401 Unauthorized” when pulling from Docker Hub after a browser-based docker login.

Networking and policy

The proxy handles trailing-dot hostnames and mixed-case host.docker.internal consistently, fixing refused requests and missing credential injection.
Sandbox image pulls retry temporary registry failures reported as HTTP 5xx errors, including when the original error type is lost across API or progress-stream boundaries.
Fixed WebSocket connections through the proxy occasionally losing the first bytes sent by the client.
sbx policy ls SANDBOX returns an error when the sandbox does not exist.
sbx policy inspect accepts policy names that match one of their own rule names, such as default-deny-all.
Removing a kit-managed network rule by resource explains that the kit manages it instead of asking for a rule ID.

CLI and diagnostics

Shell completion scripts generate without starting telemetry, reducing generation time.
sbx diagnose checks for mkfs.ext4.