docker/docs
1
0
Fork 0
mirror of https://github.com/docker/docs.git synced 2026-10-23 18:09:02 +03:00
Code Activity

docs: vendor Sandboxes v0.49 CLI reference

Browse Source 
Copy docs/yml/*.yaml from docker/sandboxes release/v0.49 at c5b19951af121b439800029695f88bf1139a0b0b into data/sbx_cli without local edits.
This commit is contained in:
David Karlsson
2026-10-20 11:06:24 +00:00
parent e1fe509582
commit a1e520f672
32 changed files with 220 additions and 615 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
data/sbx_cli/sbx_create.yaml
View File

@@ -88,6 +88,9 @@ options:
- name: on-timeout
usage: |
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).
- name: platform
usage: |
Target platform: linux/amd64 or linux/arm64 (cloud only). With --image-ref, omitting it lets the server resolve the platform from the image and the CLI sends the local CPU as a hint for multi-platform images. With --template, omitting it inherits the template platform. With a sandbox kit, the kit's template is built for this platform and cached apart from other platforms; omitting it keeps the server's choice.
- name: publish
shorthand: p
default_value: '[]'

3
data/sbx_cli/sbx_create_claude.yaml
View File

@@ -95,6 +95,9 @@ inherited_options:
- name: on-timeout
usage: |
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).
- name: platform
usage: |
Target platform: linux/amd64 or linux/arm64 (cloud only). With --image-ref, omitting it lets the server resolve the platform from the image and the CLI sends the local CPU as a hint for multi-platform images. With --template, omitting it inherits the template platform. With a sandbox kit, the kit's template is built for this platform and cached apart from other platforms; omitting it keeps the server's choice.
- name: publish
shorthand: p
default_value: '[]'

3
data/sbx_cli/sbx_create_codex.yaml
View File

@@ -95,6 +95,9 @@ inherited_options:
- name: on-timeout
usage: |
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).
- name: platform
usage: |
Target platform: linux/amd64 or linux/arm64 (cloud only). With --image-ref, omitting it lets the server resolve the platform from the image and the CLI sends the local CPU as a hint for multi-platform images. With --template, omitting it inherits the template platform. With a sandbox kit, the kit's template is built for this platform and cached apart from other platforms; omitting it keeps the server's choice.
- name: publish
shorthand: p
default_value: '[]'

3
data/sbx_cli/sbx_create_cursor.yaml
View File

@@ -95,6 +95,9 @@ inherited_options:
- name: on-timeout
usage: |
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).
- name: platform
usage: |
Target platform: linux/amd64 or linux/arm64 (cloud only). With --image-ref, omitting it lets the server resolve the platform from the image and the CLI sends the local CPU as a hint for multi-platform images. With --template, omitting it inherits the template platform. With a sandbox kit, the kit's template is built for this platform and cached apart from other platforms; omitting it keeps the server's choice.
- name: publish
shorthand: p
default_value: '[]'

3
data/sbx_cli/sbx_create_devin.yaml
View File

@@ -95,6 +95,9 @@ inherited_options:
- name: on-timeout
usage: |
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).
- name: platform
usage: |
Target platform: linux/amd64 or linux/arm64 (cloud only). With --image-ref, omitting it lets the server resolve the platform from the image and the CLI sends the local CPU as a hint for multi-platform images. With --template, omitting it inherits the template platform. With a sandbox kit, the kit's template is built for this platform and cached apart from other platforms; omitting it keeps the server's choice.
- name: publish
shorthand: p
default_value: '[]'

3
data/sbx_cli/sbx_create_docker-agent.yaml
View File

@@ -95,6 +95,9 @@ inherited_options:
- name: on-timeout
usage: |
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).
- name: platform
usage: |
Target platform: linux/amd64 or linux/arm64 (cloud only). With --image-ref, omitting it lets the server resolve the platform from the image and the CLI sends the local CPU as a hint for multi-platform images. With --template, omitting it inherits the template platform. With a sandbox kit, the kit's template is built for this platform and cached apart from other platforms; omitting it keeps the server's choice.
- name: publish
shorthand: p
default_value: '[]'

3
data/sbx_cli/sbx_create_gemini.yaml
View File

@@ -95,6 +95,9 @@ inherited_options:
- name: on-timeout
usage: |
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).
- name: platform
usage: |
Target platform: linux/amd64 or linux/arm64 (cloud only). With --image-ref, omitting it lets the server resolve the platform from the image and the CLI sends the local CPU as a hint for multi-platform images. With --template, omitting it inherits the template platform. With a sandbox kit, the kit's template is built for this platform and cached apart from other platforms; omitting it keeps the server's choice.
- name: publish
shorthand: p
default_value: '[]'

3
data/sbx_cli/sbx_create_opencode.yaml
View File

@@ -95,6 +95,9 @@ inherited_options:
- name: on-timeout
usage: |
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).
- name: platform
usage: |
Target platform: linux/amd64 or linux/arm64 (cloud only). With --image-ref, omitting it lets the server resolve the platform from the image and the CLI sends the local CPU as a hint for multi-platform images. With --template, omitting it inherits the template platform. With a sandbox kit, the kit's template is built for this platform and cached apart from other platforms; omitting it keeps the server's choice.
- name: publish
shorthand: p
default_value: '[]'

3
data/sbx_cli/sbx_create_shell.yaml
View File

@@ -95,6 +95,9 @@ inherited_options:
- name: on-timeout
usage: |
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).
- name: platform
usage: |
Target platform: linux/amd64 or linux/arm64 (cloud only). With --image-ref, omitting it lets the server resolve the platform from the image and the CLI sends the local CPU as a hint for multi-platform images. With --template, omitting it inherits the template platform. With a sandbox kit, the kit's template is built for this platform and cached apart from other platforms; omitting it keeps the server's choice.
- name: publish
shorthand: p
default_value: '[]'

233
data/sbx_cli/sbx_env.yaml
View File

@@ -2,224 +2,33 @@ name: sbx env
synopsis: |
Manage sandboxes declaratively from an sbxenv.yaml file
experimental: true
description: |
Manage a sandbox environment declared in an sbxenv.yaml file.
description: |-
Manage a sandbox declared in an sbxenv.yaml file. The file selects the agent,
kits, workspace mounts, environment variables, secrets, and credential bindings.
The file describes the agent, optional mixin kits, workspace mounts,
environment variables, secrets to provision, and per-service credential
bindings. Secrets are provisioned at the environment's sandbox scope so
`sbx env rm` can remove everything it created.
Use create to provision the sandbox, run to start or join its agent session,
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.
A secret with `command` or `ref` can set `snapshot: true` to resolve on
the host after approval and store the result as a literal. This works locally
and with --cloud. Snapshots do not refresh; recreate the environment to rotate
them. A snapshot cannot set refresh or noVerify.
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.
Command secrets run from a fresh temporary directory on the host during
verification and refresh. The host temporary directory must be absolute and must
remain outside writable sandbox mounts. Relative references such as ./helper or
cat token no longer resolve against the project or daemon working directory. Use an absolute
helper path outside shared workspaces. sbx does not copy helpers, inspect their
dependencies, or confine their execution. Helpers and any code or configuration
they load must remain outside writable sandbox mounts. Explicit paths into shared
workspaces and broad mounts exposing host configuration or the host temporary
directory remain unsafe, including mounts added later with sbx mount.
The environment file is mounted read-only by default when shared with the
sandbox. Set sandboxOptions.writableEnvFiles only when you trust the agent
to change what future invocations run on the host.
secrets:
github:
command: gh auth token
snapshot: true
With --cloud, manage a cloud sandbox from the same file. Host workspace mounts,
host port bindings, MCP definitions, registry credentials, and unsnapshotted
dynamic secret sources are unsupported. Clone the project inside the sandbox instead.
A file may declare its own inputs in an `args:` block, each with a default or
`required: true` and an optional description, enum, or pattern. Reference one
as `${{ env.args.NAME }}` anywhere a value appears and supply it with
`--env-arg NAME=VALUE`.
Secrets and bindings are provisioned at creation; changes require recreating
the sandbox. Removal deletes secrets provisioned by this environment; bindings
are retained unless --prune-bindings is passed. Use the same cloud target,
identity, and ordered files for subsequent commands.
A `kits:` entry is either a bare reference or a mapping carrying the
arguments that kit declares, which `--kit-arg` overrides per invocation:
kits:
- ./mixins/base
- source: ./mixins/tool
args:
version: ${{ env.args.channel }}
A kit source written as an explicit relative path — `./…`, `../…`, `.`, `..`, or one
ending in `.zip` — is resolved against the directory of the file that declares
it, so a checked-in file reaches the same kits from wherever `sbx` is run. Write a
local kit that way: a bare `kits/tool` is as much a registry reference as a
directory, so it is left as written and resolves from the current directory.
A `workspace:` names the directory mounted read/write into the sandbox. A
relative path resolves against the directory of the file that declares it — as
a relative kit source does — so `workspace: .` mounts the directory the file
sits in. ${{ env.projectDir }} names the project directory (the one holding the
first PATH, or the current directory when none is named) and ${{ env.fileDir }}
the declaring file's own, for a value that spells its anchor out. Declaring
none mounts nothing — as omitting PATH does for `sbx create` — and the agent
works in the container's own filesystem instead of on your files. Unless the file sets `name:` or --name overrides it,
the sandbox is named after the mounted directory, or after the project directory
when nothing is mounted, so an environment that mounts nothing is still the same
sandbox every time.
A `lifecycle:` block declares commands that run on the host — outside
the sandbox, with your own privileges — around the sandbox's life:
lifecycle:
initialize:
- command: test -d app || git clone https://github.com/acme/app
postCreate:
- command: ./scripts/seed-fixtures.sh
preRemove:
- command: ./scripts/archive-state.sh
Each runs through your shell from the project directory — the one holding the
first PATH, or the current directory when none is named; ${{ env.projectDir }}
names the same place, and commands merged in from a file elsewhere share it.
Change it per command with `workdir:`, and cap a command's runtime with
`timeout:`.
"initialize" runs on every "create" and every "run", including one that only
attaches, so it can produce the workspace the sandbox mounts; write it to be
repeatable. "postCreate" runs once the sandbox exists, and "preRemove" after
"sbx env rm" is confirmed but before it deletes anything. Whatever stops
preRemove is only a warning, so a teardown that cannot run still cannot make an
environment unremovable; what one adds to the environment instead — a stored
credential, an approved domain — stops the removal, since what follows would
delete it without a plan row ever naming it. "sbx env exec" runs no commands at
all.
Commands appear in the environment plan with the directory each runs in, and are
approved with it before the invocation does any work. An environment that declares
any of them asks on every invocation, whether or not this one is what runs them,
since approving a command also trusts whatever it invokes, including a script
whose contents change after the answer. Use --skip-host-commands to run none of
them.
Everything an environment sets up — host commands, credentials, bindings, MCP
registrations, directories, published ports, the sandbox itself and the
variables it runs with — is shown as a plan and approved before anything runs:
ENVIRONMENT
Name: claude-proj
File: /Users/me/proj/sbxenv.yaml
SECRETS
+ anthropic
ref: op://vault/anthropic/key
refresh: 55m
LIFECYCLE
~ initialize: make setup && make seed
command: make setup -> make setup && make seed
workdir: /Users/me/proj
1 to add · 1 to change · 0 to destroy
Approve this plan? (y/N)
The plan groups resources by the block of the file that declares them, in the
order the blocks are declared, so a row is looked up where it was written. The
mark in front of a row is what applying does to the resource, and the totals
name every mark a plan can carry: "+ to add" and "~ to change" above,
"- to destroy" for what "sbx env rm" takes away, "> to run" for a command that
runs again — a command converges to nothing, so it runs on every apply that
reaches it — and "! to forget" for a resource this environment applied and no
longer declares. Where the file has nothing to say, the text after the row's name does:
that a resource is missing, or that the work waits for the next create, since a
port, a credential, a kit or a postCreate command comes with the sandbox, so
attaching to one that already exists leaves it for the next one that is built. A
resource that is as it was, and already approved, is left out: what is on screen
is what there is to read.
The lines under a row are the attributes the environment declares, so an edited
kit argument or variable reads as what it was against what it becomes, and a
"command:" or "ref:" secret shows where the credential comes from — a command
that resolves one runs on this machine. A secret's literal "value:" is the one
exception: a plan is both shown here and written to state, so it is named and
stands in as a "sha256:" digest.
KITS
~ ./mixins/tool
args.version: 1.2.3 -> 1.2.4
ENV
~ GOFLAGS
value: -mod=mod -> -mod=readonly
What an attribute was is what this environment last applied here, or — for one it
approved and never applied, such as a binding or a port answered for while
attaching to a sandbox that already exists — what was approved. Either way an
edit shows the value the question is about, whatever the row itself does.
An environment file that a mount would hand over read-write — which is what
mounting the project directory holding it does — is bound read-only at its own
path inside that mount, leaving the rest of it writable. The file decides what a
later invocation runs on this machine, so an agent able to edit it decides what
the next plan asks about. Declare "sandboxOptions.writableEnvFiles: true" where an
agent is meant to edit it; the plan then says the file is writable, as it says
when a file sits below a mount's own directory, where renaming that directory
reaches it again.
What was approved is recorded per environment under sbx's state directory, not
next to the file, so a later invocation asks only about what moved — and applies
silently when nothing did. An environment that declares commands running on this
machine is asked about on every invocation, changed or not: the answer is about
the invocation, and what a command does depends on what the project holds when it
runs rather than on the text approved before. "sbx env plan" prints the plan and
changes nothing.
Use --force (-f) where there is no terminal to answer on. Where an
environment's commands are your own and run many times a day,
"sbx settings set env.rememberHostCommands true" asks about them only when
they change.
With --cloud, create, run, exec, rm and plan manage a cloud sandbox from the same
file. Supported declarations are agents and kits, sandbox environment variables,
CPU and memory sizing, literal or snapshot secrets and bindings for supported providers, and
host lifecycle commands. Kits can publish TCP ports through cloud endpoints.
Stored cloud secrets are inherited as with cloud create/run; sandbox-scoped secrets
override account defaults, and secrets declared in the file override both. The plan
shows inherited credentials. Removal deletes only secrets provisioned by this environment.
Bindings merge into the same global credentials.yaml as local environments and
are retained on removal unless --prune-bindings is passed. Cloud must advertise
kit credential support. Third-party kit domains must be approved by the binding;
creation refuses implicit provider-default routing for a bound secret. Bindings
and secrets are provisioned at creation; editing them requires recreating the sandbox.
Snapshot references use the host's supported CLI resolvers (such as op:// and AWS
Secrets Manager ARNs); the sdk backend is unsupported. An interrupted secret
upload reuses the saved value in the host credential store. If that value is
unavailable, resolution is not repeated: follow the recovery error before cleanup.
workspace, additionalWorkspaces and clone name host directories, which a cloud
sandbox cannot mount; remove them and clone the project inside the sandbox from a
kit instead. Host port bindings, registry credentials, MCP definitions, custom
credential providers, local sandbox options and dynamic secret sources are also
rejected before host commands or provisioning. Initialize commands may prepare
local kit sources; kit validation follows initialization and precedes cloud baking.
State belongs to this machine, the selected cloud endpoint, Docker identity and
ordered environment files. Use the same target and files for subsequent commands.
DOCKER_ACCESS_TOKEN uses a token-specific state scope: changing the token starts
with separate state. Use sbx login for state that survives token refresh.
If creation is interrupted, retry the same command and declaration within 23 hours.
Removal waits for unresolved writes to be recovered. Older unresolved attempts
retain their journal; the error names its path. Before deleting that journal,
confirm the original requests have finished and remove their sandbox and secrets
using ordinary cloud commands in the same account and endpoint. If the outcome
cannot be confirmed, retain the journal and contact support.
Lifecycle commands inherit the cloud endpoint and expose SBX_SANDBOX_ID after
creation. Sandbox env values apply to new sessions; rejoining a live agent keeps
that process's existing environment.
sbx --cloud env plan ./sbxenv.yaml
sbx --cloud env run --force --detach ./sbxenv.yaml
sbx --cloud env exec ./sbxenv.yaml -- git status
sbx --cloud env rm --force ./sbxenv.yaml
For file syntax and workflows, see:
https://docs.docker.com/ai/sandboxes/configuration/environment-files/
usage: sbx env COMMAND
options:
- name: help

21
data/sbx_cli/sbx_env_create.yaml
View File

@@ -13,23 +13,10 @@ description: |-
supplied by --env-arg, plus ${{ env.projectDir }} and ${{ env.fileDir }}.
Nothing else is expanded, so a "$" is literal text.
A directory resolves to the sbxenv.yaml in it and to no other name; any
other file is read only when a PATH names it. The hidden .sbxenv.yaml was once
read as a directory's own environment too, so a project still holding one now
reads as having none.
With no PATH, an existing .sbxenv.yaml in your home directory is merged
underneath as a base layer for defaults shared across projects; naming any
PATH skips the layer. It may not set "name:", which identifies a single
project, and its "workspace:" must be rooted at ${{ env.projectDir }} — for
the base that is always the directory the invocation runs from, since naming
any PATH skips it — so the base mounts each project's own directory rather
than one directory under all of them. Changing its "agent:"
changes the derived <agent>-<directory-basename> sandbox name, leaving
sandboxes created under the previous name for "sbx env rm" to miss.
A list such as "ports" or "mcp.servers" concatenates across layers rather
than overriding, so an entry declared in both appears twice.
A directory PATH selects sbxenv.yaml; a file PATH selects that file.
With no PATH, ~/.sbxenv.yaml supplies shared defaults when present.
Explicit PATHs skip those defaults. Later files override earlier values;
lists such as ports and mcp.servers are concatenated.
usage: sbx env create [PATH...] [flags]
options:
- name: clone

21
data/sbx_cli/sbx_env_exec.yaml
View File

@@ -13,23 +13,10 @@ description: |-
argument forms the command and the environment file is read from the current
directory.
A directory resolves to the sbxenv.yaml in it and to no other name; any
other file is read only when a PATH names it. The hidden .sbxenv.yaml was once
read as a directory's own environment too, so a project still holding one now
reads as having none.
With no PATH, an existing .sbxenv.yaml in your home directory is merged
underneath as a base layer for defaults shared across projects; naming any
PATH skips the layer. It may not set "name:", which identifies a single
project, and its "workspace:" must be rooted at ${{ env.projectDir }} — for
the base that is always the directory the invocation runs from, since naming
any PATH skips it — so the base mounts each project's own directory rather
than one directory under all of them. Changing its "agent:"
changes the derived <agent>-<directory-basename> sandbox name, leaving
sandboxes created under the previous name for "sbx env rm" to miss.
A list such as "ports" or "mcp.servers" concatenates across layers rather
than overriding, so an entry declared in both appears twice.
A directory PATH selects sbxenv.yaml; a file PATH selects that file.
With no PATH, ~/.sbxenv.yaml supplies shared defaults when present.
Explicit PATHs skip those defaults. Later files override earlier values;
lists such as ports and mcp.servers are concatenated.
Flags match the behavior of "sbx exec".
usage: sbx env exec [flags] [PATH...] -- COMMAND [ARG...]

21
data/sbx_cli/sbx_env_plan.yaml
View File

@@ -17,23 +17,10 @@ description: |-
path to the environment file itself. Passing more than one PATH deep-merges them
in order, matching the other "sbx env" subcommands.
A directory resolves to the sbxenv.yaml in it and to no other name; any
other file is read only when a PATH names it. The hidden .sbxenv.yaml was once
read as a directory's own environment too, so a project still holding one now
reads as having none.
With no PATH, an existing .sbxenv.yaml in your home directory is merged
underneath as a base layer for defaults shared across projects; naming any
PATH skips the layer. It may not set "name:", which identifies a single
project, and its "workspace:" must be rooted at ${{ env.projectDir }} — for
the base that is always the directory the invocation runs from, since naming
any PATH skips it — so the base mounts each project's own directory rather
than one directory under all of them. Changing its "agent:"
changes the derived <agent>-<directory-basename> sandbox name, leaving
sandboxes created under the previous name for "sbx env rm" to miss.
A list such as "ports" or "mcp.servers" concatenates across layers rather
than overriding, so an entry declared in both appears twice.
A directory PATH selects sbxenv.yaml; a file PATH selects that file.
With no PATH, ~/.sbxenv.yaml supplies shared defaults when present.
Explicit PATHs skip those defaults. Later files override earlier values;
lists such as ports and mcp.servers are concatenated.
usage: sbx env plan [PATH...] [flags]
options:
- name: clone

21
data/sbx_cli/sbx_env_rm.yaml
View File

@@ -13,23 +13,10 @@ description: |-
in order (docker-compose `-f` semantics), so the same set used to create the
environment resolves to the same sandbox on removal.
A directory resolves to the sbxenv.yaml in it and to no other name; any
other file is read only when a PATH names it. The hidden .sbxenv.yaml was once
read as a directory's own environment too, so a project still holding one now
reads as having none.
With no PATH, an existing .sbxenv.yaml in your home directory is merged
underneath as a base layer for defaults shared across projects; naming any
PATH skips the layer. It may not set "name:", which identifies a single
project, and its "workspace:" must be rooted at ${{ env.projectDir }} — for
the base that is always the directory the invocation runs from, since naming
any PATH skips it — so the base mounts each project's own directory rather
than one directory under all of them. Changing its "agent:"
changes the derived <agent>-<directory-basename> sandbox name, leaving
sandboxes created under the previous name for "sbx env rm" to miss.
A list such as "ports" or "mcp.servers" concatenates across layers rather
than overriding, so an entry declared in both appears twice.
A directory PATH selects sbxenv.yaml; a file PATH selects that file.
With no PATH, ~/.sbxenv.yaml supplies shared defaults when present.
Explicit PATHs skip those defaults. Later files override earlier values;
lists such as ports and mcp.servers are concatenated.
usage: sbx env rm [PATH...] [flags]
options:
- name: env-arg

21
data/sbx_cli/sbx_env_run.yaml
View File

@@ -14,23 +14,10 @@ description: |-
supplied by --env-arg, plus ${{ env.projectDir }} and ${{ env.fileDir }}.
Nothing else is expanded, so a "$" is literal text.
A directory resolves to the sbxenv.yaml in it and to no other name; any
other file is read only when a PATH names it. The hidden .sbxenv.yaml was once
read as a directory's own environment too, so a project still holding one now
reads as having none.
With no PATH, an existing .sbxenv.yaml in your home directory is merged
underneath as a base layer for defaults shared across projects; naming any
PATH skips the layer. It may not set "name:", which identifies a single
project, and its "workspace:" must be rooted at ${{ env.projectDir }} — for
the base that is always the directory the invocation runs from, since naming
any PATH skips it — so the base mounts each project's own directory rather
than one directory under all of them. Changing its "agent:"
changes the derived <agent>-<directory-basename> sandbox name, leaving
sandboxes created under the previous name for "sbx env rm" to miss.
A list such as "ports" or "mcp.servers" concatenates across layers rather
than overriding, so an entry declared in both appears twice.
A directory PATH selects sbxenv.yaml; a file PATH selects that file.
With no PATH, ~/.sbxenv.yaml supplies shared defaults when present.
Explicit PATHs skip those defaults. Later files override earlier values;
lists such as ports and mcp.servers are concatenated.
usage: sbx env run [PATH...] [flags]
options:
- name: clone

12
data/sbx_cli/sbx_kit_inspect.yaml
View File

@@ -8,6 +8,11 @@ description: |-
Pass --kit-arg to preview how the kit resolves with a given set of
arguments; the output shows the substituted content.
--offline skips the daemon-backed kit policy (kit.allowedSources,
kit.allowLocalKits, kit.requireSignature) so the command needs neither
sandboxd nor a signed-in session; it only accepts a local directory or
ZIP reference, since those are the only ones this check applies to.
usage: sbx kit inspect REFERENCE [flags]
options:
- name: format
@@ -29,6 +34,10 @@ options:
experimental: true
usage: |
File of name=value kit arguments, one per line (can be repeated); --kit-arg overrides
- name: offline
default_value: "false"
usage: |
Skip the daemon-backed kit policy check; local directory or ZIP references only
inherited_options:
- name: cloud
default_value: "false"
@@ -44,5 +53,8 @@ example: |4-
# Machine-readable output
sbx kit inspect ghcr.io/myorg/my-kit:1.0 --format json
# Inspect without sandboxd running or a Docker sign-in
sbx kit inspect ./my-kit --offline
see_also:
- sbx kit - (Experimental) Manage kit artifacts

15
data/sbx_cli/sbx_kit_pull.yaml
View File

@@ -2,18 +2,15 @@ name: sbx kit pull
synopsis: Pull a kit artifact from an OCI registry
experimental: true
description: |-
Pull a kit artifact from an OCI registry and save its layer payload to a file.
Pull a kit artifact from an OCI registry and save its payload to a file.
Use a registry/repo:tag or registry/repo@sha256:digest reference.
The reference should be in the format "registry/repo:tag" or
"registry/repo@sha256:digest" (e.g., "ghcr.io/myorg/my-plugin:1.0").
The file extension is chosen automatically based on the kit's format:
schemaVersion: "1" → <name>.zip (legacy ZIP archive)
schemaVersion: "2" → <name>.tar.gz (standard OCI tar+gzip layer)
The output extension follows the resolved artifact format: .zip for v1,
or .tar.gz for v2. Use --output to choose the file path.
For Docker Hub, the sbx login session takes priority. Other registries use
secrets set with sbx secret set --registry. Both fall back to Docker credentials.
The registry must support HTTPS.
Authentication: sbx registry secrets (sbx secret set --registry) take priority, falling back to the Docker credential store.
usage: sbx kit pull REFERENCE [flags]
options:
- name: help

30
data/sbx_cli/sbx_kit_push.yaml
View File

@@ -2,31 +2,15 @@ name: sbx kit push
synopsis: Push a kit artifact to an OCI registry
experimental: true
description: |-
Package and push a kit artifact directory to an OCI registry.
Package a kit directory containing spec.yaml and push it to an OCI registry.
Use a registry/repo:tag reference. The kit's schema selects the artifact format.
The directory must contain a valid spec.yaml. The reference should be
in the format "registry/repo:tag" (e.g., "ghcr.io/myorg/my-plugin:1.0").
Every push attaches provenance. Use --sign to also sign the manifest and
provenance; signing is keyless unless --key is supplied.
The OCI artifact format is selected from the kit's spec.yaml:
schemaVersion: "1" → legacy ZIP-based artifact
schemaVersion: "2" → v2 tar+gzip layer with the spec in the manifest
config blob and standard OCI annotations (so
distribution tooling can read kit metadata
without pulling layers)
With --sign, the pushed manifest is signed and the Sigstore bundle is
attached to the kit as an OCI referrer. Signing is keyless (Fulcio +
Rekor) unless --key is given for key-based signing.
Every push also attaches a SLSA provenance attestation as an OCI
referrer, recording the kit's content digests, the declared sandbox
image, and the source git commit when the directory is a working tree.
The provenance is unsigned unless --sign is given, in which case it is
signed as a DSSE in-toto attestation with the same identity or key.
Authentication: the Docker Hub session from sbx login and sbx registry
secrets (sbx secret set --registry) take priority, falling back to the
Docker credential store.
For Docker Hub, the sbx login session takes priority. Other registries use
secrets set with sbx secret set --registry. Both fall back to Docker credentials.
The registry must support HTTPS.
usage: sbx kit push DIRECTORY REFERENCE [flags]
options:
- name: help

12
data/sbx_cli/sbx_kit_validate.yaml
View File

@@ -9,6 +9,11 @@ description: |-
A kit that declares required arguments is invalid until they are
supplied, so pass the same --kit-arg values you would pass to sbx
create.
--offline skips the daemon-backed kit policy (kit.allowedSources,
kit.allowLocalKits, kit.requireSignature) so the command needs neither
sandboxd nor a signed-in session; it only accepts a local directory or
ZIP reference, since those are the only ones this check applies to.
usage: sbx kit validate REFERENCE [flags]
options:
- name: format
@@ -30,6 +35,10 @@ options:
experimental: true
usage: |
File of name=value kit arguments, one per line (can be repeated); --kit-arg overrides
- name: offline
default_value: "false"
usage: |
Skip the daemon-backed kit policy check; local directory or ZIP references only
inherited_options:
- name: cloud
default_value: "false"
@@ -45,5 +54,8 @@ example: |4-
# Supply the arguments a kit declares
sbx kit validate ./my-kit --kit-arg region=eu
# Validate without sandboxd running or a Docker sign-in
sbx kit validate ./my-kit --offline
see_also:
- sbx kit - (Experimental) Manage kit artifacts

2
data/sbx_cli/sbx_mcp.yaml
View File

@@ -22,7 +22,7 @@ see_also:
- sbx mcp add - Register an MCP server
- sbx mcp auth - Authorize MCP servers
- sbx mcp inspect - Show MCP server details
- sbx mcp load - Load an already-registered MCP server into a running sandbox
- sbx mcp load - Load an already-registered MCP server into a sandbox
- sbx mcp ls - List MCP servers
- sbx mcp rm - Remove a registered MCP server
- sbx mcp unload - Unload an MCP server from a running sandbox

225
data/sbx_cli/sbx_mcp_add.yaml
View File

@@ -1,220 +1,25 @@
name: sbx mcp add
synopsis: Register an MCP server
description: |-
Register an MCP server by name. The server is validated and its
specification is stored for use with sbx create/run --static-mcp.
Register an MCP server for use with sbx create/run --static-mcp.
To attach a registered server to a running sandbox, use sbx mcp load.
This command only registers the server. To attach an already-registered
server to a running sandbox, use 'sbx mcp load'.
Use --url for a remote MCP endpoint, a community-registry or server-manifest
URL, or a Docker Hardened Image reference. Other image references are unsupported.
Use --command for a local stdio server. Local servers run on the host with your
full permissions; use only trusted executables.
The --url flag accepts four input formats; the type is auto-detected:
OAuth metadata is discovered automatically for remote endpoints. Use --client-id
for a pre-registered client, or --oauth-authorization-server when the server
publishes no discovery metadata. Confidential clients need a secret stored as
mcp:NAME:client_secret; use sbx secret set without -t to read it from stdin.
- Remote MCP endpoint URL (https://host/mcp — talks MCP at the URL;
OAuth metadata is discovered via RFC 9728/8414).
- MCP community-registry URL (https://registry.modelcontextprotocol.io/v0/servers/<name>...)
— fetches the registry envelope and resolves the OCI image.
- Server-manifest URL (any URL returning a server.json or server.yaml
body shaped like the MCP community-registry schema — GitHub raw URLs,
internal HTTP servers, ad-hoc CDN links all work).
- Docker Hardened Images (DHI) image ref (dhi.io/<name>:<tag> or
dhi.io/<name>@sha256:... — the server.json manifest is extracted
from the image's in-toto attestation via the OCI Referrers API).
Use --header for custom headers on remote endpoints. Header values can reference
stored secrets; see the examples below. Header secrets come from this host's
secret store and require a locally connected server.
Other image refs (inputs without "://" that are not dhi.io, e.g.
docker.io/foo:tag) are no longer accepted. Use a server manifest instead.
SSRF guard and --skip-ssrf-check:
A --url whose host resolves to a private/RFC1918, loopback, link-local, or
cloud-metadata address is fetched anyway, but flagged: the add proceeds and
a warning naming the resolved address is printed (this protects against
manifest URLs that reach internal services, cloud metadata, or
DNS-rebinding targets by making them visible, not by blocking them). Some
legitimate servers live on private networks (split-horizon DNS, internal
load balancers, VPN-only endpoints, PrivateLink), so their public hostname
resolves to a private address and the warning is expected noise for them.
OAuth authorization-server metadata has a separate SSRF guard with the same
warn-and-proceed posture: a disallowed address is logged, not blocked. Pass
--skip-ssrf-check to disable both checks for this add, including OAuth
metadata redirects (silencing the warning too), when you trust the provider
and its discovery destinations; use it only for URLs you control.
OAuth for remote endpoints (--oauth-authorization-server / --client-id):
Two related options configure OAuth for a remote --url server (both are
only valid with --url):
--oauth-authorization-server hand-supplies the authorization-server
metadata for a server that publishes no well-known RFC 9728/8414 metadata
(e.g. Gmail). It is a local file path or an http(s) URL to a JSON document
conforming to the RFC 8414 oauth-authorization-server shape
(authorization_endpoint and token_endpoint are required). --client-id is
required alongside it UNLESS the metadata document itself advertises a
registration_endpoint, in which case a client is registered dynamically
(RFC 7591) and --client-id may be omitted.
--client-id supplies a PRE-REGISTERED OAuth client. It may be given WITHOUT
--oauth-authorization-server: the server's authorization metadata is then
discovered normally and the supplied client is attached to it. This is the
right mode for a server whose discoverable metadata exposes no
registration_endpoint (so Dynamic Client Registration is impossible) but
which accepts a client id the operator registered ahead of time.
Client secrets (confidential clients):
There is no --client-secret flag. The secret for a confidential client
lives in the secret store in the global scope under the
service name "mcp:<server>:client_secret", and is read from there
whenever the server is used:
sbx secret set mcp:<server>:client_secret
Run it with no -t so the value is read from stdin instead of landing in
your shell history. The secret is never written to the MCP registration
on disk. Remove it later with 'sbx secret rm mcp:<server>:client_secret'.
The stored secret is bound to the OAuth identity (client id, issuer and
token endpoint) that first used it. Re-registering the same server name
against a different client or authorization server therefore does NOT
reuse it — store the secret again for the new client. To let a new
identity claim the existing secret, drop the recorded binding with
'sbx secret rm mcp:<server>:client_secret:identity'.
Two rules apply on the discovered path (they do not affect a server that
advertises a registration_endpoint, the hand-supplied
--oauth-authorization-server path, or --command servers):
- If the discovered authorization metadata has NO registration_endpoint,
Dynamic Client Registration is impossible, so --client-id is REQUIRED;
the add fails without it. This is the Slack shape (discoverable metadata,
no DCR, a pre-registered client).
- A stored client secret is REQUIRED when the server's advertised
token_endpoint_auth_methods_supported (RFC 8414) does NOT include "none"
— i.e. it accepts only confidential clients (client_secret_basic /
client_secret_post). Registration still succeeds without one, but the
add-time authorization is skipped; store the secret and run
'sbx mcp auth <server>' to finish. When the list includes "none" a
public/PKCE client is allowed and --client-id alone is enough. If the
server advertises no token_endpoint_auth_methods_supported at all (the
field is optional in RFC 8414), the requirement cannot be determined and
the add proceeds as usual.
Default OAuth scopes (--scope / --no-scope):
--scope records the DEFAULT set of scopes to request at consent time for a
remote --url OAuth server (repeatable). Precedence at authorization time is
--no-scope > an explicit 'sbx mcp auth --scope' > the set recorded here > the
scope set the RESOURCE itself says it requires (from its RFC 9728
protected-resource metadata or its WWW-Authenticate challenge) > whichever of
openid, email, profile, and offline_access are advertised. Other advertised
scopes are excluded from this fallback. If no scopes are selected, the scope
parameter is omitted so the authorization server can apply its own default
grant (RFC 6749 §3.3).
A resource that publishes a required set therefore gets it requested with no
flag at all, and the consent block marks that set as derived rather than
chosen. --no-scope suppresses all scope fallbacks and requests the server's
default grant.
When using recorded defaults or resource scopes, sbx also requests offline_access
if the authorization server advertises it, allowing refresh tokens. To request
an exact set without this addition, use 'sbx mcp auth <server> --scope ...'.
Scopes you name are checked against the union of two documents a server can
publish: the authorization server's RFC 8414 scopes_supported and the
resource's own RFC 9728 protected-resource metadata (some servers, e.g.
GitHub, document their real scopes on the resource and advertise almost
nothing over RFC 8414). A scope in neither prints a warning naming the
offender but is still requested — a mismatch is often the server's own
documentation gap, not a typo, and either document is allowed to be
non-exhaustive. This is a recognition check, not a promise: a recognized
scope can still be refused at consent time.
Scope values may be URN-shaped (urn:ietf:params:oauth:scope:mail) or
URL-shaped (https://www.fastmail.com/dev/mcp). Neither needs quoting — a scope
token cannot contain a space or a quote — and both are percent-encoded
normally on the wire. --scope applies both to a hand-supplied override and to
a plain --url server whose OAuth metadata is discovered.
RFC 8707 resource indicator (--resource):
Every authorization request, code exchange and token refresh names the server
the token is for, in the 'resource' parameter the MCP authorization
specification requires (RFC 8707). That value is normally DERIVED, and you do
not need this flag: it comes from the server's own RFC 9728 protected-resource
metadata when it publishes some, and otherwise from the --url endpoint
(lowercased scheme/host, path kept, fragment dropped).
--resource replaces that derivation with a value you supply. Use it when the
derived one is wrong — most often a server whose published identifier is its
bare origin (https://api.example.com) while its endpoint has a path
(https://api.example.com/mcp), which is indistinguishable from publishing
nothing, so the endpoint URL is what gets sent. An authorization server
entitled to reject an unknown target answers 'invalid_target'.
The value must be an absolute URI with a scheme and a host, and RFC 8707 §2
forbids a fragment; a bad value fails the add rather than being repaired or
dropped later. It is sent VERBATIM — nothing is lowercased and no path or
trailing slash is adjusted, because the string names a server and changing it
could name a different one. Only one value is accepted: a gateway backend
connects to exactly one MCP endpoint.
It outranks both the published value and the URL derivation, and also an
authorization server advertising resource_indicators_supported=false (the add
says so when that happens). It is recorded on the registration, so there is no
'sbx mcp auth --resource': one value is used by the add-time authorization,
every later 'sbx mcp auth', and every token refresh — a resource that differed
between them is the audience mismatch this parameter exists to prevent. To
change it, 'sbx mcp rm' the server and add it again; the existing token was
minted for the old resource anyway.
Not 'audience': RFC 8707 'resource' is what the MCP specification requires, and
an 'audience' parameter on an authorization-code request is an Auth0/Okta
vendor extension that sbx does not send. See 'sbx mcp inspect <name>' for the
effective value and where it came from.
Scope limit: this governs the OAuth flow sbx itself runs — a local data plane
(SBX_MCP_URL=none), and any server registered with
--oauth-authorization-server/--client-id. For a plain remote in hosted mode the
control-plane gateway is the OAuth client and does not carry the field yet, so
the value is recorded and the add warns that it is not sent for that server.
Custom request headers for remote endpoints (--header):
--header adds an HTTP header to every request sent to a remote --url
endpoint, written in the curl convention 'Header-Name: header value'.
Repeat the flag for more headers; each header name may be given once.
Headers the transport owns (Host, Content-Length, Connection, Proxy-*, …)
are rejected.
Only a remote endpoint can carry them: --header is refused with --command
and --local, and an add whose --url resolves to a stdio server (a registry
or manifest URL naming an OCI image) fails rather than dropping them.
A header value may reference a secret with ${placeholder}. The placeholder is
stored in the registration exactly as typed and the secret itself never is;
the value is read from the encrypted secret store and substituted when a
sandbox connects to the server. Store it with:
sbx secret set mcp:<server>:<placeholder>
For example:
sbx mcp add acme --url https://mcp.acme.com/mcp --header 'Authorization: Bearer ${api-key}'
sbx secret set mcp:acme:api-key
On an OAuth-protected server an explicit Authorization header takes
precedence over the OAuth access token.
Header secrets are read from the LOCAL secret store, so a header-bearing
server only works where this host connects it. Adding one while your MCP
gateway is the hosted (SaaS) one is rejected rather than registered with
headers that would be silently dropped — unless the server carries a
hand-supplied OAuth override (--oauth-authorization-server), which this
host connects directly in every gateway mode.
Alternative input — local stdio command (--command + --args):
The command runs as a subprocess on the HOST, outside the sandbox.
WARNING: Local servers are for ad-hoc development only. They have
no identity, no verifiable supply chain, and no sandboxing. The
process runs with your host user's full permissions — it can read
your filesystem, access your network, and call any API your user
can. Do not use --command with untrusted executables.
For registration and authorization workflows, see:
https://docs.docker.com/ai/sandboxes/mcp-gateway/
usage: sbx mcp add NAME (--url URL | --command COMMAND) [flags]
options:
- name: args

9
data/sbx_cli/sbx_mcp_load.yaml
View File

@@ -1,9 +1,10 @@
name: sbx mcp load
synopsis: Load an already-registered MCP server into a running sandbox
synopsis: Load an already-registered MCP server into a sandbox
description: |-
Attach a previously-registered MCP server to a running sandbox's gateway.
Connected agents see the new server's tools immediately via the standard MCP
tools/list_changed notification — no agent restart required.
Attach a previously-registered MCP server to a sandbox's gateway.
In a running sandbox, connected agents see the new server's tools immediately
via the standard MCP tools/list_changed notification — no agent restart
required. A stopped sandbox gets the server the next time it starts.
The server must already exist in the local MCP store (register first with
'sbx mcp add'). Both remote/hosted and local-stdio servers are supported.

1
data/sbx_cli/sbx_policy.yaml
View File

@@ -30,5 +30,6 @@ see_also:
- sbx policy inspect - Show policy or rule details
- sbx policy log - Show sandbox policy logs
- sbx policy ls - List sandbox policies
- sbx policy refresh - Force an immediate policy refresh
- sbx policy reset - Reset policies to defaults
- sbx policy rm - Remove a policy rule

23
data/sbx_cli/sbx_policy_init.yaml
View File

@@ -1,23 +1,18 @@
name: sbx policy init
synopsis: Initialize the global network policy
description: |-
Initialize the global network policy that applies to all sandboxes.
Initialize the global network policy before starting a sandbox or adding
custom rules. Per-sandbox rules apply on top of this policy.
This sets the initial global network policy and must be run before adding
custom allow/deny rules or starting a sandbox for the first time. It is a
one-time setup: once initialized, use "sbx policy reset" to start over.
Choose a policy:
This is the initial global policy, not a per-sandbox default; you can change
it later. Per-sandbox rules, including those added by kits such as the
built-in agent kits, apply on top for individual sandboxes.
- allow-all: Allow all outbound network traffic.
- balanced: Allow typical development traffic, including AI services and package registries.
- deny-all: Block all outbound network traffic.
Available policies:
allow-all All outbound network traffic is allowed
balanced Typical development traffic is allowed, such as AI services and package registries
deny-all All outbound network traffic is blocked
After initializing, use "sbx policy allow/deny/rm" to change the global policy.
Use "sbx policy reset" to clear all policies and start over.
After initialization, use sbx policy allow/deny/rm to change the rules.
Initialization is a one-time setup. Use sbx policy reset to clear all policies
and start over.
With --cloud:
Set the default network mode of the cloud policy.

7
data/sbx_cli/sbx_policy_ls.yaml
View File

@@ -37,6 +37,10 @@ options:
usage: Output in JSON format
- name: protocol
usage: 'Filter network rules by protocol: tcp or udp'
- name: quiet
shorthand: q
default_value: "false"
usage: Only display rule IDs (network patterns with --cloud)
- name: source
usage: 'Filter policies by source: "local", "org", or "kit"'
- name: type
@@ -68,6 +72,9 @@ example: |4-
# Output filtered rules as JSON
sbx policy ls --json
# List only rule IDs
sbx policy ls -q
# List only network policies
sbx policy ls --type network

32
data/sbx_cli/sbx_policy_refresh.yaml Normal file
View File

@@ -0,0 +1,32 @@
name: sbx policy refresh
synopsis: Force an immediate policy refresh
description: |-
Force sandboxd to fetch and apply governance policy immediately.
The daemon normally polls for policy changes on a regular interval. Use this
after changing an org policy setting (for example, toggling AI Governance) so
the change takes effect without waiting for the next poll. This also
invalidates the cached registry credential; it never restarts the daemon or
stops running sandboxes.
The refreshed policy applies to new connections only. Connections a sandbox
opened while the previous policy allowed them stay open even if the new
policy denies them; restart the sandbox to drop them.
usage: sbx policy refresh [flags]
options:
- name: help
shorthand: h
default_value: "false"
usage: help for refresh
inherited_options:
- name: cloud
default_value: "false"
usage: |
Dispatch to Docker Cloud Sandboxes API instead of local sandboxd (supported by a growing set of verbs — run 'sbx --cloud --help' for the current list)
- name: debug
shorthand: D
default_value: "false"
usage: Enable debug logging
example: ' sbx policy refresh'
see_also:
- sbx policy - Manage sandbox policies

3
data/sbx_cli/sbx_run.yaml
View File

@@ -116,6 +116,9 @@ options:
- name: on-timeout
usage: |
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).
- name: platform
usage: |
Target platform: linux/amd64 or linux/arm64 (cloud only). With --image-ref, omitting it lets the server resolve the platform from the image and the CLI sends the local CPU as a hint for multi-platform images. With --template, omitting it inherits the template platform. With a sandbox kit, the kit's template is built for this platform and cached apart from other platforms; omitting it keeps the server's choice.
- name: publish
shorthand: p
default_value: '[]'

7
data/sbx_cli/sbx_settings_ls.yaml
View File

@@ -22,6 +22,10 @@ options:
- name: no-trunc
default_value: "false"
usage: Show full values and descriptions, one setting per block
- name: quiet
shorthand: q
default_value: "false"
usage: Only display setting keys
inherited_options:
- name: cloud
default_value: "false"
@@ -37,5 +41,8 @@ example: |4-
# List settings as JSON
sbx settings ls --format json
# List only setting keys
sbx settings ls -q
see_also:
- sbx settings - Manage Docker Sandboxes settings

17
data/sbx_cli/sbx_settings_set.yaml
View File

@@ -1,21 +1,14 @@
name: sbx settings set
synopsis: Set a setting override
description: |-
Set a user override for a setting.
Administrator constraints apply to saved overrides. A conflicting value is rejected.
The value is parsed according to the setting's type:
bool "true" or "false"
int integer value
float floating-point value
string plain text
json raw JSON
Set a user override for a setting. Values are parsed according to the
setting's type: bool (true or false), int, float, string, or raw JSON.
Administrator constraints apply; conflicting values are rejected.
Environment variables take precedence over user overrides.
Most changes take effect within about five seconds. If a daemon restart is
required, this command tells you to run 'sbx daemon restart'.
Most changes take effect within about five seconds. This command reports
when a daemon restart is required.
usage: sbx settings set KEY VALUE [flags]
options:
- name: help

32
data/sbx_cli/sbx_skills_import.yaml
View File

@@ -2,29 +2,19 @@ name: sbx skills import
synopsis: Import skills from supported agent directories
experimental: true
description: |-
Import skills already installed for supported coding agents on this
machine.
Import skills installed for supported coding agents on this machine.
Directories are checked in order:
The following directories are checked in order:
~/.agents/skills
~/.claude/skills
~/.config/opencode/skills
~/.copilot/skills
~/.cursor/skills
~/.factory/skills
1. ~/.agents/skills
2. ~/.claude/skills
3. ~/.config/opencode/skills
4. ~/.copilot/skills
5. ~/.cursor/skills
6. ~/.factory/skills
When the same skill appears in more than one directory, the first copy is used
and the others are skipped with a warning.
Importing a skill that is already installed replaces it completely, including
removing files that are no longer present. You will be prompted before a skill
is replaced; use --force to skip all prompts.
Symlinks at the top level are followed if they point to a directory. Symlinks
within skill folders and loose files at the top level are skipped.
Imported skills are available to Claude, Codex, Copilot, Cursor, Droid, and
OpenCode.
The first copy of each skill is used. Importing replaces an existing skill
completely, including removing obsolete files; --force skips confirmation.
Top-level directory symlinks are followed; symlinks within skills are skipped.
usage: sbx skills import [flags]
options:
- name: dry-run

27
data/sbx_cli/sbx_template_load.yaml
View File

@@ -7,22 +7,19 @@ description: |-
Tar files are typically created with: sbx template save SANDBOX TAG --output FILE
With --cloud:
The tar is uploaded to the cloud template registry as a new template.
Takes two arguments (FILE, NAME). NAME must be unique per account.
--cpus and --memory-mib are required, and together must name one of the
billable sandbox shapes:
micro (1 vCPU / 2048 MiB)
small (2 vCPU / 4096 MiB)
medium (4 vCPU / 8192 MiB)
large (8 vCPU / 16384 MiB)
xl (16 vCPU / 32768 MiB)
--capture-mode controls what gets captured for the template: "disk" (default)
is faster to load and cold-boots from the filesystem; "all" captures memory +
disk + microVM checkpoint so subsequent runs resume in sub-second time at the
cost of a slower load.
Upload a tar file as a cloud template. Takes FILE and NAME; NAME must be
unique per account. Uploads can take several minutes.
Cloud loads upload your full tar to the registry; multi-GB uploads can
take several minutes. See https://docs.docker.com/ai/sandboxes/ for the snapshot/load model.
--cpus and --memory-mib are required and must match a billable sandbox shape:
- micro (1 vCPU / 2048 MiB)
- small (2 vCPU / 4096 MiB)
- medium (4 vCPU / 8192 MiB)
- large (8 vCPU / 16384 MiB)
- xl (16 vCPU / 32768 MiB)
Use --capture-mode disk for a filesystem snapshot, or all to capture memory,
disk, and the microVM checkpoint for faster resume.
usage: sbx template load FILE [NAME] [flags]
options:
- name: capture-mode

16
data/sbx_cli/sbx_template_save.yaml
View File

@@ -1,16 +1,11 @@
name: sbx template save
synopsis: Save a snapshot of the sandbox as a template
description: |-
Save a snapshot of the sandbox as a template.
Save a sandbox snapshot as a template in the local image store.
Use --pull never when creating a sandbox from the saved template.
The saved image is stored in the sandbox runtime's image store and can be
used as a template for new sandboxes with:
sbx run --pull never -t TAG AGENT [WORKSPACE]
Use --pull never to use the saved image without trying to pull it from a registry.
Use --output to also export the image to a tar file that can be shared
and loaded on another host with: sbx template load FILE
Use --output to export a tar file for loading on another host with
sbx template load.
With --cloud:
Snapshot a running cloud sandbox into a cloud-managed template. The
@@ -52,6 +47,9 @@ example: |4-
# Save as a template for new sandboxes on this host
sbx template save my-sandbox myimage:v1.0
# Create a sandbox from the saved template
sbx run --pull never -t myimage:v1.0 claude ./project
# Also export to a shareable tar file
sbx template save my-sandbox myimage:v1.0 --output /tmp/myimage.tar