diff --git a/content/manuals/ai/sandboxes/release-notes.md b/content/manuals/ai/sandboxes/release-notes.md index 664c39779051..4f0c17939e87 100644 --- a/content/manuals/ai/sandboxes/release-notes.md +++ b/content/manuals/ai/sandboxes/release-notes.md @@ -15,6 +15,51 @@ the full release history, including pre-releases and downloads, see the +## 0.34.0 + +{{< release-date date="2026-06-26" >}} + +[GitHub release](https://github.com/docker/sbx-releases/releases/tag/v0.34.0) + +### Highlights + +Kit installs are now restricted to an allowlist of sources, defaulting to Docker Hub only — a **breaking change** if you install kits from a Git URL or another registry. + +This release also renames `sbx policy set-default` to `sbx policy init`, restores published ports when a sandbox restarts, fixes a number of bugs, and adds two experimental previews: a native SSH endpoint and an `sbx setup` command for smoother first-time onboarding. + +### What's New + +#### SSH + +- Add an experimental native SSH endpoint in sandboxd: connect with `ssh @127.0.0.1 -p 2222` (publickey auth, connect-to-create, interactive shell and exec; no SFTP yet). Enable with `sbx settings set feature.ssh true`. + +#### Setup & Onboarding + +- Add an experimental `sbx setup` command that imports agent credentials from environment variables. + +#### Agents + +- Cursor sandboxes no longer show the workspace trust prompt on launch. + +#### Kits + +- Add OCI v2 kit artifact streaming that decompresses the layer once to a cache directory and uses seek-based random access, so file content is not held in memory between reads. +- Restrict kit installs to an allowlist of sources, defaulting to Docker Hub (`docker.io/`) only. + + **Breaking:** installing a kit from another registry or a Git URL fails until you add its prefix with `sbx settings set kit.allowedSources`. See [Docs: Restrict kit sources](https://docs.docker.com/ai/sandboxes/customize/kits#restrict-kit-sources) for details. + +#### CLI & Behavior Changes + +- Rename `sbx policy set-default` to `sbx policy init`; the old name keeps working as a hidden, deprecated alias. +- Published sandbox ports are restored on restart, and the CLI/TUI can recover explicit host-port conflicts by choosing a new host port. + +#### Bug Fixes + +- Fix a daemon hang where a slow or stuck sandbox creation/deletion blocked `sbx ls`, the TUI, and new sessions until the daemon was restarted. +- Fix a kit mixin regression where adding `network.serviceDomains` for a service already provided by the base agent failed with a "credential … defined in both" error. +- Reject `+` in sandbox names with a clear validation error instead of panicking. +- Fix the interactive host-port conflict recovery prompt not appearing on Windows when restarting a sandbox whose published port is already in use. + ## 0.33.0 {{< release-date date="2026-06-17" >}} @@ -134,124 +179,6 @@ This release also improves network isolation and policy enforcement. Sandbox DNS - Stop counting expected `rm`/`stop`/list-ports "not found" 404s as analytics failures, so routine existence checks no longer inflate error dashboards. - Require a daemon restart (instead of failing with `405 Method Not Allowed`) when downgrading the CLI below a newer running daemon. -## 0.31.3 - -{{< release-date date="2026-06-03" >}} - -[GitHub release](https://github.com/docker/sbx-releases/releases/tag/v0.31.3) - -### Bug Fixes - -- Fix a failure to start sandboxes that were created with older versions of the CLI. -- Fix a file descriptor leak on Linux. Each credential lookup left a session - D-Bus socket open, so long-running processes (such as the daemon) could - gradually accumulate open file descriptors and eventually hit the session - bus's connection limit, failing with "The maximum number of active - connections has been reached." Connections are now closed after each - operation. macOS and Windows were not affected. - -## 0.31.2 - -{{< release-date date="2026-06-01" >}} - -[GitHub release](https://github.com/docker/sbx-releases/releases/tag/v0.31.2) - -### Highlights - -This patch release resolves two reliability issues. It **fixes a Windows issue** where odd default sandbox memory values could lead to startup timeouts. It also includes a **daemon-compatibility fix** that prevents a silent failure (`405 Method Not Allowed`) when the `sbx` CLI is downgraded while a newer `sandboxd` daemon is still running — the CLI now requires a daemon restart instead. - -### What's New - -#### Bug Fixes - -- Fix a Windows issue where odd default sandbox memory values could lead to startup timeouts. -- Require a daemon restart when downgrading the CLI below a running daemon, instead of silently proceeding into a `405 Method Not Allowed` error. - -## 0.31.1 - -{{< release-date date="2026-05-29" >}} - -[GitHub release](https://github.com/docker/sbx-releases/releases/tag/v0.31.1) - -### Bug fixes - -- Fixes a bug introduced in v0.31.0 where sandboxes from earlier versions were not listed by sbx ls and could fail to run. Upgrading to v0.31.1 restores them. - -## 0.31.0 - -{{< release-date date="2026-05-28" >}} - -[GitHub release](https://github.com/docker/sbx-releases/releases/tag/v0.31.0) - -### Highlights - -#### Clone mode: `--clone` - -The `--branch` flag has been removed in favor of `--clone` (clone mode). Using `--branch` now fails with: - -```console -$ sbx run claude --branch foo -ERROR: --branch is no longer supported; use --clone instead -``` - -Clone mode does not create a branch or worktree on your behalf — instead of a host-side worktree, the sandbox now runs against an in-container read-only clone. - -- Your source repository is mounted into the sandbox read-only, and the shallow clone sets that mount as a Git remote. The agent only ever writes to the in-container clone, never to your working tree or .git/ -- The clone lives on the sandbox's filesystem and is exposed back to the host as a `sandbox-` Git remote served by `git-daemon` (no more `.sbx/-worktrees/...` on the host). -- Forge remotes (`origin`, `upstream`, etc.) on the host are propagated into the in-container clone, so the agent can `git push origin` directly, the same way you would. Local-path remotes are skipped. -- Fetched sandbox refs are mirrored into `refs/sandboxes//*` on the host and persist after the sandbox is removed. Restore a branch from a removed sandbox with `git branch refs/sandboxes//`. Commits that were never fetched, or uncommitted changes, are still lost on `sbx rm`. -- The `sandbox-` remote is added to your host on `sbx create --clone` / `sbx run --clone` and removed on `sbx rm`, including across stop and restart. - -### What's New - -#### CLI - -- `sbx create` auto-starts the daemon when it isn't already running. -- `sbx logout` now stops the daemon and running sandboxes. -- Unify terminal environment variables across `sbx run` and `sbx exec`. - -#### Policies - -- Show policy and rule names in CLI list output and TUI details. -- Add filters to the policies listing. - -#### Kits - -- Mark kits as experimental. -- Verbose error reporting for kit apply failures. - -#### Sandboxes - -- Opt a sandbox into virtiofs caching at create time via `DOCKER_SANDBOXES_ENABLE_VIRTIOFS_CACHE=1` (off by default; the choice is persisted in the spec and survives daemon restarts). - -#### Networking - -- Allow public-CA CRL/OCSP/AIA endpoints in the balanced proxy preset. Applies to new installations or after `sbx policy reset` (which removes any user-added rules). - -#### Telemetry - -- Surface `port_publish_failed` inner error detail. - -#### Secrets - -- Store container-registry pull credentials with `sbx secret set --registry`, so `sbx run --template` and `sbx run --kit` can pull from private registries (GHCR, ACR, ECR, Quay, …) without a `docker login`. Manage entries with `sbx secret ls` and remove them with `sbx secret rm --registry `. - -> [!WARNING] -> By default the credential is stored **host-side only** and is used just for pulling templates/kits. It is never placed inside a sandbox. If you pass `-g` (or scope it to a sandbox name), the credential is **injected into the sandbox in plaintext**, where the agent and any code running there can read it. Only use `-g`/sandbox scope when the sandbox itself needs to pull from the registry; otherwise omit `-g` to keep it host-only. - -#### Bug Fixes - -- Sort `template ls` output by repository, then tag. -- Retry `ExecResize` to keep the agent TUI in sync. -- Set `TERM=xterm-256color` when exec'ing with `-t`. -- Move the state directory symlink from `/tmp` to `~/.sbx/run/`. -- Stop `storageRootsGone` from locking the storagekit singleton. -- Use `engineError` and add retry debug logging in sandboxd. -- Retry transient shim start closures. -- Make Cursor session bootstrap proxy-local. -- Add bracketed `[::1]` to `NO_PROXY` for IPv6 loopback. -- Backdate proxy CA `NotBefore` to match the goproxy leaf cert window. - ## Earlier releases diff --git a/data/sbx_cli/sbx.yaml b/data/sbx_cli/sbx.yaml index 8beb101c632d..fc39a7d3b337 100644 --- a/data/sbx_cli/sbx.yaml +++ b/data/sbx_cli/sbx.yaml @@ -30,6 +30,7 @@ see_also: - sbx rm - Remove one or more sandboxes - sbx run - Run an agent in a sandbox - sbx secret - Manage stored secrets + - sbx setup - (Experimental) Detect host configuration and prepare Docker Sandboxes - sbx stop - Stop one or more sandboxes without removing them - sbx template - Manage sandbox templates - sbx tui - Open the interactive TUI dashboard diff --git a/data/sbx_cli/sbx_create.yaml b/data/sbx_cli/sbx_create.yaml index 78ced18da439..b4aeeeb1cfc3 100644 --- a/data/sbx_cli/sbx_create.yaml +++ b/data/sbx_cli/sbx_create.yaml @@ -13,7 +13,7 @@ options: - name: cpus default_value: "0" usage: | - Number of CPUs to allocate to the sandbox (0 = auto: N-1 host CPUs, min 1) + Number of CPUs to allocate to the sandbox (0 = auto: all host CPUs) - name: help shorthand: h default_value: "false" diff --git a/data/sbx_cli/sbx_create_claude.yaml b/data/sbx_cli/sbx_create_claude.yaml index 1a21d45d184a..2ffde54ce9e0 100644 --- a/data/sbx_cli/sbx_create_claude.yaml +++ b/data/sbx_cli/sbx_create_claude.yaml @@ -22,7 +22,7 @@ inherited_options: - name: cpus default_value: "0" usage: | - Number of CPUs to allocate to the sandbox (0 = auto: N-1 host CPUs, min 1) + Number of CPUs to allocate to the sandbox (0 = auto: all host CPUs) - name: debug shorthand: D default_value: "false" diff --git a/data/sbx_cli/sbx_create_codex.yaml b/data/sbx_cli/sbx_create_codex.yaml index 3797e5a08936..a14e03c2b75c 100644 --- a/data/sbx_cli/sbx_create_codex.yaml +++ b/data/sbx_cli/sbx_create_codex.yaml @@ -22,7 +22,7 @@ inherited_options: - name: cpus default_value: "0" usage: | - Number of CPUs to allocate to the sandbox (0 = auto: N-1 host CPUs, min 1) + Number of CPUs to allocate to the sandbox (0 = auto: all host CPUs) - name: debug shorthand: D default_value: "false" diff --git a/data/sbx_cli/sbx_create_copilot.yaml b/data/sbx_cli/sbx_create_copilot.yaml index d5ceb1764860..4224e34e4ea9 100644 --- a/data/sbx_cli/sbx_create_copilot.yaml +++ b/data/sbx_cli/sbx_create_copilot.yaml @@ -22,7 +22,7 @@ inherited_options: - name: cpus default_value: "0" usage: | - Number of CPUs to allocate to the sandbox (0 = auto: N-1 host CPUs, min 1) + Number of CPUs to allocate to the sandbox (0 = auto: all host CPUs) - name: debug shorthand: D default_value: "false" diff --git a/data/sbx_cli/sbx_create_cursor.yaml b/data/sbx_cli/sbx_create_cursor.yaml index 724b0639dedb..ba8a42a2547a 100644 --- a/data/sbx_cli/sbx_create_cursor.yaml +++ b/data/sbx_cli/sbx_create_cursor.yaml @@ -22,7 +22,7 @@ inherited_options: - name: cpus default_value: "0" usage: | - Number of CPUs to allocate to the sandbox (0 = auto: N-1 host CPUs, min 1) + Number of CPUs to allocate to the sandbox (0 = auto: all host CPUs) - name: debug shorthand: D default_value: "false" diff --git a/data/sbx_cli/sbx_create_docker-agent.yaml b/data/sbx_cli/sbx_create_docker-agent.yaml index ae167e57c826..b04a541e2dc2 100644 --- a/data/sbx_cli/sbx_create_docker-agent.yaml +++ b/data/sbx_cli/sbx_create_docker-agent.yaml @@ -22,7 +22,7 @@ inherited_options: - name: cpus default_value: "0" usage: | - Number of CPUs to allocate to the sandbox (0 = auto: N-1 host CPUs, min 1) + Number of CPUs to allocate to the sandbox (0 = auto: all host CPUs) - name: debug shorthand: D default_value: "false" diff --git a/data/sbx_cli/sbx_create_droid.yaml b/data/sbx_cli/sbx_create_droid.yaml index 8cb6c566bd36..237a68b2864a 100644 --- a/data/sbx_cli/sbx_create_droid.yaml +++ b/data/sbx_cli/sbx_create_droid.yaml @@ -22,7 +22,7 @@ inherited_options: - name: cpus default_value: "0" usage: | - Number of CPUs to allocate to the sandbox (0 = auto: N-1 host CPUs, min 1) + Number of CPUs to allocate to the sandbox (0 = auto: all host CPUs) - name: debug shorthand: D default_value: "false" diff --git a/data/sbx_cli/sbx_create_gemini.yaml b/data/sbx_cli/sbx_create_gemini.yaml index 90350b1684f7..5a94084deb6d 100644 --- a/data/sbx_cli/sbx_create_gemini.yaml +++ b/data/sbx_cli/sbx_create_gemini.yaml @@ -22,7 +22,7 @@ inherited_options: - name: cpus default_value: "0" usage: | - Number of CPUs to allocate to the sandbox (0 = auto: N-1 host CPUs, min 1) + Number of CPUs to allocate to the sandbox (0 = auto: all host CPUs) - name: debug shorthand: D default_value: "false" diff --git a/data/sbx_cli/sbx_create_kiro.yaml b/data/sbx_cli/sbx_create_kiro.yaml index 36aae1277613..9734a1b2fd3a 100644 --- a/data/sbx_cli/sbx_create_kiro.yaml +++ b/data/sbx_cli/sbx_create_kiro.yaml @@ -22,7 +22,7 @@ inherited_options: - name: cpus default_value: "0" usage: | - Number of CPUs to allocate to the sandbox (0 = auto: N-1 host CPUs, min 1) + Number of CPUs to allocate to the sandbox (0 = auto: all host CPUs) - name: debug shorthand: D default_value: "false" diff --git a/data/sbx_cli/sbx_create_opencode.yaml b/data/sbx_cli/sbx_create_opencode.yaml index cec2dfb89da4..765031ce6620 100644 --- a/data/sbx_cli/sbx_create_opencode.yaml +++ b/data/sbx_cli/sbx_create_opencode.yaml @@ -22,7 +22,7 @@ inherited_options: - name: cpus default_value: "0" usage: | - Number of CPUs to allocate to the sandbox (0 = auto: N-1 host CPUs, min 1) + Number of CPUs to allocate to the sandbox (0 = auto: all host CPUs) - name: debug shorthand: D default_value: "false" diff --git a/data/sbx_cli/sbx_create_shell.yaml b/data/sbx_cli/sbx_create_shell.yaml index bbbf75c3c464..957b35099960 100644 --- a/data/sbx_cli/sbx_create_shell.yaml +++ b/data/sbx_cli/sbx_create_shell.yaml @@ -22,7 +22,7 @@ inherited_options: - name: cpus default_value: "0" usage: | - Number of CPUs to allocate to the sandbox (0 = auto: N-1 host CPUs, min 1) + Number of CPUs to allocate to the sandbox (0 = auto: all host CPUs) - name: debug shorthand: D default_value: "false" diff --git a/data/sbx_cli/sbx_policy.yaml b/data/sbx_cli/sbx_policy.yaml index 10a30d5152ac..968db88e9df9 100644 --- a/data/sbx_cli/sbx_policy.yaml +++ b/data/sbx_cli/sbx_policy.yaml @@ -21,8 +21,8 @@ see_also: - sbx - Manage AI coding agent sandboxes. - sbx policy allow - Add an allow rule for sandboxes - sbx policy deny - Add a deny rule for sandboxes + - sbx policy init - Initialize the global network policy - sbx policy log - Show sandbox policy logs - sbx policy ls - List sandbox policy rules - sbx policy reset - Reset policies to defaults - sbx policy rm - Remove a policy rule - - sbx policy set-default - Set the default network policy diff --git a/data/sbx_cli/sbx_policy_init.yaml b/data/sbx_cli/sbx_policy_init.yaml new file mode 100644 index 000000000000..a8ac9bdece17 --- /dev/null +++ b/data/sbx_cli/sbx_policy_init.yaml @@ -0,0 +1,43 @@ +name: sbx policy init +synopsis: Initialize the global network policy +description: |- + Initialize the global network policy that applies to all sandboxes. + + This sets the initial global network policy and must be run before adding + custom allow/deny rules or starting a sandbox for the first time. It is a + one-time setup: once initialized, use "sbx policy reset" to start over. + + This is the initial global policy, not a per-sandbox default; you can change + it later. Per-sandbox rules, including those added by kits such as the + built-in agent kits, apply on top for individual sandboxes. + + Available policies: + allow-all All outbound network traffic is allowed + balanced Typical development traffic is allowed, such as AI services and package registries + deny-all All outbound network traffic is blocked + + After initializing, use "sbx policy allow/deny/rm" to change the global policy. + Use "sbx policy reset" to clear all policies and start over. +usage: sbx policy init [flags] +options: + - name: help + shorthand: h + default_value: "false" + usage: help for init +inherited_options: + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +example: |4- + # Initialize with the balanced policy — recommended + sbx policy init balanced + + # Allow all traffic + sbx policy init allow-all + + # Block everything, then allow specific sites + sbx policy init deny-all + sbx policy allow network api.example.com:443 +see_also: + - sbx policy - Manage sandbox policies diff --git a/data/sbx_cli/sbx_policy_log.yaml b/data/sbx_cli/sbx_policy_log.yaml index 34c68a60e9f9..39f398a94de8 100644 --- a/data/sbx_cli/sbx_policy_log.yaml +++ b/data/sbx_cli/sbx_policy_log.yaml @@ -24,7 +24,8 @@ options: usage: Only display log entries - name: type default_value: all - usage: 'Filter logs by type: "all" or "network" (default "all")' + usage: | + Filter logs by type: "all", "network", or "filesystem" (filesystem logs are not supported yet; default "all") inherited_options: - name: debug shorthand: D diff --git a/data/sbx_cli/sbx_policy_ls.yaml b/data/sbx_cli/sbx_policy_ls.yaml index 5005d5b41dd6..1810e6a5ea1c 100644 --- a/data/sbx_cli/sbx_policy_ls.yaml +++ b/data/sbx_cli/sbx_policy_ls.yaml @@ -22,7 +22,8 @@ options: usage: Show inactive policy rules hidden by remote governance - name: type default_value: all - usage: 'Filter policies by type: "all" or "network" (default "all")' + usage: | + Filter policies by type: "all", "network", or "filesystem" (default "all") inherited_options: - name: debug shorthand: D @@ -35,6 +36,9 @@ example: |4- # List only network policies sbx policy ls --type network + # List only filesystem policies + sbx policy ls --type filesystem + # List policies that apply to a specific sandbox sbx policy ls my-sandbox diff --git a/data/sbx_cli/sbx_policy_reset.yaml b/data/sbx_cli/sbx_policy_reset.yaml index 7c4c1ec80b25..5c6e9289392d 100644 --- a/data/sbx_cli/sbx_policy_reset.yaml +++ b/data/sbx_cli/sbx_policy_reset.yaml @@ -3,8 +3,9 @@ synopsis: Reset policies to defaults description: |- Remove all custom policies and restart the daemon to restore defaults. - This deletes the local policy store and stops the daemon. When the daemon - restarts (automatically on next command), the default policy is installed. + This deletes the local policy store and stops the daemon. The daemon restarts + automatically on the next command, then prompts you to initialize the global + network policy again. If sandboxes are currently running, they will be stopped when the daemon shuts down. You will be prompted for confirmation unless --force is used. @@ -24,7 +25,7 @@ inherited_options: default_value: "false" usage: Enable debug logging example: |4- - # Reset policies (prompts if sandboxes are running) + # Reset policies — prompts if sandboxes are running sbx policy reset # Reset policies without confirmation diff --git a/data/sbx_cli/sbx_policy_set-default.yaml b/data/sbx_cli/sbx_policy_set-default.yaml deleted file mode 100644 index 505ee16fd799..000000000000 --- a/data/sbx_cli/sbx_policy_set-default.yaml +++ /dev/null @@ -1,38 +0,0 @@ -name: sbx policy set-default -synopsis: Set the default network policy -description: |- - Set the default network policy for all sandboxes. - - This must be run before adding custom allow/deny rules or starting a sandbox - for the first time. The default policy determines the baseline network access. - - Available policies: - allow-all All outbound network traffic is allowed - balanced Typical development traffic is allowed (AI services, package registries, etc.) - deny-all All outbound network traffic is blocked - - After setting defaults, use "sbx policy allow/deny" to add custom rules. - Use "sbx policy reset" to clear all policies and start over. -usage: sbx policy set-default [flags] -options: - - name: help - shorthand: h - default_value: "false" - usage: help for set-default -inherited_options: - - name: debug - shorthand: D - default_value: "false" - usage: Enable debug logging -example: |4- - # Set balanced defaults (recommended) - sbx policy set-default balanced - - # Allow all traffic - sbx policy set-default allow-all - - # Block everything, then allow specific sites - sbx policy set-default deny-all - sbx policy allow network api.example.com:443 -see_also: - - sbx policy - Manage sandbox policies diff --git a/data/sbx_cli/sbx_run.yaml b/data/sbx_cli/sbx_run.yaml index 7141fe80d6ab..68f2acf02f11 100644 --- a/data/sbx_cli/sbx_run.yaml +++ b/data/sbx_cli/sbx_run.yaml @@ -10,7 +10,9 @@ description: |- Pass agent arguments after the "--" separator. Additional workspaces can be provided as extra arguments. Append ":ro" to mount them read-only. - To create a sandbox without attaching, use "sbx create" instead. + To create a sandbox without attaching, use "sbx create" instead, or + pass --detached (-d) to print the sandbox ID and exit without opening an + interactive session. Available agents: claude, codex, copilot, cursor, docker-agent, droid, gemini, kiro, opencode, shell usage: sbx run [flags] [AGENT] [PATH...] [-- AGENT_ARGS...] @@ -22,7 +24,7 @@ options: - name: cpus default_value: "0" usage: | - Number of CPUs to allocate to the sandbox (0 = auto: N-1 host CPUs, min 1) + Number of CPUs to allocate to the sandbox (0 = auto: all host CPUs) - name: help shorthand: h default_value: "false" diff --git a/data/sbx_cli/sbx_secret_rm.yaml b/data/sbx_cli/sbx_secret_rm.yaml index c555e36263d0..5830519a0c81 100644 --- a/data/sbx_cli/sbx_secret_rm.yaml +++ b/data/sbx_cli/sbx_secret_rm.yaml @@ -35,6 +35,9 @@ example: |4- sbx secret rm -g openai sbx secret rm -g anthropic + # Remove custom secret by specifying the placeholder value + sbx secret rm -g --placeholder docker-placeholder-value + # Remove registry pull credentials (removes host-only and global entries) sbx secret rm --registry ghcr.io -f diff --git a/data/sbx_cli/sbx_setup.yaml b/data/sbx_cli/sbx_setup.yaml new file mode 100644 index 000000000000..aa5edb8c1b7d --- /dev/null +++ b/data/sbx_cli/sbx_setup.yaml @@ -0,0 +1,29 @@ +name: sbx setup +synopsis: | + Detect host configuration and prepare Docker Sandboxes +experimental: true +description: |- + Detect what is already configured on your host and prepare Docker Sandboxes. + + Agent secrets are detected from the built-in agent kit specs and the + env vars set on this host, and accepted secrets are imported into the global + secrets store (the same store as "sbx secret set -g"). + + [T] toggle the detailed review table on/off + ↑/↓ move between rows + TAB toggle import / skip for the selected row + [enter] accept and import + [q]/esc quit without importing +usage: sbx setup +options: + - name: help + shorthand: h + default_value: "false" + usage: help for setup +inherited_options: + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +see_also: + - sbx - Manage AI coding agent sandboxes.