From c572cdcb546eda2c03e6453047c2129dee2c9247 Mon Sep 17 00:00:00 2001
From: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Date: Mon, 26 Oct 2026 17:28:15 +0100
Subject: [PATCH] docs: cover sbx 0.50 user-facing changes (#26449)

Documents six user-facing changes in sbx 0.50: kit host mount bindings,
persistent kit volume retention, environment MCP command approvals and
ownership, HTTP query restrictions, cloud sandbox inspection, and exec
exit status in automation. Each change has its own commit. Also vendors
the matching v0.50 CLI reference verbatim and regenerates the release
notes from published GitHub releases.

Kit documentation focuses on sbx usage and links to the canonical
capability definitions. Volume retention follows the 0.50
implementation; the upstream spec's main branch describes a different
storage lifecycle.

Verified against the release implementation. Scoped Markdown and prose
lint, a full Hugo build, and checks of the added internal links pass.

Related release: https://github.com/docker/sandboxes/issues/7698

Generated by Codex
---
 content/manuals/ai/sandboxes/cloud/usage.md   |  14 ++
 .../configuration/environment-files.md        | 118 +++++++++++---
 .../customize/author/capabilities.md          |   5 +-
 .../ai/sandboxes/customize/author/patterns.md |  23 ++-
 .../ai/sandboxes/customize/use-kits.md        |  49 ++++++
 .../governance/access-controls/local.md       |  20 ++-
 .../governance/access-controls/network.md     |   6 +-
 .../ai/sandboxes/governance/concepts.md       |  35 ++++-
 content/manuals/ai/sandboxes/release-notes.md | 147 +++++++++++-------
 content/manuals/ai/sandboxes/usage.md         |  11 +-
 .../ai/sandboxes/workflows/automation.md      |   5 +
 data/sbx_cli/sbx_cp.yaml                      |   4 +
 data/sbx_cli/sbx_create.yaml                  |  12 +-
 data/sbx_cli/sbx_create_claude.yaml           |   7 +-
 data/sbx_cli/sbx_create_codex.yaml            |   7 +-
 data/sbx_cli/sbx_create_cursor.yaml           |   7 +-
 data/sbx_cli/sbx_create_devin.yaml            |   7 +-
 data/sbx_cli/sbx_create_docker-agent.yaml     |   7 +-
 data/sbx_cli/sbx_create_gemini.yaml           |   7 +-
 data/sbx_cli/sbx_create_opencode.yaml         |   7 +-
 data/sbx_cli/sbx_create_shell.yaml            |   7 +-
 data/sbx_cli/sbx_env.yaml                     |  12 +-
 data/sbx_cli/sbx_env_create.yaml              |   3 +-
 data/sbx_cli/sbx_env_exec.yaml                |   4 +
 data/sbx_cli/sbx_env_plan.yaml                |   2 +-
 data/sbx_cli/sbx_env_rm.yaml                  |   3 +-
 data/sbx_cli/sbx_env_run.yaml                 |   3 +-
 data/sbx_cli/sbx_exec.yaml                    |   4 +
 data/sbx_cli/sbx_kit_builder.yaml             |   2 +-
 data/sbx_cli/sbx_kit_builder_history.yaml     |   2 +-
 data/sbx_cli/sbx_kit_builder_history_rm.yaml  |   3 +-
 data/sbx_cli/sbx_mcp_rm.yaml                  |  18 ++-
 data/sbx_cli/sbx_policy_allow_network.yaml    |  18 +++
 data/sbx_cli/sbx_policy_deny_network.yaml     |  18 +++
 data/sbx_cli/sbx_policy_inspect.yaml          |   2 +-
 data/sbx_cli/sbx_policy_ls.yaml               |   2 +-
 data/sbx_cli/sbx_policy_rm_network.yaml       |  18 +++
 data/sbx_cli/sbx_rm.yaml                      |   6 +-
 data/sbx_cli/sbx_run.yaml                     |   9 +-
 39 files changed, 497 insertions(+), 137 deletions(-)

diff --git a/content/manuals/ai/sandboxes/cloud/usage.md b/content/manuals/ai/sandboxes/cloud/usage.md
index 99b3ae95bc..373ada694c 100644
--- a/content/manuals/ai/sandboxes/cloud/usage.md
+++ b/content/manuals/ai/sandboxes/cloud/usage.md
@@ -111,6 +111,20 @@ $ sbx --cloud ls
 Most cloud commands accept either the sandbox name or the `sbx_`-prefixed ID
 shown in the output.
 
+Inspect a sandbox's state, template, resources, timeout settings, and
+published port URLs:
+
+```console
+$ sbx --cloud inspect cloud-project
+```
+
+Use `--format json` or `--format yaml` for structured output. For example,
+retrieve the published port URLs in a script:
+
+```console
+$ sbx --cloud inspect cloud-project --format json | jq -r '.ports[]? | .url // empty'
+```
+
 ## Run commands
 
 Run a command inside a cloud sandbox:
diff --git a/content/manuals/ai/sandboxes/configuration/environment-files.md b/content/manuals/ai/sandboxes/configuration/environment-files.md
index c15a6022ac..1ce8649c95 100644
--- a/content/manuals/ai/sandboxes/configuration/environment-files.md
+++ b/content/manuals/ai/sandboxes/configuration/environment-files.md
@@ -92,8 +92,8 @@ existing sandbox.
 
 ### Protect the environment file
 
-Environment files can declare lifecycle and secret commands that run on your
-host. Keep them outside writable sandbox mounts so the agent cannot change
+Environment files can declare lifecycle, secret, and MCP commands that run on
+your host. Keep them outside writable sandbox mounts so the agent cannot change
 what a later invocation runs. This applies to both the primary workspace and
 `additionalWorkspaces`.
 
@@ -479,27 +479,53 @@ directory. Plans without host commands apply silently on later invocations until
 the environment changes or a resource is missing. An approval provided with
 `--force` applies only to that invocation.
 
+### Approve or skip host commands
+
+Plans containing lifecycle commands, credential `command` sources, or local MCP
+commands require approval for every invocation by default, even when the command
+text hasn't changed. Approve one invocation with `--force`, skip lifecycle and
+MCP commands with `--skip-host-commands`, or turn on
+[`env.rememberHostCommands`](settings.md#envrememberhostcommands) to remember
+approval until the commands change:
+
+```console
+$ sbx settings set env.rememberHostCommands true
+```
+
+To run an environment without lifecycle or local MCP commands, use:
+
+```console
+$ sbx env run --skip-host-commands
+```
+
+The flag also disables previously approved MCP commands before asking you to
+approve the plan. They remain disabled even if you cancel the plan or restart
+the daemon. To enable them again, run `sbx env run` without the flag and approve
+the plan. Credential `command` sources still run when their secrets are needed.
+
 ## Update an environment
 
 For an existing sandbox, `sbx env run` applies updated `env` values to the new
-agent session and reconciles declared MCP servers. Changes to workspaces, kits,
-ports, secrets, bindings, and `sandboxOptions` take effect only when the
-sandbox is next created. Remove the environment with `sbx env rm`, then create
+agent session and reconciles declared MCP servers. Changes to workspaces, kit
+host mounts, kits, ports, secrets, bindings, and `sandboxOptions` take effect
+only when the sandbox is next created. Remove the environment with `sbx env rm`, then create
 it again to apply those changes.
 
 ## Remove an environment
 
 Secrets and registry credentials are sandbox-scoped. Credential bindings and
-MCP server registrations are host-global and can be shared by multiple
-sandboxes.
+remote MCP server registrations are host-global and can be shared by multiple
+sandboxes. Local MCP commands declared by the environment belong to that
+environment and sandbox.
 
 `sbx env rm` builds a destroy plan from the resources on the host. The plan
 includes all credentials stored at the sandbox's scope, including credentials
 that the environment file no longer declares. After approval, `sbx` removes
 only the resources named in the plan.
 
-Global credential bindings remain unless you pass `--prune-bindings`. MCP
-registrations remain available to other sandboxes.
+Global credential bindings remain unless you pass `--prune-bindings`. Remote
+MCP registrations remain available to other sandboxes. Removing a local
+environment revokes and removes the MCP commands it registered.
 
 ### Clean up after a failed create
 
@@ -507,8 +533,9 @@ Secret provisioning, binding updates, and MCP server registration occur before
 the sandbox is created. If sandbox creation fails, scoped secrets remain, and
 bindings and MCP registrations may also remain. Run `sbx env rm` with the same
 paths to remove the scoped secrets. Pass `--prune-bindings` if you also want to
-remove the declared global bindings. MCP registrations are host-global and
-remain after cleanup.
+remove the declared global bindings. Remote MCP registrations remain after
+cleanup. If an environment MCP command registration cannot be removed, follow
+[Recover a conflicting MCP registration](#recover-a-conflicting-mcp-registration).
 
 ## File reference
 
@@ -523,6 +550,7 @@ remain after cleanup.
 | `kits`                 | list             | No       | None                           | Kits to install at creation. See [`kits`](#kits)                                 |
 | `workspace`            | string or object | No       | No host mount                  | Primary workspace. See [`workspace`](#workspace)                                |
 | `additionalWorkspaces` | list             | No       | None                           | Extra directories to mount. See [`additionalWorkspaces`](#additionalworkspaces) |
+| `mounts` | map of strings | No | None | Host directories for kit-declared mounts. See [`mounts`](#mounts) |
 | `env`                  | map of strings   | No       | None                           | Environment variables for the sandbox                                           |
 | `sandboxOptions`       | object           | No       | None                           | Creation options. See [`sandboxOptions`](#sandboxoptions)                        |
 | `secrets`              | map              | No       | None                           | Service credentials. See [`secrets`](#secrets)                                  |
@@ -617,6 +645,22 @@ paths resolve from the directory of the environment file that declares them.
 | `path`     | string  | Yes      | None    | Directory to mount            |
 | `readOnly` | boolean | No       | `false` | Mount the directory read-only |
 
+### `mounts`
+
+`mounts` selects host directories for
+[kit-declared host mounts](../customize/use-kits.md#choose-directories-for-kit-host-mounts)
+in local sandboxes. Map each kit-declared sandbox path to an existing host
+directory. Relative host paths resolve from the environment file that declares
+them:
+
+```yaml
+mounts:
+  /home/agent/history: ./history
+```
+
+The target must match a `host-mount@1` path declared by one of the selected
+kits. Bindings take effect when the sandbox is created.
+
 ### `sandboxOptions`
 
 | Field         | Type            | Default  | Description                                           |
@@ -700,17 +744,6 @@ variables:
 The environment file's `env` values and resolved secrets aren't passed to host
 commands.
 
-Plans containing lifecycle commands or credential `command` sources require
-approval for every invocation by default, even when the command text hasn't
-changed. Approve one invocation with `--force`, skip lifecycle commands
-with `--skip-host-commands`, or turn on
-[`env.rememberHostCommands`](settings.md#envrememberhostcommands) to remember
-approval until the commands change:
-
-```console
-$ sbx settings set env.rememberHostCommands true
-```
-
 ### `secrets`
 
 `secrets` maps service names to secret sources. Each entry must set exactly one
@@ -803,8 +836,10 @@ registries:
 ### `mcp`
 
 The `mcp.servers` list registers servers with the built-in
-[MCP gateway](../mcp-gateway.md) and adds them to the sandbox. MCP registrations
-are host-global and remain after `sbx env rm`.
+[MCP gateway](../mcp-gateway.md) and adds them to the sandbox. Remote servers
+registered with `url` remain host-global and survive `sbx env rm`. In local
+environments, servers registered with `command` belong to the environment
+and can run only for its sandbox.
 
 | Field     | Type            | Required | Default | Description                                                     |
 | --------- | --------------- | -------- | ------- | --------------------------------------------------------------- |
@@ -815,6 +850,41 @@ are host-global and remain after `sbx env rm`.
 
 Each server must set exactly one of `url` or `command`.
 
+#### Approve local MCP commands
+
+A `command` server runs on your host with your privileges whenever the
+sandbox's MCP gateway starts, including after restarts. The environment plan
+shows the resolved executable and arguments before registration. Approval
+pins the executable path, not the contents of executables, scripts, or
+packages they load. Keep these files outside writable sandbox mounts.
+
+If an `initialize` command creates the executable or changes its resolved
+path, `sbx` asks you to approve the resolved MCP command after initialization.
+Declining that approval leaves the completed initialization work in place
+but does not register the command. `--force` approves both stages for that
+invocation.
+
+Removing a command from the file and applying the environment revokes its
+registration. `sbx env rm` removes the environment's command registrations.
+
+#### Recover a conflicting MCP registration
+
+An environment cannot take over a command registered manually or by another
+environment, even when its executable and arguments match. Choose a different
+server name, or remove the conflicting registration before applying the file.
+
+For a legacy or damaged registration, stop the daemon before removing only
+its saved registration:
+
+```console
+$ sbx daemon stop
+$ sbx mcp rm --registration-only -- <SERVER_NAME>
+```
+
+Stopping the daemon interrupts its sandbox gateways. Registration-only removal
+does not delete saved credentials. Apply the environment again to register and
+approve the command for its sandbox.
+
 ### `ports`
 
 `ports` publishes sandbox ports when the environment is created. Ports exposed
diff --git a/content/manuals/ai/sandboxes/customize/author/capabilities.md b/content/manuals/ai/sandboxes/customize/author/capabilities.md
index 8dc9910d9f..1af1e0f20c 100644
--- a/content/manuals/ai/sandboxes/customize/author/capabilities.md
+++ b/content/manuals/ai/sandboxes/customize/author/capabilities.md
@@ -18,7 +18,6 @@ Version numbers identify the first `sbx` release that supports the
 capability, subject to the restrictions in the table. Limited support means
 that Docker Sandboxes applies only part of the capability. Declaration only
 means that Docker Sandboxes accepts the entry without using its commands.
-The table covers behavior through v0.48.0.
 
 All capability names in the table have the `com.docker.sandbox/` prefix.
 
@@ -31,7 +30,7 @@ All capability names in the table have the `com.docker.sandbox/` prefix.
 | [`agent-skills@1`](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/agent-skills@1.md) | v0.45.0 | Unsupported | Local sandboxes mount the shared skills store. From v0.48.0, discovery paths also receive bundled skills. |
 | [`credential@1`](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/credential@1.md) | v0.45.0 | Limited: v0.45.0 | In cloud sandboxes, credentials scoped to installation remain available after setup. |
 | [`git-identity@1`](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/git-identity@1.md) | v0.48.0 | Unsupported | Requires `user.name` and `user.email` in the host Git config. |
-| [`host-mount@1`](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/host-mount@1.md) | Unsupported | Unsupported | Kit requests for shared host directories are not supported. |
+| [`host-mount@1`](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/host-mount@1.md) | v0.50.0 | Unsupported | Users can [select host directories](../use-kits.md#choose-directories-for-kit-host-mounts) at creation time. Cloud sandboxes reject required entries and skip optional ones. |
 | [`kit-registry@1`](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/kit-registry@1.md) | v0.45.0 | Unsupported | Restricted to approved OCI builder kits. Local and Git kit sources do not receive registry access. |
 | [`lifecycle@1`](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/lifecycle@1.md) | v0.45.0 | v0.45.0 | Local startup hooks run alongside the agent, rather than blocking its launch. |
 | [`long-running@1`](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/long-running@1.md) | v0.47.0 | Unsupported | Keeps a local sandbox running after its last session disconnects. |
@@ -43,7 +42,7 @@ All capability names in the table have the `com.docker.sandbox/` prefix.
 | [`sbx@1`](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/sbx@1.md) | v0.45.0 | v0.45.0 | Docker Sandboxes launches the agent using the workload command. |
 | [`ssh-agent@1`](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/ssh-agent@1.md) | v0.48.0 | Unsupported | Requires SSH-agent forwarding to be enabled and a host SSH agent to be available. |
 | [`usb-device@1`](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/usb-device@1.md) | Unsupported | Unsupported | Kit requests for USB device access are not supported. |
-| [`volume@1`](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/volume@1.md) | v0.45.0 | Limited: v0.45.0 | Local sandboxes provide block storage or tmpfs. Cloud sandboxes use ordinary sandbox disk at the declared paths, including for tmpfs requests. |
+| [`volume@1`](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/volume@1.md) | v0.45.0 | Limited: v0.45.0 | Local sandboxes provide block storage or tmpfs and [retain block volumes across removal and recreation](../use-kits.md#keep-kit-data-when-recreating-a-sandbox). Cloud sandboxes use ordinary sandbox disk at the declared paths, including for tmpfs requests. |
 
 ## Capability groups
 
diff --git a/content/manuals/ai/sandboxes/customize/author/patterns.md b/content/manuals/ai/sandboxes/customize/author/patterns.md
index 4e5b004b48..ee9a69f8cd 100644
--- a/content/manuals/ai/sandboxes/customize/author/patterns.md
+++ b/content/manuals/ai/sandboxes/customize/author/patterns.md
@@ -108,8 +108,8 @@ capabilities:
       install:
         - command: |
             set -eu
-            chown 1000:1000 /home/agent/.company-cli
             if [ ! -e /home/agent/.company-cli/config.json ]; then
+              chown 1000:1000 /home/agent/.company-cli
               install -o 1000 -g 1000 -m 0644 /usr/share/company-cli/defaults.json /home/agent/.company-cli/config.json
             fi
           user: "0"
@@ -122,13 +122,22 @@ volume already has a configuration file, the hook leaves its contents intact.
 
 ### Configure the volume
 
-The volume keeps the tool's data across sandbox restarts. A replacement
-sandbox gets its own volume. This example allocates `1g` of space. If you
-omit `size`, `sbx` allocates `512m`.
+In local sandboxes, persistent volumes (`volume@1` with `tmpfs: false`)
+keep data across restarts, kit updates, and sandbox removal. Docker Sandboxes
+reattaches a volume when the sandbox name, kit source, and volume path match.
+Changing a volume path gives it separate storage, so keep paths stable across
+kit releases when you want users to retain their data.
 
-Use an install hook to set ownership and permissions for persistent volumes,
-as this example does. The volume capability's `mode` setting applies only
-to tmpfs mounts. See the upstream
+For published kits, changing a tag or digest retains the same kit source.
+For Git sources, the repository and kit subdirectory must stay the same;
+for local sources, the source directory must stay the same. Tmpfs contents
+are discarded when the sandbox stops.
+
+This example allocates `1g` of space. If you omit `size`, `sbx` allocates `512m`.
+
+Use an install hook when your tool needs specific ownership or permissions,
+as this example does. Make initialization preserve existing files and permissions
+when the volume is reused. See the upstream
 [volume definition](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/volume@1.md)
 for storage options.
 
diff --git a/content/manuals/ai/sandboxes/customize/use-kits.md b/content/manuals/ai/sandboxes/customize/use-kits.md
index 306107d302..e38e806aec 100644
--- a/content/manuals/ai/sandboxes/customize/use-kits.md
+++ b/content/manuals/ai/sandboxes/customize/use-kits.md
@@ -275,6 +275,55 @@ Other component arguments are fixed when the set is published.
 Settings chosen during the image build, such as a tool's version, require
 rebuilding the image.
 
+## Kit data and host directories
+
+Kits can provide storage for tool settings, history, and other data. The kit
+chooses which directories to use and whether their contents are persistent,
+temporary, or shared with other sandboxes. Check the kit's documentation before
+relying on it to preserve your work.
+
+### Choose directories for kit host mounts
+
+Some kits share a directory with your host. In local sandboxes, Docker
+Sandboxes manages this directory by default. Its contents survive sandbox
+removal and are shared across sandboxes using the same kit source and mount
+path.
+
+You can choose your own host directory instead. Check the kit's documentation
+for the sandbox path, then pass `--mount HOST:SANDBOX_PATH` when creating the
+sandbox with `sbx create` or `sbx run`. For example, if a published kit uses
+`/home/agent/history`:
+
+```console
+$ mkdir -p ./history
+$ sbx run docker.io/<NAMESPACE>/my-agent:1.0.0 --name my-agent \
+    --mount ./history:/home/agent/history
+```
+
+The host directory must exist, and the sandbox path must exactly match a host
+mount declared by the kit. You can't add other mount paths this way. Repeat
+`--mount` for additional declared paths. These choices are fixed when the
+sandbox is created. Use `sbx inspect <SANDBOX>` to see the host directories.
+
+For an environment file, use
+[`mounts`](../configuration/environment-files.md#mounts).
+Host-directory bindings are available only for local sandboxes.
+
+### Keep kit data when recreating a sandbox
+
+Persistent kit volumes in local sandboxes survive kit updates and sandbox
+removal. To reuse their data, recreate the sandbox with the same name and kit
+source. You can change a published kit's tag or digest, provided the kit still
+uses the same storage paths. A different sandbox name or kit source gets
+separate storage.
+
+This applies only to persistent kit volumes. Save any work you need from the
+container filesystem before removing the sandbox. Temporary kit storage is
+discarded when the sandbox stops.
+
+For how to preserve storage when changing a kit, see
+[Configure the volume](author/patterns.md#configure-the-volume).
+
 ## Restrict kit sources
 
 [`kit.allowedSources`](../configuration/settings.md#kitallowedsources) controls
diff --git a/content/manuals/ai/sandboxes/governance/access-controls/local.md b/content/manuals/ai/sandboxes/governance/access-controls/local.md
index c120e38633..68636519c6 100644
--- a/content/manuals/ai/sandboxes/governance/access-controls/local.md
+++ b/content/manuals/ai/sandboxes/governance/access-controls/local.md
@@ -201,6 +201,19 @@ $ sbx policy allow network api.github.com --method GET --path '/repos/**'
 $ sbx policy allow network api.github.com --method GET --path '/users/**'
 ```
 
+Add `--query` to match URL query parameters
+separately from the path:
+
+```console
+$ sbx policy allow network api.example.com --method GET --path '/search' \
+    --query 'team=platform' --query 'label=release*'
+```
+
+Repeat the flag to require multiple parameters. Keep `--method` in the command,
+or use `--method ANY` to match all methods. Query restrictions use the same
+flags on deny rules. For value patterns and matching behavior, see
+[Query parameters](../concepts.md#query-parameters).
+
 Hosts follow the same patterns as network rules and can include a port. Write
 the host on its own, without a scheme, so an HTTP rule takes `api.example.com`
 rather than `https://api.example.com`.
@@ -219,11 +232,12 @@ $ sbx policy deny network api.example.com --method POST --path '/admin/**'
 For how the two layers combine, see
 [HTTP rules](../concepts.md#http-method-and-path).
 
-Remove an HTTP rule by naming the same qualifiers you added it with, or by
-rule ID:
+Remove an HTTP rule by naming the same qualifiers you added it with, including
+any `--query` flags, or by rule ID:
 
 ```console
-$ sbx policy rm network --resource api.github.com --method GET --path '/repos/org/project/**'
+$ sbx policy rm network --resource api.example.com --method GET --path '/search' \
+    --query 'team=platform' --query 'label=release*'
 $ sbx policy rm network --id 7f3a1c2e-4a73-4e05-bc9d-f2f9a4b50d67
 ```
 
diff --git a/content/manuals/ai/sandboxes/governance/access-controls/network.md b/content/manuals/ai/sandboxes/governance/access-controls/network.md
index b4a1c6c063..b569c0e928 100644
--- a/content/manuals/ai/sandboxes/governance/access-controls/network.md
+++ b/content/manuals/ai/sandboxes/governance/access-controls/network.md
@@ -13,8 +13,8 @@ use separate network policy configuration. See
 Network access policies control outbound connections from sandboxes. Each
 policy contains one or more rules that allow the domains, IP ranges, and ports a
 workflow needs, or block destinations that should stay unavailable. Rules can
-also match the HTTP method and path of a request, so a policy can allow part of
-an API without allowing all of it.
+also match the HTTP method, path, and query parameters of a request, so a policy
+can allow part of an API without allowing all of it.
 
 You can configure network access in two places:
 
@@ -63,7 +63,7 @@ Configure them in either place:
 - Organization policies, in the network rule composer in Docker Home. Set the
   rule **Type** to **HTTP**, then select the methods and path patterns. See
   [Add a network rule](organization.md#add-a-network-rule).
-- Local policies, with `--method` and `--path` on `sbx policy`. See
+- Local policies, with `--method`, `--path`, and `--query` on `sbx policy`. See
   [HTTP method and path rules](local.md#http-method-and-path-rules).
 
 ## Local network rules
diff --git a/content/manuals/ai/sandboxes/governance/concepts.md b/content/manuals/ai/sandboxes/governance/concepts.md
index a7c2928256..eebe81ebd9 100644
--- a/content/manuals/ai/sandboxes/governance/concepts.md
+++ b/content/manuals/ai/sandboxes/governance/concepts.md
@@ -119,8 +119,8 @@ Both IPv4 and IPv6 notation are supported: `10.0.0.0/8`, `192.168.1.0/24`,
 #### HTTP method and path
 
 A network rule matches a destination host on its own. An HTTP rule is a network
-rule that also names an HTTP method and URL path, so a policy can allow reads
-from an API without allowing writes to it.
+rule that also names an HTTP method and URL path, with optional query-parameter
+restrictions, so a policy can allow selected API requests.
 
 An HTTP rule names one or more methods, a destination, and path patterns. What
 each part accepts depends on where you configure the rule:
@@ -154,21 +154,42 @@ can't contain percent-encoding, control characters, repeated or trailing
 slashes, or a `.` segment. For the full list, see
 [HTTP method and path rules](access-controls/local.md#http-method-and-path-rules).
 
+##### Query parameters
+
+An HTTP rule can also restrict query parameters independently of the path.
+
+Use exact parameter names and values, or a single `*` at the start or end of a
+value to match a suffix or prefix. A value of `*` matches any value, including
+an empty one. Names cannot contain wildcards. Names and values are
+case-sensitive.
+
+For rules created with `--query`, every specified parameter must match.
+Parameter order doesn't matter, and requests may include additional parameters. Repeating a parameter
+name in the rule requires separate matching occurrences in the request. A rule
+without query restrictions matches regardless of query parameters.
+
+Write names and value patterns using URL query encoding: `+` or `%20` for a
+space, `%2B` for a literal plus, and `%2A` for a literal asterisk. Keep query
+parameters out of `--path`. For CLI examples, see
+[Local HTTP rules](access-controls/local.md#http-method-and-path-rules).
+
+##### Combine HTTP and network rules
+
 HTTP requests are evaluated against both layers. A network rule sets the
-baseline for a host, and HTTP rules adjust individual methods and paths within
-it:
+baseline for a host, and HTTP rules narrow access by method, path, and query
+parameters:
 
 | Rules that cover the host   | Result for an HTTP request                                              |
 | --------------------------- | ----------------------------------------------------------------------- |
 | Network allow only          | Allowed at any method and path                                          |
-| HTTP allow only             | Allowed only where a rule matches the method and path. Anything else is denied |
-| Network allow and HTTP deny | The denied methods and paths are blocked. The rest stay allowed          |
+| HTTP allow only             | Allowed only where a rule matches the method, path, and any query restrictions. Anything else is denied |
+| Network allow and HTTP deny | Requests matching the HTTP deny are blocked. The rest stay allowed          |
 | Network deny                | Blocked. An HTTP allow can't reopen a denied host                        |
 
 A network deny is therefore a floor that HTTP rules can't raise, while a
 network allow is a ceiling that HTTP rules can carve into.
 
-When a rule requires a method and path decision, the sandbox HTTP proxy
+When a rule requires an HTTP decision, the sandbox HTTP proxy
 evaluates each request separately instead of deciding once per connection.
 
 Those requests have to go through the proxy. A connection it can't inspect,
diff --git a/content/manuals/ai/sandboxes/release-notes.md b/content/manuals/ai/sandboxes/release-notes.md
index 8646ebb8db..d0b1522ab6 100644
--- a/content/manuals/ai/sandboxes/release-notes.md
+++ b/content/manuals/ai/sandboxes/release-notes.md
@@ -16,6 +16,93 @@ the full release history, including pre-releases and downloads, see the
 
 <!-- BEGIN GENERATED RELEASES -->
 
+## 0.50.0
+
+{{< release-date date="2026-10-26" >}}
+
+[GitHub release](https://github.com/docker/sbx-releases/releases/tag/v0.50.0)
+
+### Highlights
+
+Docker Sandboxes v0.50.0 adds configurable kit host mounts, preserves persistent kit volumes across updates and sandbox recreation, and adds cloud sandbox inspection. It also strengthens host-execution, credential, and workspace-copy protections.
+
+### What's new
+
+#### Security
+
+- `sbx cp` rejects symbolic links that escape a sandbox workspace when the workspace is reached through an alternate host path, including a symlink or junction, macOS `/private/tmp`, or a Linux bind mount of a workspace subdirectory.
+- Host Git commands no longer run programs configured by a sandbox through the workspace repository's `.git` directory.
+- Browser, clipboard, and self-update helpers run only from trusted system locations, preventing sandbox-writable directories on `PATH` from supplying those programs.
+- Local source kits are reused and composed only when their digests match recorded local builds. Each local source kit rebuilds once after upgrading.
+- Git kit references reject ambiguous paths, non-ASCII hostnames, and SSH transport syntax. Use IDNA ASCII labels for internationalized hostnames. HTTPS source restrictions are checked against the parsed URL host.
+- MCP OAuth requests block cross-origin credential redirects. Rejected silent refreshes preserve saved credentials without opening a browser.
+- Browser-open logs omit URL query strings and fragments, keeping OAuth parameters and tokens in those components out of daemon logs and diagnostic bundles.
+- Windows clients verify that the daemon's named pipes belong to the same Windows user. Before using the updated CLI, older elevated daemons may need to be stopped with the previous CLI or Task Manager.
+- Environment MCP commands require approval to execute on the host, remain scoped to their sandbox, and are disabled by `--skip-host-commands`. Approval notices explain that executable paths are pinned, but file contents are not. Keep executables and scripts outside writable sandbox mounts.
+- Gordon clears **Approve all** and **Always allow** grants when a conversation resumes, requiring approval before running tools again.
+
+#### Kits
+
+- When creating a sandbox, use `--mount HOST:SANDBOX_PATH` with `sbx create` or `sbx run` to select a host directory for a kit-declared host mount. The sandbox target must exactly match the `path` of a `host-mount@1` capability declared by a kit in the resolved kit set. Environment files support the same bindings through `mounts`, mapping sandbox target paths to host directories. These options cannot add undeclared mount targets.
+- Persistent kit volumes retain data across kit updates and sandbox removal and recreation with the same name. This applies to sandboxes created with this version; existing sandbox records retain their previous storage behavior.
+- Creating a sandbox from a v3 kit set without a workload kit reports a clear explanation instead of "the kit set is not coherent."
+
+#### Sandbox lifecycle and workspaces
+
+- Host Git identity is copied into sandboxes for repositories that use the reftable ref format.
+- Sandboxes created with `--clone` preserve kit-provided workspace files and report clone initialization failures.
+- Canceling clone remote configuration preserves the cancellation error even if stopping Git also fails.
+
+#### Authentication and agents
+
+- Kiro IDE AWS IAM Identity Center sign-in callbacks reach the sandbox even when the callback port hasn't been published.
+- Claude sandboxes using subscription OAuth are provisioned without the API-key helper.
+
+#### Networking and policy
+
+- HTTP network rules support query-parameter restrictions. Repeat `--query name=value` to require multiple parameters.
+
+#### Cloud sandboxes
+
+- `sbx --cloud inspect <id|name>` shows details for a single cloud sandbox, including published port URLs. Use `--format json` or `--format yaml` for scripting.
+- Running `sbx --cloud run --name <name>` without an agent suggests the correct form: `sbx --cloud run <agent> --name <name>`.
+
+#### CLI and diagnostics
+
+- `sbx exec` returns exit status 125 when it cannot run the command, such as when the sandbox doesn't exist.
+- On macOS and Windows, `sbx diagnose` and daemon logs warn when `SSL_CERT_FILE` or `SSL_CERT_DIR` replaces the system trust store and can cause HTTPS certificate verification failures.
+
+#### Experimental Runtime backend
+
+- Workloads have network access.
+- Startup stops waiting and cleans up when a workload exits or fails before becoming ready.
+
+## 0.49.2
+
+{{< release-date date="2026-10-21" >}}
+
+[GitHub release](https://github.com/docker/sbx-releases/releases/tag/v0.49.2)
+
+### Highlights
+
+Docker Sandboxes 0.49.2 updates Go and bundled dependencies as part of Docker’s response to the [eMudhra certificate authority compromise](https://docs.docker.com/security/security-announcements/#docker-sandboxes-response-to-emudhra-ca-compromise).
+
+### Security updates
+
+- Updated Go to 1.27.3.
+- Updated bundled llmman to 0.1.571.
+
+### Recommended actions
+
+Updating the `sbx` CLI alone does not update existing sandboxes. Docker has also rebuilt the built-in template images with updated CA certificates.
+
+Follow one of the documented mitigation paths:
+
+- [Recreate sandboxes with refreshed images](https://docs.docker.com/security/security-announcements/#recreate-sandboxes-with-updated-images), using `--pull always`. Save any files and unpushed commits before removing a sandbox.
+- [Update CA certificates in existing sandboxes](https://docs.docker.com/security/security-announcements/#update-ca-certificates-in-existing-sandboxes), then restart applications. Tools that bundle their own CA certificates may require separate updates.
+
+See the [security advisory](https://docs.docker.com/security/security-announcements/#docker-sandboxes-response-to-emudhra-ca-compromise) for commands and guidance for custom templates.
+
 ## 0.49.1
 
 {{< release-date date="2026-10-20" >}}
@@ -228,66 +315,6 @@ Results go to stdout. Errors, warnings, corrective hints, daemon-start progress,
 - Shell completion scripts generate without starting telemetry, reducing generation time.
 - `sbx diagnose` checks for `mkfs.ext4`.
 
-## 0.47.0
-
-{{< release-date date="2026-10-05" >}}
-
-[GitHub release](https://github.com/docker/sbx-releases/releases/tag/v0.47.0)
-
-### Highlights
-
-Docker Sandboxes v0.47.0 adds automatic cleanup after agent sessions with `sbx run --rm` and a kit capability for keeping local sandboxes running after sessions disconnect.
-
-### What's new
-
-#### Security
-
-- Fixed OAuth token interception when a provider hostname uses different capitalization or a trailing dot, preventing real tokens from reaching the sandbox instead of the proxy's placeholders.
-- The proxy rejects unrecognized OAuth token grants and prevents their responses from replacing host-managed credentials. Supported in-sandbox sign-in flows remain available.
-- The proxy returns an error when it cannot safely mask a successful Anthropic API-key creation response, instead of forwarding the unmasked response to the sandbox.
-- Included since v0.46.0: fixed raw TCP connections to denied hostnames being permitted by an allow rule for the hostname's resolved IP address. This fix applies to TCP; the related UDP case with multiple tracked hostnames remains outside its scope.
-- Included since v0.45.0: CLI-created cloud hostname allowlists no longer gain implicit `0.0.0.0/0` and `::/0` rules. Existing stored policies are unchanged; remove those rules or recreate the policy to apply the restriction. Explicit IP and CIDR allowances remain supported.
-- The proxy rejects TLS handshakes that fill its inspection buffer before a complete ClientHello can be checked on a non-MITM CONNECT tunnel or during the transparent proxy's late handshake check.
-- The proxy closes incomplete TLS handshakes on those paths after a two-minute timeout instead of retaining the connections for the sandbox's lifetime.
-- Sandboxes reject UDP to multicast, link-local, and unspecified destinations, limited broadcast, and broadcast addresses derived from the host's interface prefixes, regardless of network policy. UDP to `host.docker.internal` is unaffected. Broadcast addresses configured outside that derivation and networks reachable only through routes are not covered by this check.
-- Kit pulls enforce limits on registry-declared blob sizes, decompressed content, and archive entry counts.
-
-#### Sandbox lifecycle and workspaces
-
-- `sbx run --rm` removes a local or cloud sandbox after its agent session ends. It cannot be combined with `--detached`. If a cloud session is interrupted, such as by a dropped connection, the sandbox is kept and the CLI prints the command to remove it.
-- Running `sbx run -d` against an existing local sandbox keeps it running after sessions disconnect, until you stop or remove it.
-- Dynamic mounts and permissions created through symlink paths can be removed without reappearing after a restart. Incompatible saved records include recovery guidance.
-
-#### Kits
-
-- Local kit inspection, validation, and pulling require the daemon to be running.
-- Kits can declare `com.docker.sandbox/long-running@1` to keep local sandboxes running after all sessions disconnect. Cloud sandboxes and `sbx kit add` cannot provide this capability: required entries are rejected, and optional entries are skipped.
-- `sbx kit sign` and `sbx kit push --sign` succeed on registries that refuse manifest deletion, including GitHub Container Registry and Docker Hub, instead of reporting failure after attaching the signature.
-- Adding a kit to a sandbox whose guest has stopped responding fails without leaving the sandbox unusable until the daemon restarts.
-
-#### Cloud sandboxes
-
-- `sbx --cloud ttl` reports stopped sandboxes as stopped instead of expired. The time-to-live restarts when the sandbox resumes. JSON output includes `stopped` and `ttl_paused`; while the sandbox is resuming, only `ttl_paused` is true.
-- Creating a cloud sandbox or moving a local sandbox to the cloud applies cloud policy and the kit's network rules without copying locally added network rules. Moving a sandbox with local HTTP method or path restrictions warns that those restrictions will not apply in the cloud.
-
-#### Settings and proxies
-
-- Upstream proxy recovery no longer blocks unrelated sandboxes or deletes isolated container data when credentials are unavailable. Local host services remain reachable.
-- `sbx settings set` rejects invalid upstream proxy values before saving them.
-
-#### MCP
-
-- MCP authorization requests `offline_access` when the server advertises it and authorization uses saved defaults or resource-required scopes, so the server can issue refresh tokens. Explicit `--scope` values are unchanged. Run `sbx mcp auth` again to obtain a grant with a refresh token for existing credentials.
-- Fixed MCP gateway availability in sandboxes created from the TUI and when connecting over SSH after a daemon restart or automatic sandbox creation.
-
-#### CLI and updates
-
-- `sbx env` reports the correct file, line, and column for unrecognized keys even when another entry in the file fails custom validation. Multiple validation errors appear on separate lines.
-- Help remains available when the settings directory is unwritable or local settings cannot be opened, with a warning instead of a panic.
-- Host-port collisions from `sbx ports --publish` identify the occupied binding and offer a retry with an automatically allocated port when safe.
-- Windows update notices appear only after WinGet confirms that the version is available in its catalog.
-<!-- release-notes:end -->
-
 <!-- END GENERATED RELEASES -->
 
 ## Earlier releases
diff --git a/content/manuals/ai/sandboxes/usage.md b/content/manuals/ai/sandboxes/usage.md
index 6864a99f9f..1f1a616b43 100644
--- a/content/manuals/ai/sandboxes/usage.md
+++ b/content/manuals/ai/sandboxes/usage.md
@@ -439,10 +439,15 @@ recipes, see
 
 While a sandbox exists, installed packages, Docker images, configuration
 changes, command history, and mountless workspace files all persist across
-stops and restarts. When you remove a sandbox, everything inside is deleted.
+stops and restarts. Removing a sandbox deletes its container filesystem.
 Host workspace files, including repositories used as clone sources, and the
-[shared agent skills store](workflows/agent-skills.md) remain on your host. To
-capture changes in the container filesystem, [save a template](#saving-a-sandbox-as-a-template).
+[shared agent skills store](workflows/agent-skills.md) remain on your host.
+Persistent kit volumes in local sandboxes also survive removal. See
+[Keep kit data when recreating a sandbox](customize/use-kits.md#keep-kit-data-when-recreating-a-sandbox)
+for how to reattach them.
+
+To capture changes in the container filesystem,
+[save a template](#saving-a-sandbox-as-a-template).
 For a reproducible environment defined in source,
 [author a kit](/manuals/ai/sandboxes/customize/author/_index.md).
 
diff --git a/content/manuals/ai/sandboxes/workflows/automation.md b/content/manuals/ai/sandboxes/workflows/automation.md
index 78567684a2..9e2ada04b2 100644
--- a/content/manuals/ai/sandboxes/workflows/automation.md
+++ b/content/manuals/ai/sandboxes/workflows/automation.md
@@ -54,6 +54,11 @@ CI provider's secret store, use `-t`. For example, in a GitHub Actions step:
 
 ## Cleanup and exit codes
 
+`sbx exec` returns the exit status of the command it runs. A failure to run
+the command, such as a missing sandbox, returns
+125. A missing executable inside a local sandbox returns 127. Check stderr
+for the cause before deciding whether to retry.
+
 Confirmations require terminal input. Piping an answer, such as `echo y`, does
 not confirm an operation. Use `--force` on commands that provide it to skip
 confirmation in scripts. `sbx kit builder history rm` uses `--yes` or `-y`
diff --git a/data/sbx_cli/sbx_cp.yaml b/data/sbx_cli/sbx_cp.yaml
index 690b3c9c6f..0571e6aacd 100644
--- a/data/sbx_cli/sbx_cp.yaml
+++ b/data/sbx_cli/sbx_cp.yaml
@@ -9,6 +9,10 @@ description: |-
     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
     as a directory, the source is placed inside it.
+
+    When a local path is inside a sandbox workspace, sbx cp refuses symbolic
+    links that lead out of the workspace, even with --follow-link, including
+    when the workspace is reached through a symbolic link or junction to it.
 usage: sbx cp SRC DST [flags]
 options:
     - name: follow-link
diff --git a/data/sbx_cli/sbx_create.yaml b/data/sbx_cli/sbx_create.yaml
index 0175c8e627..a98b3659dd 100644
--- a/data/sbx_cli/sbx_create.yaml
+++ b/data/sbx_cli/sbx_create.yaml
@@ -6,7 +6,10 @@ description: |-
     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.
+    paths such as ./my-kit or ../my-kit.zip. A kit.shortcuts.<agent> setting
+    (sbx settings set kit.shortcuts.claude sbx/claude:latest) makes that agent name
+    resolve to the configured kit reference instead for local sandboxes; cloud
+    sandboxes ignore it.
 
     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.
@@ -27,7 +30,8 @@ description: |-
     do not apply. Set cloud account defaults with
     "sbx --cloud policy init <allow-all|balanced|deny-all>".
 
-    Use "sbx --cloud run --name SANDBOX" to attach to the agent after creation.
+    Use "sbx --cloud run <agent> --name SANDBOX" to attach to the agent after
+    creation: cloud needs the agent, since a name alone is not a unique handle.
 usage: sbx create AGENT|SANDBOX_KIT [PATH...] [flags]
 options:
     - name: allow-network
@@ -79,6 +83,10 @@ options:
       shorthand: m
       usage: |
         Memory limit in binary units (e.g., 512m, 8g). Minimum: 512 MiB. Default: 50% of host memory, clamped to 512 MiB–32 GiB. Maximum: max(75% of host memory, 512 MiB)
+    - name: mount
+      default_value: '[]'
+      usage: |
+        Bind a host directory to a kit host-mount@1 path (can be repeated): HOST:SANDBOX_PATH. Can only be used when creating a new sandbox.
     - 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 (periods are rejected with --cloud); 'default' is reserved)
diff --git a/data/sbx_cli/sbx_create_claude.yaml b/data/sbx_cli/sbx_create_claude.yaml
index f9f9dd0754..fad4cb2fda 100644
--- a/data/sbx_cli/sbx_create_claude.yaml
+++ b/data/sbx_cli/sbx_create_claude.yaml
@@ -25,7 +25,8 @@ description: |-
     do not apply. Set cloud account defaults with
     "sbx --cloud policy init <allow-all|balanced|deny-all>".
 
-    Use "sbx --cloud run --name SANDBOX" to attach to the agent after creation.
+    Use "sbx --cloud run <agent> --name SANDBOX" to attach to the agent after
+    creation: cloud needs the agent, since a name alone is not a unique handle.
 usage: sbx create claude [PATH...] [flags]
 options:
     - name: help
@@ -86,6 +87,10 @@ inherited_options:
       shorthand: m
       usage: |
         Memory limit in binary units (e.g., 512m, 8g). Minimum: 512 MiB. Default: 50% of host memory, clamped to 512 MiB–32 GiB. Maximum: max(75% of host memory, 512 MiB)
+    - name: mount
+      default_value: '[]'
+      usage: |
+        Bind a host directory to a kit host-mount@1 path (can be repeated): HOST:SANDBOX_PATH. Can only be used when creating a new sandbox.
     - 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 (periods are rejected with --cloud); 'default' is reserved)
diff --git a/data/sbx_cli/sbx_create_codex.yaml b/data/sbx_cli/sbx_create_codex.yaml
index a9d9290877..18fe957198 100644
--- a/data/sbx_cli/sbx_create_codex.yaml
+++ b/data/sbx_cli/sbx_create_codex.yaml
@@ -25,7 +25,8 @@ description: |-
     do not apply. Set cloud account defaults with
     "sbx --cloud policy init <allow-all|balanced|deny-all>".
 
-    Use "sbx --cloud run --name SANDBOX" to attach to the agent after creation.
+    Use "sbx --cloud run <agent> --name SANDBOX" to attach to the agent after
+    creation: cloud needs the agent, since a name alone is not a unique handle.
 usage: sbx create codex [PATH...] [flags]
 options:
     - name: help
@@ -86,6 +87,10 @@ inherited_options:
       shorthand: m
       usage: |
         Memory limit in binary units (e.g., 512m, 8g). Minimum: 512 MiB. Default: 50% of host memory, clamped to 512 MiB–32 GiB. Maximum: max(75% of host memory, 512 MiB)
+    - name: mount
+      default_value: '[]'
+      usage: |
+        Bind a host directory to a kit host-mount@1 path (can be repeated): HOST:SANDBOX_PATH. Can only be used when creating a new sandbox.
     - 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 (periods are rejected with --cloud); 'default' is reserved)
diff --git a/data/sbx_cli/sbx_create_cursor.yaml b/data/sbx_cli/sbx_create_cursor.yaml
index 24a097f387..d60eef56e8 100644
--- a/data/sbx_cli/sbx_create_cursor.yaml
+++ b/data/sbx_cli/sbx_create_cursor.yaml
@@ -25,7 +25,8 @@ description: |-
     do not apply. Set cloud account defaults with
     "sbx --cloud policy init <allow-all|balanced|deny-all>".
 
-    Use "sbx --cloud run --name SANDBOX" to attach to the agent after creation.
+    Use "sbx --cloud run <agent> --name SANDBOX" to attach to the agent after
+    creation: cloud needs the agent, since a name alone is not a unique handle.
 usage: sbx create cursor [PATH...] [flags]
 options:
     - name: help
@@ -86,6 +87,10 @@ inherited_options:
       shorthand: m
       usage: |
         Memory limit in binary units (e.g., 512m, 8g). Minimum: 512 MiB. Default: 50% of host memory, clamped to 512 MiB–32 GiB. Maximum: max(75% of host memory, 512 MiB)
+    - name: mount
+      default_value: '[]'
+      usage: |
+        Bind a host directory to a kit host-mount@1 path (can be repeated): HOST:SANDBOX_PATH. Can only be used when creating a new sandbox.
     - 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 (periods are rejected with --cloud); 'default' is reserved)
diff --git a/data/sbx_cli/sbx_create_devin.yaml b/data/sbx_cli/sbx_create_devin.yaml
index bc76d62859..3676ffcbfc 100644
--- a/data/sbx_cli/sbx_create_devin.yaml
+++ b/data/sbx_cli/sbx_create_devin.yaml
@@ -25,7 +25,8 @@ description: |-
     do not apply. Set cloud account defaults with
     "sbx --cloud policy init <allow-all|balanced|deny-all>".
 
-    Use "sbx --cloud run --name SANDBOX" to attach to the agent after creation.
+    Use "sbx --cloud run <agent> --name SANDBOX" to attach to the agent after
+    creation: cloud needs the agent, since a name alone is not a unique handle.
 usage: sbx create devin [PATH...] [flags]
 options:
     - name: help
@@ -86,6 +87,10 @@ inherited_options:
       shorthand: m
       usage: |
         Memory limit in binary units (e.g., 512m, 8g). Minimum: 512 MiB. Default: 50% of host memory, clamped to 512 MiB–32 GiB. Maximum: max(75% of host memory, 512 MiB)
+    - name: mount
+      default_value: '[]'
+      usage: |
+        Bind a host directory to a kit host-mount@1 path (can be repeated): HOST:SANDBOX_PATH. Can only be used when creating a new sandbox.
     - 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 (periods are rejected with --cloud); 'default' is reserved)
diff --git a/data/sbx_cli/sbx_create_docker-agent.yaml b/data/sbx_cli/sbx_create_docker-agent.yaml
index f336967fe1..48e55de89f 100644
--- a/data/sbx_cli/sbx_create_docker-agent.yaml
+++ b/data/sbx_cli/sbx_create_docker-agent.yaml
@@ -25,7 +25,8 @@ description: |-
     do not apply. Set cloud account defaults with
     "sbx --cloud policy init <allow-all|balanced|deny-all>".
 
-    Use "sbx --cloud run --name SANDBOX" to attach to the agent after creation.
+    Use "sbx --cloud run <agent> --name SANDBOX" to attach to the agent after
+    creation: cloud needs the agent, since a name alone is not a unique handle.
 usage: sbx create docker-agent [PATH...] [flags]
 options:
     - name: help
@@ -86,6 +87,10 @@ inherited_options:
       shorthand: m
       usage: |
         Memory limit in binary units (e.g., 512m, 8g). Minimum: 512 MiB. Default: 50% of host memory, clamped to 512 MiB–32 GiB. Maximum: max(75% of host memory, 512 MiB)
+    - name: mount
+      default_value: '[]'
+      usage: |
+        Bind a host directory to a kit host-mount@1 path (can be repeated): HOST:SANDBOX_PATH. Can only be used when creating a new sandbox.
     - 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 (periods are rejected with --cloud); 'default' is reserved)
diff --git a/data/sbx_cli/sbx_create_gemini.yaml b/data/sbx_cli/sbx_create_gemini.yaml
index 22d2afa7f2..0697a2554e 100644
--- a/data/sbx_cli/sbx_create_gemini.yaml
+++ b/data/sbx_cli/sbx_create_gemini.yaml
@@ -25,7 +25,8 @@ description: |-
     do not apply. Set cloud account defaults with
     "sbx --cloud policy init <allow-all|balanced|deny-all>".
 
-    Use "sbx --cloud run --name SANDBOX" to attach to the agent after creation.
+    Use "sbx --cloud run <agent> --name SANDBOX" to attach to the agent after
+    creation: cloud needs the agent, since a name alone is not a unique handle.
 usage: sbx create gemini [PATH...] [flags]
 options:
     - name: help
@@ -86,6 +87,10 @@ inherited_options:
       shorthand: m
       usage: |
         Memory limit in binary units (e.g., 512m, 8g). Minimum: 512 MiB. Default: 50% of host memory, clamped to 512 MiB–32 GiB. Maximum: max(75% of host memory, 512 MiB)
+    - name: mount
+      default_value: '[]'
+      usage: |
+        Bind a host directory to a kit host-mount@1 path (can be repeated): HOST:SANDBOX_PATH. Can only be used when creating a new sandbox.
     - 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 (periods are rejected with --cloud); 'default' is reserved)
diff --git a/data/sbx_cli/sbx_create_opencode.yaml b/data/sbx_cli/sbx_create_opencode.yaml
index 4365a06f8a..dea8467b16 100644
--- a/data/sbx_cli/sbx_create_opencode.yaml
+++ b/data/sbx_cli/sbx_create_opencode.yaml
@@ -25,7 +25,8 @@ description: |-
     do not apply. Set cloud account defaults with
     "sbx --cloud policy init <allow-all|balanced|deny-all>".
 
-    Use "sbx --cloud run --name SANDBOX" to attach to the agent after creation.
+    Use "sbx --cloud run <agent> --name SANDBOX" to attach to the agent after
+    creation: cloud needs the agent, since a name alone is not a unique handle.
 usage: sbx create opencode [PATH...] [flags]
 options:
     - name: help
@@ -86,6 +87,10 @@ inherited_options:
       shorthand: m
       usage: |
         Memory limit in binary units (e.g., 512m, 8g). Minimum: 512 MiB. Default: 50% of host memory, clamped to 512 MiB–32 GiB. Maximum: max(75% of host memory, 512 MiB)
+    - name: mount
+      default_value: '[]'
+      usage: |
+        Bind a host directory to a kit host-mount@1 path (can be repeated): HOST:SANDBOX_PATH. Can only be used when creating a new sandbox.
     - 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 (periods are rejected with --cloud); 'default' is reserved)
diff --git a/data/sbx_cli/sbx_create_shell.yaml b/data/sbx_cli/sbx_create_shell.yaml
index 4f50e5ce11..66eb2ca7df 100644
--- a/data/sbx_cli/sbx_create_shell.yaml
+++ b/data/sbx_cli/sbx_create_shell.yaml
@@ -25,7 +25,8 @@ description: |-
     do not apply. Set cloud account defaults with
     "sbx --cloud policy init <allow-all|balanced|deny-all>".
 
-    Use "sbx --cloud run --name SANDBOX" to attach to the agent after creation.
+    Use "sbx --cloud run <agent> --name SANDBOX" to attach to the agent after
+    creation: cloud needs the agent, since a name alone is not a unique handle.
 usage: sbx create shell [PATH...] [flags]
 options:
     - name: help
@@ -86,6 +87,10 @@ inherited_options:
       shorthand: m
       usage: |
         Memory limit in binary units (e.g., 512m, 8g). Minimum: 512 MiB. Default: 50% of host memory, clamped to 512 MiB–32 GiB. Maximum: max(75% of host memory, 512 MiB)
+    - name: mount
+      default_value: '[]'
+      usage: |
+        Bind a host directory to a kit host-mount@1 path (can be repeated): HOST:SANDBOX_PATH. Can only be used when creating a new sandbox.
     - 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 (periods are rejected with --cloud); 'default' is reserved)
diff --git a/data/sbx_cli/sbx_env.yaml b/data/sbx_cli/sbx_env.yaml
index b7056de720..3be78a1ff8 100644
--- a/data/sbx_cli/sbx_env.yaml
+++ b/data/sbx_cli/sbx_env.yaml
@@ -10,9 +10,15 @@ description: |-
     exec to run a command, and rm to remove it and its provisioned secrets.
     Use plan to preview changes. Changes require approval; --force skips the prompt.
 
-    Lifecycle commands and command-based secrets execute on the host with your
-    permissions. Keep secret helpers and their dependencies outside writable
-    sandbox mounts, and use absolute helper paths.
+    Lifecycle commands, command-based secrets, and command-backed MCP servers execute
+    on the host with your permissions. Keep secret helpers and their dependencies
+    outside writable sandbox mounts, and use absolute helper paths.
+
+    MCP command approval persists across sandbox and daemon restarts. Use
+    --skip-host-commands to skip lifecycle commands and disable owned host MCP
+    commands until a later "sbx env run" without the flag. If initialize creates
+    a missing MCP executable or changes its resolved path, a second approval is
+    required before registration or sandbox creation.
 
     The environment file is mounted read-only by default when shared with the
     sandbox. Set sandboxOptions.writableEnvFiles only when you trust the agent
diff --git a/data/sbx_cli/sbx_env_create.yaml b/data/sbx_cli/sbx_env_create.yaml
index 6d5aa1c4e0..360f15c53d 100644
--- a/data/sbx_cli/sbx_env_create.yaml
+++ b/data/sbx_cli/sbx_env_create.yaml
@@ -59,7 +59,8 @@ options:
         What happens when --ttl lapses: 'stop' stops the sandbox in place so it can be started again later, 'restart' keeps it running by stopping and immediately starting it, or 'delete' removes it. Omit the flag and the server stops the sandbox when it can be started again later, and deletes it otherwise. With 'restart' a supplied --ttl must be at least 1h (cloud only). Only applies when the sandbox is created; 'sbx --cloud env run' refuses it when attaching to an existing one.
     - name: skip-host-commands
       default_value: "false"
-      usage: Skip the host lifecycle commands the environment declares
+      usage: |
+        Skip host lifecycle commands and disable environment MCP commands until a later env run without this flag
     - name: ttl
       usage: |
         Cloud sandbox time-to-live before it times out (e.g. 30m, 2h, 1h30m; units are case-insensitive; cloud only; default: server-side). Only applies when the sandbox is created; 'sbx --cloud env run' refuses it when attaching to an existing one
diff --git a/data/sbx_cli/sbx_env_exec.yaml b/data/sbx_cli/sbx_env_exec.yaml
index 7820785b42..21b3d2f086 100644
--- a/data/sbx_cli/sbx_env_exec.yaml
+++ b/data/sbx_cli/sbx_env_exec.yaml
@@ -19,6 +19,10 @@ description: |-
     lists such as ports and mcp.servers are concatenated.
 
     Flags match the behavior of "sbx exec".
+
+    Exit status is that of the command. sbx exits 125 if it could not run the command,
+    for example because the sandbox does not exist. A missing command exits 127,
+    unless a cloud backend reports it as an error rather than a status, which exits 125.
 usage: sbx env exec [flags] [PATH...] -- COMMAND [ARG...]
 options:
     - name: detach
diff --git a/data/sbx_cli/sbx_env_plan.yaml b/data/sbx_cli/sbx_env_plan.yaml
index 043fc49c66..78e77fec02 100644
--- a/data/sbx_cli/sbx_env_plan.yaml
+++ b/data/sbx_cli/sbx_env_plan.yaml
@@ -57,7 +57,7 @@ options:
     - name: skip-host-commands
       default_value: "false"
       usage: |
-        Plan without the host lifecycle commands the environment declares
+        Plan without the host lifecycle commands and command-backed MCP servers the environment declares
 inherited_options:
     - name: cloud
       default_value: "false"
diff --git a/data/sbx_cli/sbx_env_rm.yaml b/data/sbx_cli/sbx_env_rm.yaml
index 6a9ca0e422..5179dfabec 100644
--- a/data/sbx_cli/sbx_env_rm.yaml
+++ b/data/sbx_cli/sbx_env_rm.yaml
@@ -47,7 +47,8 @@ options:
         Also remove this environment's bindings from the global credentials.yaml
     - name: skip-host-commands
       default_value: "false"
-      usage: Skip the host lifecycle commands the environment declares
+      usage: |
+        Skip host preRemove commands and disable owned host MCP commands; successful environment removal deletes their registrations
 inherited_options:
     - name: cloud
       default_value: "false"
diff --git a/data/sbx_cli/sbx_env_run.yaml b/data/sbx_cli/sbx_env_run.yaml
index 28328857d7..ea860c14db 100644
--- a/data/sbx_cli/sbx_env_run.yaml
+++ b/data/sbx_cli/sbx_env_run.yaml
@@ -64,7 +64,8 @@ options:
         What happens when --ttl lapses: 'stop' stops the sandbox in place so it can be started again later, 'restart' keeps it running by stopping and immediately starting it, or 'delete' removes it. Omit the flag and the server stops the sandbox when it can be started again later, and deletes it otherwise. With 'restart' a supplied --ttl must be at least 1h (cloud only). Only applies when the sandbox is created; 'sbx --cloud env run' refuses it when attaching to an existing one.
     - name: skip-host-commands
       default_value: "false"
-      usage: Skip the host lifecycle commands the environment declares
+      usage: |
+        Skip host lifecycle commands and disable environment MCP commands until a later env run without this flag
     - name: ttl
       usage: |
         Cloud sandbox time-to-live before it times out (e.g. 30m, 2h, 1h30m; units are case-insensitive; cloud only; default: server-side). Only applies when the sandbox is created; 'sbx --cloud env run' refuses it when attaching to an existing one
diff --git a/data/sbx_cli/sbx_exec.yaml b/data/sbx_cli/sbx_exec.yaml
index c2f0809b49..0fe08e438b 100644
--- a/data/sbx_cli/sbx_exec.yaml
+++ b/data/sbx_cli/sbx_exec.yaml
@@ -8,6 +8,10 @@ description: |-
     is not supported. Some flags (-d, --user, --privileged)
     are not supported with --cloud and are rejected rather than silently ignored.
     --detach-keys applies only to an interactive (-i/-t) cloud exec.
+
+    Exit status is that of the command. sbx exits 125 if it could not run the command,
+    for example because the sandbox does not exist. A missing command exits 127,
+    unless a cloud backend reports it as an error rather than a status, which exits 125.
 usage: sbx exec [flags] SANDBOX COMMAND [ARG...]
 options:
     - name: detach
diff --git a/data/sbx_cli/sbx_kit_builder.yaml b/data/sbx_cli/sbx_kit_builder.yaml
index 3522f048b4..aa075f69a7 100644
--- a/data/sbx_cli/sbx_kit_builder.yaml
+++ b/data/sbx_cli/sbx_kit_builder.yaml
@@ -6,7 +6,7 @@ description: |-
 
     Source-form kit builds (a local directory or git reference) run inside a
     shared builder sandbox named sbx-kit-builder, created on first
-    use. Its Docker engine store doubles as the kit build cache, so removing
+    use. Its Docker Engine store doubles as the kit build cache, so removing
     the builder is how the cache is reclaimed; the next source-form build
     recreates it.
 usage: sbx kit builder COMMAND
diff --git a/data/sbx_cli/sbx_kit_builder_history.yaml b/data/sbx_cli/sbx_kit_builder_history.yaml
index 5811b4fb0c..50c15f1512 100644
--- a/data/sbx_cli/sbx_kit_builder_history.yaml
+++ b/data/sbx_cli/sbx_kit_builder_history.yaml
@@ -5,7 +5,7 @@ description: |-
     Inspect kit build history in the builder sandbox.
 
     Each subcommand runs the matching docker buildx history command inside
-    the builder sandbox, against the buildx instance kit builds use. Flags
+    the builder sandbox, against the Buildx instance kit builds use. Flags
     and arguments pass through verbatim.
 usage: sbx kit builder history COMMAND
 options:
diff --git a/data/sbx_cli/sbx_kit_builder_history_rm.yaml b/data/sbx_cli/sbx_kit_builder_history_rm.yaml
index 91be46bedd..07f2d1b42b 100644
--- a/data/sbx_cli/sbx_kit_builder_history_rm.yaml
+++ b/data/sbx_cli/sbx_kit_builder_history_rm.yaml
@@ -10,8 +10,7 @@ options:
     - name: "yes"
       shorthand: "y"
       default_value: "false"
-      usage: |
-        Skip confirmation prompt (buildx --force still controls running build records)
+      usage: Skip confirmation prompt
 inherited_options:
     - name: cloud
       default_value: "false"
diff --git a/data/sbx_cli/sbx_mcp_rm.yaml b/data/sbx_cli/sbx_mcp_rm.yaml
index c0b76ed0ce..4d318ff070 100644
--- a/data/sbx_cli/sbx_mcp_rm.yaml
+++ b/data/sbx_cli/sbx_mcp_rm.yaml
@@ -1,5 +1,15 @@
 name: sbx mcp rm
 synopsis: Remove a registered MCP server
+description: |-
+    Remove a registered MCP server and its OAuth credential.
+
+    Use --registration-only to remove the local registration without starting the
+    daemon or accessing credentials. This also removes the registration's saved
+    environment ownership and approval, including damaged or orphaned registrations. Stored credentials are
+    kept, and MCP processes already running in sandbox gateways are not stopped.
+    For an untrusted registration, first stop the selected daemon; this interrupts
+    all of its sandbox gateways. A later approved env run can register a declared
+    server again.
 usage: sbx mcp rm NAME [flags]
 options:
     - name: force
@@ -10,6 +20,10 @@ options:
       shorthand: h
       default_value: "false"
       usage: help for rm
+    - name: registration-only
+      default_value: "false"
+      usage: |
+        Remove only the local registration without starting the daemon; keep credentials and running MCP processes
 inherited_options:
     - name: cloud
       default_value: "false"
@@ -19,6 +33,8 @@ inherited_options:
       shorthand: D
       default_value: "false"
       usage: Enable debug logging
-example: '  sbx mcp rm notion'
+example: |4-
+      sbx mcp rm notion
+      sbx mcp rm --registration-only notion
 see_also:
     - sbx mcp - Manage MCP servers
diff --git a/data/sbx_cli/sbx_policy_allow_network.yaml b/data/sbx_cli/sbx_policy_allow_network.yaml
index bf6af7e762..5129e9f1ad 100644
--- a/data/sbx_cli/sbx_policy_allow_network.yaml
+++ b/data/sbx_cli/sbx_policy_allow_network.yaml
@@ -16,15 +16,30 @@ description: |-
 
     The rule applies globally to all sandboxes by default. Use --sandbox to add
     the rule to policy "local" scoped to a single sandbox instead.
+
+    Use --method to add an HTTP rule. --method accepts comma-separated HTTP
+    methods or ANY; --path defaults to /**. Repeat --query name=value to require
+    query parameters.
 usage: sbx policy allow network [--sandbox SANDBOX] RESOURCES [flags]
 options:
     - name: help
       shorthand: h
       default_value: "false"
       usage: help for network
+    - name: method
+      default_value: '[]'
+      usage: |
+        Restrict the rule to these HTTP methods (comma-separated); use ANY to match all methods
+    - name: path
+      usage: |
+        Restrict the rule to this HTTP path glob (e.g. /repos/**); defaults to /**
     - name: protocol
       usage: |
         Network protocol: tcp or udp; repeat or comma-separate for both
+    - name: query
+      default_value: '[]'
+      usage: |
+        Require an HTTP query parameter (name=value pattern); repeatable
     - name: sandbox
       usage: |
         Scope the rule to a specific sandbox (default: all sandboxes)
@@ -52,5 +67,8 @@ example: |4-
 
       # Allow all outbound traffic on both transports
       sbx policy allow network --protocol tcp,udp "**"
+
+      # Allow GET and HEAD requests to a path
+      sbx policy allow network api.example.com --method GET,HEAD --path '/v1/**'
 see_also:
     - sbx policy allow - Add an allow rule for sandboxes
diff --git a/data/sbx_cli/sbx_policy_deny_network.yaml b/data/sbx_cli/sbx_policy_deny_network.yaml
index 558a9bd6b1..672ee4e551 100644
--- a/data/sbx_cli/sbx_policy_deny_network.yaml
+++ b/data/sbx_cli/sbx_policy_deny_network.yaml
@@ -12,15 +12,30 @@ description: |-
 
     The rule applies globally to all sandboxes by default. Use --sandbox to add
     the rule to policy "local" scoped to a single sandbox instead.
+
+    Use --method to add an HTTP rule. --method accepts comma-separated HTTP
+    methods or ANY; --path defaults to /**. Repeat --query name=value to require
+    query parameters.
 usage: sbx policy deny network [--sandbox SANDBOX] RESOURCES [flags]
 options:
     - name: help
       shorthand: h
       default_value: "false"
       usage: help for network
+    - name: method
+      default_value: '[]'
+      usage: |
+        Restrict the rule to these HTTP methods (comma-separated); use ANY to match all methods
+    - name: path
+      usage: |
+        Restrict the rule to this HTTP path glob (e.g. /repos/**); defaults to /**
     - name: protocol
       usage: |
         Restrict the rule to one protocol: tcp or udp (default tcp,udp)
+    - name: query
+      default_value: '[]'
+      usage: |
+        Require an HTTP query parameter (name=value pattern); repeatable
     - name: sandbox
       usage: |
         Scope the rule to a specific sandbox (default: all sandboxes)
@@ -45,5 +60,8 @@ example: |4-
 
       # Block only UDP to a host
       sbx policy deny network --protocol udp media.example.com
+
+      # Block POST requests to a path
+      sbx policy deny network api.example.com --method POST --path '/admin/**'
 see_also:
     - sbx policy deny - Add a deny rule for sandboxes
diff --git a/data/sbx_cli/sbx_policy_inspect.yaml b/data/sbx_cli/sbx_policy_inspect.yaml
index 2a1bda3d73..5b2742d74e 100644
--- a/data/sbx_cli/sbx_policy_inspect.yaml
+++ b/data/sbx_cli/sbx_policy_inspect.yaml
@@ -7,7 +7,7 @@ description: |-
     Selecting a policy lists every resource with its decision, rule, and status,
     plus a rule table showing each rule's RULE_ID, whether it is editable, and
     either the exact removal command or the reason it is read-only. Selecting a
-    rule shows just that rule with the same editability detail. RULE_ID is the
+    rule shows only that rule with the same editability detail. RULE_ID is the
     identifier accepted by "sbx policy rm network --id" (local rules only). Use
     "sbx policy ls" to find policy names and "sbx policy ls --wide" to find rule
     IDs and resource values.
diff --git a/data/sbx_cli/sbx_policy_ls.yaml b/data/sbx_cli/sbx_policy_ls.yaml
index 491d9b8328..3fc5e36aa2 100644
--- a/data/sbx_cli/sbx_policy_ls.yaml
+++ b/data/sbx_cli/sbx_policy_ls.yaml
@@ -46,7 +46,7 @@ options:
     - name: type
       default_value: all
       usage: |
-        Filter policies by type: "all", "network", "filesystem" (default "all")
+        Filter policies by type: "all", "network", "http", "filesystem" (default "all")
     - name: wide
       default_value: "false"
       usage: Show detailed rule-level output with rule IDs and resources
diff --git a/data/sbx_cli/sbx_policy_rm_network.yaml b/data/sbx_cli/sbx_policy_rm_network.yaml
index e472817bf3..9091ad6c33 100644
--- a/data/sbx_cli/sbx_policy_rm_network.yaml
+++ b/data/sbx_cli/sbx_policy_rm_network.yaml
@@ -15,6 +15,10 @@ description: |-
     "sbx policy ls --json" for the filtered rules; network values are printed in
     the form the CLI accepts back.
 
+    Use --method to add an HTTP rule. --method accepts comma-separated HTTP
+    methods or ANY; --path defaults to /**. Repeat --query name=value to require
+    query parameters.
+
     With --cloud:
     Remove a cloud network rule by pattern.
 
@@ -34,6 +38,17 @@ options:
       usage: help for network
     - name: id
       usage: Remove by rule ID
+    - name: method
+      default_value: '[]'
+      usage: |
+        Restrict the rule to these HTTP methods (comma-separated); use ANY to match all methods
+    - name: path
+      usage: |
+        Restrict the rule to this HTTP path glob (e.g. /repos/**); defaults to /**
+    - name: query
+      default_value: '[]'
+      usage: |
+        Require an HTTP query parameter (name=value pattern); repeatable
     - name: resource
       usage: Remove by resource value(s), comma-separated
     - name: sandbox
@@ -61,6 +76,9 @@ example: |4-
       # Remove a sandbox-scoped rule by resource
       sbx policy rm network --sandbox my-sandbox --resource api.example.com
 
+      # Remove an HTTP rule by resource, method, and path
+      sbx policy rm network --resource api.example.com --method GET --path '/v1/**'
+
       # Remove a cloud rule by pattern, from the allow or deny list it is in
       sbx --cloud policy rm network --resource api.example.com
 
diff --git a/data/sbx_cli/sbx_rm.yaml b/data/sbx_cli/sbx_rm.yaml
index 9f39eed20f..7a0759a307 100644
--- a/data/sbx_cli/sbx_rm.yaml
+++ b/data/sbx_cli/sbx_rm.yaml
@@ -1,12 +1,14 @@
 name: sbx rm
 synopsis: Remove one or more sandboxes
 description: |-
-    Remove one or more sandboxes and all associated resources. Or — with --cloud — the cloud sandbox
+    Remove one or more sandboxes. Or — with --cloud — the cloud sandbox
     ID (sbx_*) or name from "sbx --cloud ls".
 
     For local sandboxes, stops them, removes their containers, cleans up any Git
     worktrees, deletes sandbox state, and deletes secrets scoped to each removed
-    sandbox. This action cannot be undone. With --cloud, deletes
+    sandbox. Host-mount directories and persistent volume@1 storage created with
+    retention support are kept; creating the same sandbox name with the same kit
+    reattaches its persistent volumes. This action cannot be undone. With --cloud, deletes
     the sandbox in Docker Sandboxes Cloud. This action cannot be undone. Once the
     server accepts the request, rm waits up to 60 seconds per sandbox for the
     deletion. A removal still completing after that exits 0. Verify it later with
diff --git a/data/sbx_cli/sbx_run.yaml b/data/sbx_cli/sbx_run.yaml
index 6c331411d0..621d60dbda 100644
--- a/data/sbx_cli/sbx_run.yaml
+++ b/data/sbx_cli/sbx_run.yaml
@@ -7,7 +7,10 @@ description: |-
     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; bare values
-    retain their agent or sandbox-name meaning. To re-attach to an existing sandbox
+    retain their agent or sandbox-name meaning. A kit.shortcuts.<agent> setting (sbx
+    settings set kit.shortcuts.claude sbx/claude:latest) makes that agent name
+    resolve to the configured kit reference instead for local sandboxes; cloud
+    sandboxes ignore it. To re-attach to an existing sandbox
     by name, use --name; the agent positional is optional when the named sandbox
     already exists and is read from its spec.
 
@@ -107,6 +110,10 @@ options:
       shorthand: m
       usage: |
         Memory limit in binary units (e.g., 512m, 8g). Minimum: 512 MiB. Default: 50% of host memory, clamped to 512 MiB–32 GiB. Maximum: max(75% of host memory, 512 MiB)
+    - name: mount
+      default_value: '[]'
+      usage: |
+        Bind a host directory to a kit host-mount@1 path (can be repeated): HOST:SANDBOX_PATH. Can only be used when creating a new sandbox.
     - name: name
       usage: 'Name for the sandbox (default: <agent>-<workdir>)'
     - name: new