sbx/v0.34

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

@@ -15,6 +15,51 @@ the full release history, including pre-releases and downloads, see the
 
 <!-- BEGIN GENERATED RELEASES -->
 
+## 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 <sandbox-name>@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-<name>` Git remote served by `git-daemon` (no more `.sbx/<name>-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/<name>/*` on the host and persist after the sandbox is removed. Restore a branch from a removed sandbox with `git branch <local-name> refs/sandboxes/<name>/<branch>`. Commits that were never fetched, or uncommitted changes, are still lost on `sbx rm`.
-- The `sandbox-<name>` 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 <host>`.
-
-> [!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.
-
 <!-- END GENERATED RELEASES -->
 
 ## Earlier releases

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

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"

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"

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"

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"

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"

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"

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"

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"

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"

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"

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"

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

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 <allow-all|balanced|deny-all> [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

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

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
 

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