nprasad2077/docker-docs
1
0 Fork 0
mirror of https://github.com/docker/docs.git synced 2026-11-04 10:01:00 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: cover sbx 0.50 user-facing changes (#26449)

Browse Source 
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
This commit is contained in:
David Karlsson authored and GitHub committed 2026-10-26 17:28:15 +01:00
1 parent 419ecb4718
commit c572cdcb54
39 files changed
+497 -137
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

content/manuals/ai/sandboxes/cloud/usage.md
+14
View File
@@ -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:
content/manuals/ai/sandboxes/configuration/environment-files.md
+94 -24
View File
@@ -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
content/manuals/ai/sandboxes/customize/author/capabilities.md
+2 -3
View File
@@ -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
content/manuals/ai/sandboxes/customize/author/patterns.md
+16 -7
View File
@@ -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.
content/manuals/ai/sandboxes/customize/use-kits.md
+49
View File
@@ -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
content/manuals/ai/sandboxes/governance/access-controls/local.md
+17 -3
View File
@@ -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
```
content/manuals/ai/sandboxes/governance/access-controls/network.md
+3 -3
View File
@@ -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
content/manuals/ai/sandboxes/governance/concepts.md
+28 -7
View File
@@ -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,
content/manuals/ai/sandboxes/release-notes.md
+87 -60
View File
@@ -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
content/manuals/ai/sandboxes/usage.md
+8 -3
View File
@@ -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).
content/manuals/ai/sandboxes/workflows/automation.md
+5
View File
@@ -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`
data/sbx_cli/sbx_cp.yaml
+4
View File
@@ -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
data/sbx_cli/sbx_create.yaml
+10 -2
View File
@@ -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)
data/sbx_cli/sbx_create_claude.yaml
+6 -1
View File
@@ -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)
data/sbx_cli/sbx_create_codex.yaml
+6 -1
View File
@@ -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)
data/sbx_cli/sbx_create_cursor.yaml
+6 -1
View File
@@ -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)
data/sbx_cli/sbx_create_devin.yaml
+6 -1
View File
@@ -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)
data/sbx_cli/sbx_create_docker-agent.yaml
+6 -1
View File
@@ -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)
data/sbx_cli/sbx_create_gemini.yaml
+6 -1
View File
@@ -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)
data/sbx_cli/sbx_create_opencode.yaml
+6 -1
View File
@@ -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)
data/sbx_cli/sbx_create_shell.yaml
+6 -1
View File
@@ -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)
data/sbx_cli/sbx_env.yaml
+9 -3
View File
@@ -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
data/sbx_cli/sbx_env_create.yaml
+2 -1
View File
@@ -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
data/sbx_cli/sbx_env_exec.yaml
+4
View File
@@ -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
data/sbx_cli/sbx_env_plan.yaml
+1 -1
View File
@@ -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"
data/sbx_cli/sbx_env_rm.yaml
+2 -1
View File
@@ -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"
data/sbx_cli/sbx_env_run.yaml
+2 -1
View File
@@ -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
data/sbx_cli/sbx_exec.yaml
+4
View File
@@ -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
data/sbx_cli/sbx_kit_builder.yaml
+1 -1
View File
@@ -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
data/sbx_cli/sbx_kit_builder_history.yaml
+1 -1
View File
@@ -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:
data/sbx_cli/sbx_kit_builder_history_rm.yaml
+1 -2
View File
@@ -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"
data/sbx_cli/sbx_mcp_rm.yaml
+17 -1
View File
@@ -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
data/sbx_cli/sbx_policy_allow_network.yaml
+18
View File
@@ -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
data/sbx_cli/sbx_policy_deny_network.yaml
+18
View File
@@ -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
data/sbx_cli/sbx_policy_inspect.yaml
+1 -1
View File
@@ -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.
data/sbx_cli/sbx_policy_ls.yaml
+1 -1
View File
@@ -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
data/sbx_cli/sbx_policy_rm_network.yaml
+18
View File
@@ -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
data/sbx_cli/sbx_rm.yaml
+4 -2
View File
@@ -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
data/sbx_cli/sbx_run.yaml
+8 -1
View File
@@ -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