From c2b0924002e879e259a9b045e72984bd54a37ce9 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Thu, 27 Aug 2026 10:04:46 +0000 Subject: [PATCH] docs: sync sbx v0.42.0-rc1 CLI reference The checked-in sbx command reference predates the v0.42.0 release candidate and omits or misstates its command surface. Replace data/sbx_cli with the generated reference for Docker Sandboxes v0.42.0-rc1. Co-Authored-By: Codex --- data/sbx_cli/sbx.yaml | 16 +- data/sbx_cli/sbx_attach.yaml | 40 +++++ data/sbx_cli/sbx_completion.yaml | 8 + data/sbx_cli/sbx_completion_bash.yaml | 8 + data/sbx_cli/sbx_completion_fish.yaml | 8 + data/sbx_cli/sbx_completion_powershell.yaml | 8 + data/sbx_cli/sbx_completion_zsh.yaml | 8 + data/sbx_cli/sbx_cp.yaml | 16 +- data/sbx_cli/sbx_create.yaml | 68 ++++++++- data/sbx_cli/sbx_create_claude.yaml | 60 +++++++- data/sbx_cli/sbx_create_codex.yaml | 60 +++++++- data/sbx_cli/sbx_create_copilot.yaml | 78 ---------- data/sbx_cli/sbx_create_cursor.yaml | 60 +++++++- data/sbx_cli/sbx_create_devin.yaml | 128 ++++++++++++++++ data/sbx_cli/sbx_create_docker-agent.yaml | 60 +++++++- data/sbx_cli/sbx_create_droid.yaml | 78 ---------- data/sbx_cli/sbx_create_gemini.yaml | 60 +++++++- data/sbx_cli/sbx_create_kiro.yaml | 78 ---------- data/sbx_cli/sbx_create_opencode.yaml | 60 +++++++- data/sbx_cli/sbx_create_shell.yaml | 60 +++++++- data/sbx_cli/sbx_daemon.yaml | 8 + data/sbx_cli/sbx_daemon_log-level.yaml | 8 + data/sbx_cli/sbx_daemon_log-level_set.yaml | 8 + data/sbx_cli/sbx_daemon_restart.yaml | 8 + data/sbx_cli/sbx_daemon_start.yaml | 8 + data/sbx_cli/sbx_daemon_status.yaml | 8 + data/sbx_cli/sbx_daemon_stop.yaml | 8 + data/sbx_cli/sbx_diagnose.yaml | 11 ++ data/sbx_cli/sbx_env.yaml | 153 +++++++++++++++++++- data/sbx_cli/sbx_env_create.yaml | 62 +++++++- data/sbx_cli/sbx_env_exec.yaml | 41 +++++- data/sbx_cli/sbx_env_plan.yaml | 82 +++++++++++ data/sbx_cli/sbx_env_rm.yaml | 45 +++++- data/sbx_cli/sbx_env_run.yaml | 60 +++++++- data/sbx_cli/sbx_exec.yaml | 19 ++- data/sbx_cli/sbx_kit.yaml | 15 +- data/sbx_cli/sbx_kit_add.yaml | 27 +++- data/sbx_cli/sbx_kit_inspect.yaml | 21 +++ data/sbx_cli/sbx_kit_pack.yaml | 8 + data/sbx_cli/sbx_kit_provenance.yaml | 11 ++ data/sbx_cli/sbx_kit_pull.yaml | 8 + data/sbx_cli/sbx_kit_push.yaml | 12 +- data/sbx_cli/sbx_kit_sign.yaml | 8 + data/sbx_cli/sbx_kit_validate.yaml | 25 ++++ data/sbx_cli/sbx_kit_verify.yaml | 11 ++ data/sbx_cli/sbx_login.yaml | 8 + data/sbx_cli/sbx_logout.yaml | 8 + data/sbx_cli/sbx_ls.yaml | 8 + data/sbx_cli/sbx_mcp.yaml | 8 + data/sbx_cli/sbx_mcp_add.yaml | 87 +++++++---- data/sbx_cli/sbx_mcp_auth.yaml | 53 ++++++- data/sbx_cli/sbx_mcp_auth_rm.yaml | 11 ++ data/sbx_cli/sbx_mcp_auth_status.yaml | 11 ++ data/sbx_cli/sbx_mcp_inspect.yaml | 17 ++- data/sbx_cli/sbx_mcp_load.yaml | 8 + data/sbx_cli/sbx_mcp_ls.yaml | 17 ++- data/sbx_cli/sbx_mcp_rm.yaml | 8 + data/sbx_cli/sbx_move.yaml | 65 +++++++++ data/sbx_cli/sbx_policy.yaml | 8 + data/sbx_cli/sbx_policy_allow.yaml | 8 + data/sbx_cli/sbx_policy_allow_network.yaml | 8 + data/sbx_cli/sbx_policy_check.yaml | 8 + data/sbx_cli/sbx_policy_check_network.yaml | 8 + data/sbx_cli/sbx_policy_deny.yaml | 8 + data/sbx_cli/sbx_policy_deny_network.yaml | 8 + data/sbx_cli/sbx_policy_init.yaml | 10 ++ data/sbx_cli/sbx_policy_inspect.yaml | 14 ++ data/sbx_cli/sbx_policy_log.yaml | 8 + data/sbx_cli/sbx_policy_ls.yaml | 8 + data/sbx_cli/sbx_policy_reset.yaml | 8 + data/sbx_cli/sbx_policy_rm.yaml | 8 + data/sbx_cli/sbx_policy_rm_network.yaml | 8 + data/sbx_cli/sbx_ports.yaml | 36 ++++- data/sbx_cli/sbx_prune.yaml | 16 +- data/sbx_cli/sbx_reset.yaml | 8 + data/sbx_cli/sbx_rm.yaml | 22 ++- data/sbx_cli/sbx_run.yaml | 96 +++++++++++- data/sbx_cli/sbx_secret.yaml | 8 + data/sbx_cli/sbx_secret_import.yaml | 10 +- data/sbx_cli/sbx_secret_ls.yaml | 14 ++ data/sbx_cli/sbx_secret_rm.yaml | 15 ++ data/sbx_cli/sbx_secret_set-custom.yaml | 8 + data/sbx_cli/sbx_secret_set.yaml | 13 +- data/sbx_cli/sbx_setup.yaml | 12 +- data/sbx_cli/sbx_setup_ssh.yaml | 8 + data/sbx_cli/sbx_setup_ssh_remove.yaml | 8 + data/sbx_cli/sbx_skills.yaml | 24 ++- data/sbx_cli/sbx_skills_add.yaml | 48 ++++++ data/sbx_cli/sbx_skills_import.yaml | 32 ++-- data/sbx_cli/sbx_skills_ls.yaml | 18 ++- data/sbx_cli/sbx_skills_rm.yaml | 33 +++++ data/sbx_cli/sbx_skills_update.yaml | 30 ++++ data/sbx_cli/sbx_stop.yaml | 22 ++- data/sbx_cli/sbx_template.yaml | 12 ++ data/sbx_cli/sbx_template_inspect.yaml | 39 +++++ data/sbx_cli/sbx_template_load.yaml | 45 +++++- data/sbx_cli/sbx_template_ls.yaml | 8 + data/sbx_cli/sbx_template_rm.yaml | 20 ++- data/sbx_cli/sbx_template_save.yaml | 37 +++++ data/sbx_cli/sbx_ttl.yaml | 40 +++++ data/sbx_cli/sbx_tui.yaml | 8 + data/sbx_cli/sbx_version.yaml | 12 ++ data/sbx_cli/sbx_volume.yaml | 36 +++++ data/sbx_cli/sbx_volume_create.yaml | 32 ++++ data/sbx_cli/sbx_volume_inspect.yaml | 24 +++ data/sbx_cli/sbx_volume_ls.yaml | 27 ++++ data/sbx_cli/sbx_volume_rm.yaml | 33 +++++ 107 files changed, 2531 insertions(+), 389 deletions(-) create mode 100644 data/sbx_cli/sbx_attach.yaml delete mode 100644 data/sbx_cli/sbx_create_copilot.yaml create mode 100644 data/sbx_cli/sbx_create_devin.yaml delete mode 100644 data/sbx_cli/sbx_create_droid.yaml delete mode 100644 data/sbx_cli/sbx_create_kiro.yaml create mode 100644 data/sbx_cli/sbx_env_plan.yaml create mode 100644 data/sbx_cli/sbx_move.yaml create mode 100644 data/sbx_cli/sbx_skills_add.yaml create mode 100644 data/sbx_cli/sbx_skills_rm.yaml create mode 100644 data/sbx_cli/sbx_skills_update.yaml create mode 100644 data/sbx_cli/sbx_template_inspect.yaml create mode 100644 data/sbx_cli/sbx_ttl.yaml create mode 100644 data/sbx_cli/sbx_volume.yaml create mode 100644 data/sbx_cli/sbx_volume_create.yaml create mode 100644 data/sbx_cli/sbx_volume_inspect.yaml create mode 100644 data/sbx_cli/sbx_volume_ls.yaml create mode 100644 data/sbx_cli/sbx_volume_rm.yaml diff --git a/data/sbx_cli/sbx.yaml b/data/sbx_cli/sbx.yaml index 239291883da4..43852be389a5 100644 --- a/data/sbx_cli/sbx.yaml +++ b/data/sbx_cli/sbx.yaml @@ -6,6 +6,14 @@ description: |- Run without a command to launch interactive mode, or pass a command for CLI usage. usage: sbx COMMAND 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" @@ -15,18 +23,20 @@ options: default_value: "false" usage: help for sbx see_also: + - sbx attach - Attach to a running cloud sandbox - sbx completion - Generate the autocompletion script for the specified shell - sbx cp - Copy files or directories between a sandbox and the host - sbx create - Create a sandbox for an agent - sbx daemon - Manage sandboxd daemon - sbx diagnose - Diagnose common issues with your sbx installation - - sbx env - (Experimental) Manage sandboxes declaratively from a .sbxenv.yaml file + - sbx env - (Experimental) Manage sandboxes declaratively from an sbxenv.yaml file - sbx exec - Execute a command inside a sandbox - sbx kit - (Experimental) Manage kit artifacts - sbx login - Sign in to Docker - sbx logout - Stop all running sandboxes and sign out of Docker - sbx ls - List sandboxes - sbx mcp - Manage MCP servers + - sbx move - Move a sandbox between local and cloud - sbx policy - Manage sandbox policies - sbx ports - Manage sandbox port publishing - sbx prune - Remove all stopped sandboxes @@ -35,8 +45,10 @@ see_also: - sbx run - Run an agent in a sandbox - sbx secret - Manage stored secrets - sbx setup - (Experimental) Detect host configuration and prepare Docker Sandboxes - - sbx skills - (Experimental) Manage skills shared across sandboxes + - sbx skills - (Experimental) Manage skills available in sandboxes - sbx stop - Stop one or more sandboxes without removing them - sbx template - Manage sandbox templates + - sbx ttl - Inspect or extend a cloud sandbox's TTL - sbx tui - Open the interactive TUI dashboard - sbx version - Show Docker Sandboxes version information + - sbx volume - Manage persistent volumes (cloud-only) diff --git a/data/sbx_cli/sbx_attach.yaml b/data/sbx_cli/sbx_attach.yaml new file mode 100644 index 000000000000..e5cd4e808443 --- /dev/null +++ b/data/sbx_cli/sbx_attach.yaml @@ -0,0 +1,40 @@ +name: sbx attach +synopsis: Attach to a running cloud sandbox +description: |- + Attach an interactive terminal session to a running cloud sandbox. + + SANDBOX is the cloud sandbox ID (sbx_*) or name from "sbx --cloud ls". + + Opens a PTY-backed exec session against the sandbox's agent process. The + sandbox must already exist and be in a running state; use `sbx --cloud run` + to create a sandbox and attach in one step. + + Only supported with --cloud. See https://docs.docker.com/ai/sandboxes/ for the cloud sandbox model. +usage: sbx attach SANDBOX [flags] +options: + - name: detach-keys + usage: | + Override the detach gesture that leaves the agent running (Docker-style, e.g. "ctrl-\", "ctrl-x,ctrl-d"). Default: Ctrl-\. Use this when the default collides with an agent's keymap (cloud only). + - name: help + shorthand: h + default_value: "false" + usage: help for attach +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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +example: |4- + # Attach to a running sandbox by ID or name + sbx --cloud attach sbx_abc123 + sbx --cloud attach claude/my-sandbox +see_also: + - sbx - Manage AI coding agent sandboxes. diff --git a/data/sbx_cli/sbx_completion.yaml b/data/sbx_cli/sbx_completion.yaml index ecab3f1117ed..bd56b16275b4 100644 --- a/data/sbx_cli/sbx_completion.yaml +++ b/data/sbx_cli/sbx_completion.yaml @@ -10,6 +10,14 @@ options: default_value: "false" usage: help for completion 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" diff --git a/data/sbx_cli/sbx_completion_bash.yaml b/data/sbx_cli/sbx_completion_bash.yaml index 4e06d587fb52..2fb5cea1c360 100644 --- a/data/sbx_cli/sbx_completion_bash.yaml +++ b/data/sbx_cli/sbx_completion_bash.yaml @@ -31,6 +31,14 @@ options: default_value: "false" usage: disable completion descriptions 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" diff --git a/data/sbx_cli/sbx_completion_fish.yaml b/data/sbx_cli/sbx_completion_fish.yaml index 2d38fe4b2d51..bad67e06e166 100644 --- a/data/sbx_cli/sbx_completion_fish.yaml +++ b/data/sbx_cli/sbx_completion_fish.yaml @@ -22,6 +22,14 @@ options: default_value: "false" usage: disable completion descriptions 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" diff --git a/data/sbx_cli/sbx_completion_powershell.yaml b/data/sbx_cli/sbx_completion_powershell.yaml index 6a442b5d993b..7c6cd097af93 100644 --- a/data/sbx_cli/sbx_completion_powershell.yaml +++ b/data/sbx_cli/sbx_completion_powershell.yaml @@ -19,6 +19,14 @@ options: default_value: "false" usage: disable completion descriptions 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" diff --git a/data/sbx_cli/sbx_completion_zsh.yaml b/data/sbx_cli/sbx_completion_zsh.yaml index 2ccf93f0dd0b..4da7b2cf9393 100644 --- a/data/sbx_cli/sbx_completion_zsh.yaml +++ b/data/sbx_cli/sbx_completion_zsh.yaml @@ -33,6 +33,14 @@ options: default_value: "false" usage: disable completion descriptions 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" diff --git a/data/sbx_cli/sbx_cp.yaml b/data/sbx_cli/sbx_cp.yaml index 877f0efb566f..34d407a7e943 100644 --- a/data/sbx_cli/sbx_cp.yaml +++ b/data/sbx_cli/sbx_cp.yaml @@ -2,7 +2,9 @@ name: sbx cp synopsis: Copy files or directories between a sandbox and the host description: |- Either SRC or DST must be a sandbox path, written as SANDBOX:PATH. - The other must be a local path. Copying between two sandboxes is not supported. + The other must be a local path. Copying between two sandboxes is not supported. Or — with --cloud — the cloud sandbox + ID (sbx_*) or name from "sbx --cloud ls". Cloud transfers go through the Docker + Sandboxes Cloud file API instead of the local sandboxd. 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 @@ -18,6 +20,14 @@ options: default_value: "false" usage: help for cp 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" @@ -31,5 +41,9 @@ example: |4- # Copy a directory sbx cp ./src/ my-sandbox:/home/user/src + + # Copy to/from a cloud sandbox + sbx --cloud cp ./config.json sbx_abc:/workspace/config.json + sbx --cloud cp sbx_abc:/workspace/out.log ./ see_also: - sbx - Manage AI coding agent sandboxes. diff --git a/data/sbx_cli/sbx_create.yaml b/data/sbx_cli/sbx_create.yaml index 394b54071387..cdd3d3c07346 100644 --- a/data/sbx_cli/sbx_create.yaml +++ b/data/sbx_cli/sbx_create.yaml @@ -3,9 +3,23 @@ synopsis: Create a sandbox for an agent description: |- Create a sandbox with access to a host workspace for an agent. + 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. + + 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. + Use "sbx run --name SANDBOX" to attach to the agent after creation. -usage: sbx create [flags] AGENT PATH [PATH...] + + Without --cpus/--memory a cloud sandbox defaults to 2 CPUs and 4 GiB. +usage: sbx create [flags] AGENT|SANDBOX_KIT [PATH...] options: + - name: allow-network + default_value: '[]' + usage: | + Network pattern to allow for cloud sandbox egress (cloud only; can be specified multiple times) - name: clone default_value: "false" usage: | @@ -31,11 +45,24 @@ options: shorthand: h default_value: "false" usage: help for create + - name: image-ref + usage: | + OCI image reference for inline-mode cloud create (mutually exclusive with --template; requires --cpus and --memory) - name: kit default_value: '[]' experimental: true usage: | - Kit reference (directory, ZIP, or OCI). Can be specified multiple times + Additional kit reference (must be a mixin; directory, ZIP, git, or OCI). Can be specified multiple times + - name: kit-arg + default_value: '[]' + experimental: true + usage: | + Value for an argument the kit declares, as name=value for every kit or kit.name=value for one (can be repeated) + - name: kit-args-file + default_value: '[]' + experimental: true + usage: | + File of name=value kit arguments, one per line (can be repeated); --kit-arg overrides - name: memory shorthand: m usage: | @@ -43,6 +70,12 @@ options: - name: name usage: | Name for the sandbox (defaults to -; at least two characters, starting with a letter or number, containing only letters, numbers, hyphens and periods; 'default' is reserved) + - name: on-timeout + usage: | + What happens when --ttl lapses: 'delete' (default) tombstones the sandbox, or 'stop' stops it in place so it can be started again later (cloud only; 'stop' requires your account to be entitled to it). + - 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. - name: publish shorthand: p default_value: '[]' @@ -56,7 +89,25 @@ options: shorthand: t usage: | Container image to use for the sandbox (default: agent-specific image) + - name: ttl + default_value: 0s + usage: | + Cloud sandbox time-to-live before it times out (e.g. 30m, 2h; cloud only; default: server-side) + - name: volume + shorthand: v + default_value: '[]' + experimental: true + usage: | + Attach an existing persistent volume, NAME:MOUNTPATH (cloud only, experimental; repeatable) 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" @@ -71,17 +122,24 @@ example: |4- # Create with additional read-only workspaces sbx create claude . /path/to/docs:ro + # Create without a workspace bind mount + sbx create claude + + # Create from a local sandbox kit + sbx create ../path/to/my-agent/ + + # Add a mixin to a built-in agent + sbx create claude --kit ./my-mixin/ + # Run the agent on an in-container clone of the host repo, wired back via a git-daemon sbx create --clone claude . see_also: - sbx - Manage AI coding agent sandboxes. - sbx create claude - Create a sandbox for claude - sbx create codex - Create a sandbox for codex - - sbx create copilot - Create a sandbox for copilot - sbx create cursor - Create a sandbox for cursor + - sbx create devin - Create a sandbox for devin - sbx create docker-agent - Create a sandbox for docker-agent - - sbx create droid - Create a sandbox for droid - sbx create gemini - Create a sandbox for gemini - - sbx create kiro - Create a sandbox for kiro - sbx create opencode - Create a sandbox for opencode - sbx create shell - Create a sandbox for shell diff --git a/data/sbx_cli/sbx_create_claude.yaml b/data/sbx_cli/sbx_create_claude.yaml index 9f3fd598ea74..4209ce25600f 100644 --- a/data/sbx_cli/sbx_create_claude.yaml +++ b/data/sbx_cli/sbx_create_claude.yaml @@ -3,22 +3,40 @@ synopsis: Create a sandbox for claude description: |- Create a sandbox with access to a host workspace for claude. - The workspace path is required and will be mounted inside the sandbox at the - same path as on the host. Additional workspaces can be provided as extra - arguments. Append ":ro" to mount them read-only. + The workspace path is mounted inside the sandbox at the same path as on the + host. Additional workspaces can be provided as extra arguments. Append ":ro" to + mount them read-only; a read-only argument may name a single file, which holds + that one path out of reach inside a workspace the sandbox can otherwise write. + + 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. Use "sbx run --name SANDBOX" to attach to the agent after creation. -usage: sbx create claude PATH [PATH...] [flags] + + Without --cpus/--memory a cloud sandbox defaults to 2 CPUs and 4 GiB. +usage: sbx create claude [PATH...] [flags] options: - name: help shorthand: h default_value: "false" usage: help for claude inherited_options: + - name: allow-network + default_value: '[]' + usage: | + Network pattern to allow for cloud sandbox egress (cloud only; can be specified multiple times) - name: clone default_value: "false" usage: | Run the agent on a private in-container clone of the host Git repository (mounted read-only) instead of bind-mounting the workspace; the agent's commits are accessible via the sandbox- git remote on the host + - 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: cpus default_value: "0" usage: | @@ -40,11 +58,24 @@ inherited_options: default_value: '[]' usage: | Read environment variables from a file (can be repeated). --env wins over any file; a later file wins over an earlier one + - name: image-ref + usage: | + OCI image reference for inline-mode cloud create (mutually exclusive with --template; requires --cpus and --memory) - name: kit default_value: '[]' experimental: true usage: | - Kit reference (directory, ZIP, or OCI). Can be specified multiple times + Additional kit reference (must be a mixin; directory, ZIP, git, or OCI). Can be specified multiple times + - name: kit-arg + default_value: '[]' + experimental: true + usage: | + Value for an argument the kit declares, as name=value for every kit or kit.name=value for one (can be repeated) + - name: kit-args-file + default_value: '[]' + experimental: true + usage: | + File of name=value kit arguments, one per line (can be repeated); --kit-arg overrides - name: memory shorthand: m usage: | @@ -52,6 +83,12 @@ inherited_options: - name: name usage: | Name for the sandbox (defaults to -; at least two characters, starting with a letter or number, containing only letters, numbers, hyphens and periods; 'default' is reserved) + - name: on-timeout + usage: | + What happens when --ttl lapses: 'delete' (default) tombstones the sandbox, or 'stop' stops it in place so it can be started again later (cloud only; 'stop' requires your account to be entitled to it). + - 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. - name: publish shorthand: p default_value: '[]' @@ -65,6 +102,16 @@ inherited_options: shorthand: t usage: | Container image to use for the sandbox (default: agent-specific image) + - name: ttl + default_value: 0s + usage: | + Cloud sandbox time-to-live before it times out (e.g. 30m, 2h; cloud only; default: server-side) + - name: volume + shorthand: v + default_value: '[]' + experimental: true + usage: | + Attach an existing persistent volume, NAME:MOUNTPATH (cloud only, experimental; repeatable) example: |4- # Create in the current directory sbx create claude . @@ -74,5 +121,8 @@ example: |4- # Create with additional read-only workspaces sbx create claude . /path/to/docs:ro + + # Create without a workspace bind mount + sbx create claude see_also: - sbx create - Create a sandbox for an agent diff --git a/data/sbx_cli/sbx_create_codex.yaml b/data/sbx_cli/sbx_create_codex.yaml index f1d3bece138d..2111b92f8d3f 100644 --- a/data/sbx_cli/sbx_create_codex.yaml +++ b/data/sbx_cli/sbx_create_codex.yaml @@ -3,22 +3,40 @@ synopsis: Create a sandbox for codex description: |- Create a sandbox with access to a host workspace for codex. - The workspace path is required and will be mounted inside the sandbox at the - same path as on the host. Additional workspaces can be provided as extra - arguments. Append ":ro" to mount them read-only. + The workspace path is mounted inside the sandbox at the same path as on the + host. Additional workspaces can be provided as extra arguments. Append ":ro" to + mount them read-only; a read-only argument may name a single file, which holds + that one path out of reach inside a workspace the sandbox can otherwise write. + + 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. Use "sbx run --name SANDBOX" to attach to the agent after creation. -usage: sbx create codex PATH [PATH...] [flags] + + Without --cpus/--memory a cloud sandbox defaults to 2 CPUs and 4 GiB. +usage: sbx create codex [PATH...] [flags] options: - name: help shorthand: h default_value: "false" usage: help for codex inherited_options: + - name: allow-network + default_value: '[]' + usage: | + Network pattern to allow for cloud sandbox egress (cloud only; can be specified multiple times) - name: clone default_value: "false" usage: | Run the agent on a private in-container clone of the host Git repository (mounted read-only) instead of bind-mounting the workspace; the agent's commits are accessible via the sandbox- git remote on the host + - 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: cpus default_value: "0" usage: | @@ -40,11 +58,24 @@ inherited_options: default_value: '[]' usage: | Read environment variables from a file (can be repeated). --env wins over any file; a later file wins over an earlier one + - name: image-ref + usage: | + OCI image reference for inline-mode cloud create (mutually exclusive with --template; requires --cpus and --memory) - name: kit default_value: '[]' experimental: true usage: | - Kit reference (directory, ZIP, or OCI). Can be specified multiple times + Additional kit reference (must be a mixin; directory, ZIP, git, or OCI). Can be specified multiple times + - name: kit-arg + default_value: '[]' + experimental: true + usage: | + Value for an argument the kit declares, as name=value for every kit or kit.name=value for one (can be repeated) + - name: kit-args-file + default_value: '[]' + experimental: true + usage: | + File of name=value kit arguments, one per line (can be repeated); --kit-arg overrides - name: memory shorthand: m usage: | @@ -52,6 +83,12 @@ inherited_options: - name: name usage: | Name for the sandbox (defaults to -; at least two characters, starting with a letter or number, containing only letters, numbers, hyphens and periods; 'default' is reserved) + - name: on-timeout + usage: | + What happens when --ttl lapses: 'delete' (default) tombstones the sandbox, or 'stop' stops it in place so it can be started again later (cloud only; 'stop' requires your account to be entitled to it). + - 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. - name: publish shorthand: p default_value: '[]' @@ -65,6 +102,16 @@ inherited_options: shorthand: t usage: | Container image to use for the sandbox (default: agent-specific image) + - name: ttl + default_value: 0s + usage: | + Cloud sandbox time-to-live before it times out (e.g. 30m, 2h; cloud only; default: server-side) + - name: volume + shorthand: v + default_value: '[]' + experimental: true + usage: | + Attach an existing persistent volume, NAME:MOUNTPATH (cloud only, experimental; repeatable) example: |4- # Create in the current directory sbx create codex . @@ -74,5 +121,8 @@ example: |4- # Create with additional read-only workspaces sbx create codex . /path/to/docs:ro + + # Create without a workspace bind mount + sbx create codex see_also: - sbx create - Create a sandbox for an agent diff --git a/data/sbx_cli/sbx_create_copilot.yaml b/data/sbx_cli/sbx_create_copilot.yaml deleted file mode 100644 index 29d8a9d559be..000000000000 --- a/data/sbx_cli/sbx_create_copilot.yaml +++ /dev/null @@ -1,78 +0,0 @@ -name: sbx create copilot -synopsis: Create a sandbox for copilot -description: |- - Create a sandbox with access to a host workspace for copilot. - - The workspace path is required and will be mounted inside the sandbox at the - same path as on the host. Additional workspaces can be provided as extra - arguments. Append ":ro" to mount them read-only. - - Use "sbx run --name SANDBOX" to attach to the agent after creation. -usage: sbx create copilot PATH [PATH...] [flags] -options: - - name: help - shorthand: h - default_value: "false" - usage: help for copilot -inherited_options: - - name: clone - default_value: "false" - usage: | - Run the agent on a private in-container clone of the host Git repository (mounted read-only) instead of bind-mounting the workspace; the agent's commits are accessible via the sandbox- git remote on the host - - name: cpus - default_value: "0" - usage: | - Number of CPUs to allocate to the sandbox (0 = auto: all host CPUs) - - name: debug - shorthand: D - default_value: "false" - usage: Enable debug logging - - name: deny-network - default_value: '[]' - usage: | - Add a per-sandbox network deny rule at creation time. Can be specified multiple times. The rule applies only to the new sandbox and can be listed or removed later with `sbx policy ls ` / `sbx policy rm network --sandbox --resource `. Safe under centralized governance because a local deny can only narrow, never widen, egress. - - name: env - shorthand: e - default_value: '[]' - usage: | - Set an environment variable in the sandbox (can be repeated): KEY=VALUE, or a bare KEY to take the value from the current environment - - name: env-file - default_value: '[]' - usage: | - Read environment variables from a file (can be repeated). --env wins over any file; a later file wins over an earlier one - - name: kit - default_value: '[]' - experimental: true - usage: | - Kit reference (directory, ZIP, or OCI). Can be specified multiple times - - name: memory - shorthand: m - usage: | - Memory limit in binary units (e.g., 1024m, 8g). Default: 50% of host memory, max 32 GiB - - name: name - usage: | - Name for the sandbox (defaults to -; at least two characters, starting with a letter or number, containing only letters, numbers, hyphens and periods; 'default' is reserved) - - name: publish - shorthand: p - default_value: '[]' - usage: | - Publish a sandbox port to the host (can be repeated): [[HOST_IP:]HOST_PORT:]SANDBOX_PORT[/PROTOCOL] - - name: quiet - shorthand: q - default_value: "false" - usage: Suppress verbose output - - name: template - shorthand: t - usage: | - Container image to use for the sandbox (default: agent-specific image) -example: |4- - # Create in the current directory - sbx create copilot . - - # Create with a specific path - sbx create copilot /path/to/project - - # Create with additional read-only workspaces - sbx create copilot . /path/to/docs:ro -see_also: - - sbx create - Create a sandbox for an agent diff --git a/data/sbx_cli/sbx_create_cursor.yaml b/data/sbx_cli/sbx_create_cursor.yaml index fb7564c1ff3a..7ba037184bae 100644 --- a/data/sbx_cli/sbx_create_cursor.yaml +++ b/data/sbx_cli/sbx_create_cursor.yaml @@ -3,22 +3,40 @@ synopsis: Create a sandbox for cursor description: |- Create a sandbox with access to a host workspace for cursor. - The workspace path is required and will be mounted inside the sandbox at the - same path as on the host. Additional workspaces can be provided as extra - arguments. Append ":ro" to mount them read-only. + The workspace path is mounted inside the sandbox at the same path as on the + host. Additional workspaces can be provided as extra arguments. Append ":ro" to + mount them read-only; a read-only argument may name a single file, which holds + that one path out of reach inside a workspace the sandbox can otherwise write. + + 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. Use "sbx run --name SANDBOX" to attach to the agent after creation. -usage: sbx create cursor PATH [PATH...] [flags] + + Without --cpus/--memory a cloud sandbox defaults to 2 CPUs and 4 GiB. +usage: sbx create cursor [PATH...] [flags] options: - name: help shorthand: h default_value: "false" usage: help for cursor inherited_options: + - name: allow-network + default_value: '[]' + usage: | + Network pattern to allow for cloud sandbox egress (cloud only; can be specified multiple times) - name: clone default_value: "false" usage: | Run the agent on a private in-container clone of the host Git repository (mounted read-only) instead of bind-mounting the workspace; the agent's commits are accessible via the sandbox- git remote on the host + - 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: cpus default_value: "0" usage: | @@ -40,11 +58,24 @@ inherited_options: default_value: '[]' usage: | Read environment variables from a file (can be repeated). --env wins over any file; a later file wins over an earlier one + - name: image-ref + usage: | + OCI image reference for inline-mode cloud create (mutually exclusive with --template; requires --cpus and --memory) - name: kit default_value: '[]' experimental: true usage: | - Kit reference (directory, ZIP, or OCI). Can be specified multiple times + Additional kit reference (must be a mixin; directory, ZIP, git, or OCI). Can be specified multiple times + - name: kit-arg + default_value: '[]' + experimental: true + usage: | + Value for an argument the kit declares, as name=value for every kit or kit.name=value for one (can be repeated) + - name: kit-args-file + default_value: '[]' + experimental: true + usage: | + File of name=value kit arguments, one per line (can be repeated); --kit-arg overrides - name: memory shorthand: m usage: | @@ -52,6 +83,12 @@ inherited_options: - name: name usage: | Name for the sandbox (defaults to -; at least two characters, starting with a letter or number, containing only letters, numbers, hyphens and periods; 'default' is reserved) + - name: on-timeout + usage: | + What happens when --ttl lapses: 'delete' (default) tombstones the sandbox, or 'stop' stops it in place so it can be started again later (cloud only; 'stop' requires your account to be entitled to it). + - 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. - name: publish shorthand: p default_value: '[]' @@ -65,6 +102,16 @@ inherited_options: shorthand: t usage: | Container image to use for the sandbox (default: agent-specific image) + - name: ttl + default_value: 0s + usage: | + Cloud sandbox time-to-live before it times out (e.g. 30m, 2h; cloud only; default: server-side) + - name: volume + shorthand: v + default_value: '[]' + experimental: true + usage: | + Attach an existing persistent volume, NAME:MOUNTPATH (cloud only, experimental; repeatable) example: |4- # Create in the current directory sbx create cursor . @@ -74,5 +121,8 @@ example: |4- # Create with additional read-only workspaces sbx create cursor . /path/to/docs:ro + + # Create without a workspace bind mount + sbx create cursor see_also: - sbx create - Create a sandbox for an agent diff --git a/data/sbx_cli/sbx_create_devin.yaml b/data/sbx_cli/sbx_create_devin.yaml new file mode 100644 index 000000000000..c64eccad4e50 --- /dev/null +++ b/data/sbx_cli/sbx_create_devin.yaml @@ -0,0 +1,128 @@ +name: sbx create devin +synopsis: Create a sandbox for devin +description: |- + Create a sandbox with access to a host workspace for devin. + + The workspace path is mounted inside the sandbox at the same path as on the + host. Additional workspaces can be provided as extra arguments. Append ":ro" to + mount them read-only; a read-only argument may name a single file, which holds + that one path out of reach inside a workspace the sandbox can otherwise write. + + 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. + + Use "sbx run --name SANDBOX" to attach to the agent after creation. + + Without --cpus/--memory a cloud sandbox defaults to 2 CPUs and 4 GiB. +usage: sbx create devin [PATH...] [flags] +options: + - name: help + shorthand: h + default_value: "false" + usage: help for devin +inherited_options: + - name: allow-network + default_value: '[]' + usage: | + Network pattern to allow for cloud sandbox egress (cloud only; can be specified multiple times) + - name: clone + default_value: "false" + usage: | + Run the agent on a private in-container clone of the host Git repository (mounted read-only) instead of bind-mounting the workspace; the agent's commits are accessible via the sandbox- git remote on the host + - 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. + - name: cpus + default_value: "0" + usage: | + Number of CPUs to allocate to the sandbox (0 = auto: all host CPUs) + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging + - name: deny-network + default_value: '[]' + usage: | + Add a per-sandbox network deny rule at creation time. Can be specified multiple times. The rule applies only to the new sandbox and can be listed or removed later with `sbx policy ls ` / `sbx policy rm network --sandbox --resource `. Safe under centralized governance because a local deny can only narrow, never widen, egress. + - name: env + shorthand: e + default_value: '[]' + usage: | + Set an environment variable in the sandbox (can be repeated): KEY=VALUE, or a bare KEY to take the value from the current environment + - name: env-file + default_value: '[]' + usage: | + Read environment variables from a file (can be repeated). --env wins over any file; a later file wins over an earlier one + - name: image-ref + usage: | + OCI image reference for inline-mode cloud create (mutually exclusive with --template; requires --cpus and --memory) + - name: kit + default_value: '[]' + experimental: true + usage: | + Additional kit reference (must be a mixin; directory, ZIP, git, or OCI). Can be specified multiple times + - name: kit-arg + default_value: '[]' + experimental: true + usage: | + Value for an argument the kit declares, as name=value for every kit or kit.name=value for one (can be repeated) + - name: kit-args-file + default_value: '[]' + experimental: true + usage: | + File of name=value kit arguments, one per line (can be repeated); --kit-arg overrides + - name: memory + shorthand: m + usage: | + Memory limit in binary units (e.g., 1024m, 8g). Default: 50% of host memory, max 32 GiB + - name: name + usage: | + Name for the sandbox (defaults to -; at least two characters, starting with a letter or number, containing only letters, numbers, hyphens and periods; 'default' is reserved) + - name: on-timeout + usage: | + What happens when --ttl lapses: 'delete' (default) tombstones the sandbox, or 'stop' stops it in place so it can be started again later (cloud only; 'stop' requires your account to be entitled to it). + - 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. + - name: publish + shorthand: p + default_value: '[]' + usage: | + Publish a sandbox port to the host (can be repeated): [[HOST_IP:]HOST_PORT:]SANDBOX_PORT[/PROTOCOL] + - name: quiet + shorthand: q + default_value: "false" + usage: Suppress verbose output + - name: template + shorthand: t + usage: | + Container image to use for the sandbox (default: agent-specific image) + - name: ttl + default_value: 0s + usage: | + Cloud sandbox time-to-live before it times out (e.g. 30m, 2h; cloud only; default: server-side) + - name: volume + shorthand: v + default_value: '[]' + experimental: true + usage: | + Attach an existing persistent volume, NAME:MOUNTPATH (cloud only, experimental; repeatable) +example: |4- + # Create in the current directory + sbx create devin . + + # Create with a specific path + sbx create devin /path/to/project + + # Create with additional read-only workspaces + sbx create devin . /path/to/docs:ro + + # Create without a workspace bind mount + sbx create devin +see_also: + - sbx create - Create a sandbox for an agent diff --git a/data/sbx_cli/sbx_create_docker-agent.yaml b/data/sbx_cli/sbx_create_docker-agent.yaml index 2dc8938a2d0b..c0d366e2d637 100644 --- a/data/sbx_cli/sbx_create_docker-agent.yaml +++ b/data/sbx_cli/sbx_create_docker-agent.yaml @@ -3,22 +3,40 @@ synopsis: Create a sandbox for docker-agent description: |- Create a sandbox with access to a host workspace for docker-agent. - The workspace path is required and will be mounted inside the sandbox at the - same path as on the host. Additional workspaces can be provided as extra - arguments. Append ":ro" to mount them read-only. + The workspace path is mounted inside the sandbox at the same path as on the + host. Additional workspaces can be provided as extra arguments. Append ":ro" to + mount them read-only; a read-only argument may name a single file, which holds + that one path out of reach inside a workspace the sandbox can otherwise write. + + 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. Use "sbx run --name SANDBOX" to attach to the agent after creation. -usage: sbx create docker-agent PATH [PATH...] [flags] + + Without --cpus/--memory a cloud sandbox defaults to 2 CPUs and 4 GiB. +usage: sbx create docker-agent [PATH...] [flags] options: - name: help shorthand: h default_value: "false" usage: help for docker-agent inherited_options: + - name: allow-network + default_value: '[]' + usage: | + Network pattern to allow for cloud sandbox egress (cloud only; can be specified multiple times) - name: clone default_value: "false" usage: | Run the agent on a private in-container clone of the host Git repository (mounted read-only) instead of bind-mounting the workspace; the agent's commits are accessible via the sandbox- git remote on the host + - 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: cpus default_value: "0" usage: | @@ -40,11 +58,24 @@ inherited_options: default_value: '[]' usage: | Read environment variables from a file (can be repeated). --env wins over any file; a later file wins over an earlier one + - name: image-ref + usage: | + OCI image reference for inline-mode cloud create (mutually exclusive with --template; requires --cpus and --memory) - name: kit default_value: '[]' experimental: true usage: | - Kit reference (directory, ZIP, or OCI). Can be specified multiple times + Additional kit reference (must be a mixin; directory, ZIP, git, or OCI). Can be specified multiple times + - name: kit-arg + default_value: '[]' + experimental: true + usage: | + Value for an argument the kit declares, as name=value for every kit or kit.name=value for one (can be repeated) + - name: kit-args-file + default_value: '[]' + experimental: true + usage: | + File of name=value kit arguments, one per line (can be repeated); --kit-arg overrides - name: memory shorthand: m usage: | @@ -52,6 +83,12 @@ inherited_options: - name: name usage: | Name for the sandbox (defaults to -; at least two characters, starting with a letter or number, containing only letters, numbers, hyphens and periods; 'default' is reserved) + - name: on-timeout + usage: | + What happens when --ttl lapses: 'delete' (default) tombstones the sandbox, or 'stop' stops it in place so it can be started again later (cloud only; 'stop' requires your account to be entitled to it). + - 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. - name: publish shorthand: p default_value: '[]' @@ -65,6 +102,16 @@ inherited_options: shorthand: t usage: | Container image to use for the sandbox (default: agent-specific image) + - name: ttl + default_value: 0s + usage: | + Cloud sandbox time-to-live before it times out (e.g. 30m, 2h; cloud only; default: server-side) + - name: volume + shorthand: v + default_value: '[]' + experimental: true + usage: | + Attach an existing persistent volume, NAME:MOUNTPATH (cloud only, experimental; repeatable) example: |4- # Create in the current directory sbx create docker-agent . @@ -74,5 +121,8 @@ example: |4- # Create with additional read-only workspaces sbx create docker-agent . /path/to/docs:ro + + # Create without a workspace bind mount + sbx create docker-agent see_also: - sbx create - Create a sandbox for an agent diff --git a/data/sbx_cli/sbx_create_droid.yaml b/data/sbx_cli/sbx_create_droid.yaml deleted file mode 100644 index 168e70ccff8e..000000000000 --- a/data/sbx_cli/sbx_create_droid.yaml +++ /dev/null @@ -1,78 +0,0 @@ -name: sbx create droid -synopsis: Create a sandbox for droid -description: |- - Create a sandbox with access to a host workspace for droid. - - The workspace path is required and will be mounted inside the sandbox at the - same path as on the host. Additional workspaces can be provided as extra - arguments. Append ":ro" to mount them read-only. - - Use "sbx run --name SANDBOX" to attach to the agent after creation. -usage: sbx create droid PATH [PATH...] [flags] -options: - - name: help - shorthand: h - default_value: "false" - usage: help for droid -inherited_options: - - name: clone - default_value: "false" - usage: | - Run the agent on a private in-container clone of the host Git repository (mounted read-only) instead of bind-mounting the workspace; the agent's commits are accessible via the sandbox- git remote on the host - - name: cpus - default_value: "0" - usage: | - Number of CPUs to allocate to the sandbox (0 = auto: all host CPUs) - - name: debug - shorthand: D - default_value: "false" - usage: Enable debug logging - - name: deny-network - default_value: '[]' - usage: | - Add a per-sandbox network deny rule at creation time. Can be specified multiple times. The rule applies only to the new sandbox and can be listed or removed later with `sbx policy ls ` / `sbx policy rm network --sandbox --resource `. Safe under centralized governance because a local deny can only narrow, never widen, egress. - - name: env - shorthand: e - default_value: '[]' - usage: | - Set an environment variable in the sandbox (can be repeated): KEY=VALUE, or a bare KEY to take the value from the current environment - - name: env-file - default_value: '[]' - usage: | - Read environment variables from a file (can be repeated). --env wins over any file; a later file wins over an earlier one - - name: kit - default_value: '[]' - experimental: true - usage: | - Kit reference (directory, ZIP, or OCI). Can be specified multiple times - - name: memory - shorthand: m - usage: | - Memory limit in binary units (e.g., 1024m, 8g). Default: 50% of host memory, max 32 GiB - - name: name - usage: | - Name for the sandbox (defaults to -; at least two characters, starting with a letter or number, containing only letters, numbers, hyphens and periods; 'default' is reserved) - - name: publish - shorthand: p - default_value: '[]' - usage: | - Publish a sandbox port to the host (can be repeated): [[HOST_IP:]HOST_PORT:]SANDBOX_PORT[/PROTOCOL] - - name: quiet - shorthand: q - default_value: "false" - usage: Suppress verbose output - - name: template - shorthand: t - usage: | - Container image to use for the sandbox (default: agent-specific image) -example: |4- - # Create in the current directory - sbx create droid . - - # Create with a specific path - sbx create droid /path/to/project - - # Create with additional read-only workspaces - sbx create droid . /path/to/docs:ro -see_also: - - sbx create - Create a sandbox for an agent diff --git a/data/sbx_cli/sbx_create_gemini.yaml b/data/sbx_cli/sbx_create_gemini.yaml index cc3fd9165813..962372fcb626 100644 --- a/data/sbx_cli/sbx_create_gemini.yaml +++ b/data/sbx_cli/sbx_create_gemini.yaml @@ -3,22 +3,40 @@ synopsis: Create a sandbox for gemini description: |- Create a sandbox with access to a host workspace for gemini. - The workspace path is required and will be mounted inside the sandbox at the - same path as on the host. Additional workspaces can be provided as extra - arguments. Append ":ro" to mount them read-only. + The workspace path is mounted inside the sandbox at the same path as on the + host. Additional workspaces can be provided as extra arguments. Append ":ro" to + mount them read-only; a read-only argument may name a single file, which holds + that one path out of reach inside a workspace the sandbox can otherwise write. + + 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. Use "sbx run --name SANDBOX" to attach to the agent after creation. -usage: sbx create gemini PATH [PATH...] [flags] + + Without --cpus/--memory a cloud sandbox defaults to 2 CPUs and 4 GiB. +usage: sbx create gemini [PATH...] [flags] options: - name: help shorthand: h default_value: "false" usage: help for gemini inherited_options: + - name: allow-network + default_value: '[]' + usage: | + Network pattern to allow for cloud sandbox egress (cloud only; can be specified multiple times) - name: clone default_value: "false" usage: | Run the agent on a private in-container clone of the host Git repository (mounted read-only) instead of bind-mounting the workspace; the agent's commits are accessible via the sandbox- git remote on the host + - 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: cpus default_value: "0" usage: | @@ -40,11 +58,24 @@ inherited_options: default_value: '[]' usage: | Read environment variables from a file (can be repeated). --env wins over any file; a later file wins over an earlier one + - name: image-ref + usage: | + OCI image reference for inline-mode cloud create (mutually exclusive with --template; requires --cpus and --memory) - name: kit default_value: '[]' experimental: true usage: | - Kit reference (directory, ZIP, or OCI). Can be specified multiple times + Additional kit reference (must be a mixin; directory, ZIP, git, or OCI). Can be specified multiple times + - name: kit-arg + default_value: '[]' + experimental: true + usage: | + Value for an argument the kit declares, as name=value for every kit or kit.name=value for one (can be repeated) + - name: kit-args-file + default_value: '[]' + experimental: true + usage: | + File of name=value kit arguments, one per line (can be repeated); --kit-arg overrides - name: memory shorthand: m usage: | @@ -52,6 +83,12 @@ inherited_options: - name: name usage: | Name for the sandbox (defaults to -; at least two characters, starting with a letter or number, containing only letters, numbers, hyphens and periods; 'default' is reserved) + - name: on-timeout + usage: | + What happens when --ttl lapses: 'delete' (default) tombstones the sandbox, or 'stop' stops it in place so it can be started again later (cloud only; 'stop' requires your account to be entitled to it). + - 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. - name: publish shorthand: p default_value: '[]' @@ -65,6 +102,16 @@ inherited_options: shorthand: t usage: | Container image to use for the sandbox (default: agent-specific image) + - name: ttl + default_value: 0s + usage: | + Cloud sandbox time-to-live before it times out (e.g. 30m, 2h; cloud only; default: server-side) + - name: volume + shorthand: v + default_value: '[]' + experimental: true + usage: | + Attach an existing persistent volume, NAME:MOUNTPATH (cloud only, experimental; repeatable) example: |4- # Create in the current directory sbx create gemini . @@ -74,5 +121,8 @@ example: |4- # Create with additional read-only workspaces sbx create gemini . /path/to/docs:ro + + # Create without a workspace bind mount + sbx create gemini see_also: - sbx create - Create a sandbox for an agent diff --git a/data/sbx_cli/sbx_create_kiro.yaml b/data/sbx_cli/sbx_create_kiro.yaml deleted file mode 100644 index 2008da0763ea..000000000000 --- a/data/sbx_cli/sbx_create_kiro.yaml +++ /dev/null @@ -1,78 +0,0 @@ -name: sbx create kiro -synopsis: Create a sandbox for kiro -description: |- - Create a sandbox with access to a host workspace for kiro. - - The workspace path is required and will be mounted inside the sandbox at the - same path as on the host. Additional workspaces can be provided as extra - arguments. Append ":ro" to mount them read-only. - - Use "sbx run --name SANDBOX" to attach to the agent after creation. -usage: sbx create kiro PATH [PATH...] [flags] -options: - - name: help - shorthand: h - default_value: "false" - usage: help for kiro -inherited_options: - - name: clone - default_value: "false" - usage: | - Run the agent on a private in-container clone of the host Git repository (mounted read-only) instead of bind-mounting the workspace; the agent's commits are accessible via the sandbox- git remote on the host - - name: cpus - default_value: "0" - usage: | - Number of CPUs to allocate to the sandbox (0 = auto: all host CPUs) - - name: debug - shorthand: D - default_value: "false" - usage: Enable debug logging - - name: deny-network - default_value: '[]' - usage: | - Add a per-sandbox network deny rule at creation time. Can be specified multiple times. The rule applies only to the new sandbox and can be listed or removed later with `sbx policy ls ` / `sbx policy rm network --sandbox --resource `. Safe under centralized governance because a local deny can only narrow, never widen, egress. - - name: env - shorthand: e - default_value: '[]' - usage: | - Set an environment variable in the sandbox (can be repeated): KEY=VALUE, or a bare KEY to take the value from the current environment - - name: env-file - default_value: '[]' - usage: | - Read environment variables from a file (can be repeated). --env wins over any file; a later file wins over an earlier one - - name: kit - default_value: '[]' - experimental: true - usage: | - Kit reference (directory, ZIP, or OCI). Can be specified multiple times - - name: memory - shorthand: m - usage: | - Memory limit in binary units (e.g., 1024m, 8g). Default: 50% of host memory, max 32 GiB - - name: name - usage: | - Name for the sandbox (defaults to -; at least two characters, starting with a letter or number, containing only letters, numbers, hyphens and periods; 'default' is reserved) - - name: publish - shorthand: p - default_value: '[]' - usage: | - Publish a sandbox port to the host (can be repeated): [[HOST_IP:]HOST_PORT:]SANDBOX_PORT[/PROTOCOL] - - name: quiet - shorthand: q - default_value: "false" - usage: Suppress verbose output - - name: template - shorthand: t - usage: | - Container image to use for the sandbox (default: agent-specific image) -example: |4- - # Create in the current directory - sbx create kiro . - - # Create with a specific path - sbx create kiro /path/to/project - - # Create with additional read-only workspaces - sbx create kiro . /path/to/docs:ro -see_also: - - sbx create - Create a sandbox for an agent diff --git a/data/sbx_cli/sbx_create_opencode.yaml b/data/sbx_cli/sbx_create_opencode.yaml index 298a78de304f..0f97904d8e14 100644 --- a/data/sbx_cli/sbx_create_opencode.yaml +++ b/data/sbx_cli/sbx_create_opencode.yaml @@ -3,22 +3,40 @@ synopsis: Create a sandbox for opencode description: |- Create a sandbox with access to a host workspace for opencode. - The workspace path is required and will be mounted inside the sandbox at the - same path as on the host. Additional workspaces can be provided as extra - arguments. Append ":ro" to mount them read-only. + The workspace path is mounted inside the sandbox at the same path as on the + host. Additional workspaces can be provided as extra arguments. Append ":ro" to + mount them read-only; a read-only argument may name a single file, which holds + that one path out of reach inside a workspace the sandbox can otherwise write. + + 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. Use "sbx run --name SANDBOX" to attach to the agent after creation. -usage: sbx create opencode PATH [PATH...] [flags] + + Without --cpus/--memory a cloud sandbox defaults to 2 CPUs and 4 GiB. +usage: sbx create opencode [PATH...] [flags] options: - name: help shorthand: h default_value: "false" usage: help for opencode inherited_options: + - name: allow-network + default_value: '[]' + usage: | + Network pattern to allow for cloud sandbox egress (cloud only; can be specified multiple times) - name: clone default_value: "false" usage: | Run the agent on a private in-container clone of the host Git repository (mounted read-only) instead of bind-mounting the workspace; the agent's commits are accessible via the sandbox- git remote on the host + - 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: cpus default_value: "0" usage: | @@ -40,11 +58,24 @@ inherited_options: default_value: '[]' usage: | Read environment variables from a file (can be repeated). --env wins over any file; a later file wins over an earlier one + - name: image-ref + usage: | + OCI image reference for inline-mode cloud create (mutually exclusive with --template; requires --cpus and --memory) - name: kit default_value: '[]' experimental: true usage: | - Kit reference (directory, ZIP, or OCI). Can be specified multiple times + Additional kit reference (must be a mixin; directory, ZIP, git, or OCI). Can be specified multiple times + - name: kit-arg + default_value: '[]' + experimental: true + usage: | + Value for an argument the kit declares, as name=value for every kit or kit.name=value for one (can be repeated) + - name: kit-args-file + default_value: '[]' + experimental: true + usage: | + File of name=value kit arguments, one per line (can be repeated); --kit-arg overrides - name: memory shorthand: m usage: | @@ -52,6 +83,12 @@ inherited_options: - name: name usage: | Name for the sandbox (defaults to -; at least two characters, starting with a letter or number, containing only letters, numbers, hyphens and periods; 'default' is reserved) + - name: on-timeout + usage: | + What happens when --ttl lapses: 'delete' (default) tombstones the sandbox, or 'stop' stops it in place so it can be started again later (cloud only; 'stop' requires your account to be entitled to it). + - 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. - name: publish shorthand: p default_value: '[]' @@ -65,6 +102,16 @@ inherited_options: shorthand: t usage: | Container image to use for the sandbox (default: agent-specific image) + - name: ttl + default_value: 0s + usage: | + Cloud sandbox time-to-live before it times out (e.g. 30m, 2h; cloud only; default: server-side) + - name: volume + shorthand: v + default_value: '[]' + experimental: true + usage: | + Attach an existing persistent volume, NAME:MOUNTPATH (cloud only, experimental; repeatable) example: |4- # Create in the current directory sbx create opencode . @@ -74,5 +121,8 @@ example: |4- # Create with additional read-only workspaces sbx create opencode . /path/to/docs:ro + + # Create without a workspace bind mount + sbx create opencode see_also: - sbx create - Create a sandbox for an agent diff --git a/data/sbx_cli/sbx_create_shell.yaml b/data/sbx_cli/sbx_create_shell.yaml index 1d56a4309479..72ef9c183027 100644 --- a/data/sbx_cli/sbx_create_shell.yaml +++ b/data/sbx_cli/sbx_create_shell.yaml @@ -3,22 +3,40 @@ synopsis: Create a sandbox for shell description: |- Create a sandbox with access to a host workspace for shell. - The workspace path is required and will be mounted inside the sandbox at the - same path as on the host. Additional workspaces can be provided as extra - arguments. Append ":ro" to mount them read-only. + The workspace path is mounted inside the sandbox at the same path as on the + host. Additional workspaces can be provided as extra arguments. Append ":ro" to + mount them read-only; a read-only argument may name a single file, which holds + that one path out of reach inside a workspace the sandbox can otherwise write. + + 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. Use "sbx run --name SANDBOX" to attach to the agent after creation. -usage: sbx create shell PATH [PATH...] [flags] + + Without --cpus/--memory a cloud sandbox defaults to 2 CPUs and 4 GiB. +usage: sbx create shell [PATH...] [flags] options: - name: help shorthand: h default_value: "false" usage: help for shell inherited_options: + - name: allow-network + default_value: '[]' + usage: | + Network pattern to allow for cloud sandbox egress (cloud only; can be specified multiple times) - name: clone default_value: "false" usage: | Run the agent on a private in-container clone of the host Git repository (mounted read-only) instead of bind-mounting the workspace; the agent's commits are accessible via the sandbox- git remote on the host + - 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: cpus default_value: "0" usage: | @@ -40,11 +58,24 @@ inherited_options: default_value: '[]' usage: | Read environment variables from a file (can be repeated). --env wins over any file; a later file wins over an earlier one + - name: image-ref + usage: | + OCI image reference for inline-mode cloud create (mutually exclusive with --template; requires --cpus and --memory) - name: kit default_value: '[]' experimental: true usage: | - Kit reference (directory, ZIP, or OCI). Can be specified multiple times + Additional kit reference (must be a mixin; directory, ZIP, git, or OCI). Can be specified multiple times + - name: kit-arg + default_value: '[]' + experimental: true + usage: | + Value for an argument the kit declares, as name=value for every kit or kit.name=value for one (can be repeated) + - name: kit-args-file + default_value: '[]' + experimental: true + usage: | + File of name=value kit arguments, one per line (can be repeated); --kit-arg overrides - name: memory shorthand: m usage: | @@ -52,6 +83,12 @@ inherited_options: - name: name usage: | Name for the sandbox (defaults to -; at least two characters, starting with a letter or number, containing only letters, numbers, hyphens and periods; 'default' is reserved) + - name: on-timeout + usage: | + What happens when --ttl lapses: 'delete' (default) tombstones the sandbox, or 'stop' stops it in place so it can be started again later (cloud only; 'stop' requires your account to be entitled to it). + - 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. - name: publish shorthand: p default_value: '[]' @@ -65,6 +102,16 @@ inherited_options: shorthand: t usage: | Container image to use for the sandbox (default: agent-specific image) + - name: ttl + default_value: 0s + usage: | + Cloud sandbox time-to-live before it times out (e.g. 30m, 2h; cloud only; default: server-side) + - name: volume + shorthand: v + default_value: '[]' + experimental: true + usage: | + Attach an existing persistent volume, NAME:MOUNTPATH (cloud only, experimental; repeatable) example: |4- # Create in the current directory sbx create shell . @@ -74,5 +121,8 @@ example: |4- # Create with additional read-only workspaces sbx create shell . /path/to/docs:ro + + # Create without a workspace bind mount + sbx create shell see_also: - sbx create - Create a sandbox for an agent diff --git a/data/sbx_cli/sbx_daemon.yaml b/data/sbx_cli/sbx_daemon.yaml index f7a913bd4683..31acae707a35 100644 --- a/data/sbx_cli/sbx_daemon.yaml +++ b/data/sbx_cli/sbx_daemon.yaml @@ -7,6 +7,14 @@ options: default_value: "false" usage: help for daemon 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" diff --git a/data/sbx_cli/sbx_daemon_log-level.yaml b/data/sbx_cli/sbx_daemon_log-level.yaml index 20822ef1bd11..377ead36b651 100644 --- a/data/sbx_cli/sbx_daemon_log-level.yaml +++ b/data/sbx_cli/sbx_daemon_log-level.yaml @@ -7,6 +7,14 @@ options: default_value: "false" usage: help for log-level 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" diff --git a/data/sbx_cli/sbx_daemon_log-level_set.yaml b/data/sbx_cli/sbx_daemon_log-level_set.yaml index d3da38752bbb..407fcf47fa6b 100644 --- a/data/sbx_cli/sbx_daemon_log-level_set.yaml +++ b/data/sbx_cli/sbx_daemon_log-level_set.yaml @@ -7,6 +7,14 @@ options: default_value: "false" usage: help for set 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" diff --git a/data/sbx_cli/sbx_daemon_restart.yaml b/data/sbx_cli/sbx_daemon_restart.yaml index d7bea6d0f156..bac4258ce9d9 100644 --- a/data/sbx_cli/sbx_daemon_restart.yaml +++ b/data/sbx_cli/sbx_daemon_restart.yaml @@ -7,6 +7,14 @@ options: default_value: "false" usage: help for restart 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" diff --git a/data/sbx_cli/sbx_daemon_start.yaml b/data/sbx_cli/sbx_daemon_start.yaml index 879c93c62015..f7d356add977 100644 --- a/data/sbx_cli/sbx_daemon_start.yaml +++ b/data/sbx_cli/sbx_daemon_start.yaml @@ -14,6 +14,14 @@ options: usage: | Initialize the global network policy: "allow-all", "balanced", or "deny-all" 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" diff --git a/data/sbx_cli/sbx_daemon_status.yaml b/data/sbx_cli/sbx_daemon_status.yaml index 9b3c790e76de..f03c928631f6 100644 --- a/data/sbx_cli/sbx_daemon_status.yaml +++ b/data/sbx_cli/sbx_daemon_status.yaml @@ -10,6 +10,14 @@ options: default_value: "false" usage: Output as JSON 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" diff --git a/data/sbx_cli/sbx_daemon_stop.yaml b/data/sbx_cli/sbx_daemon_stop.yaml index d703903cb3ac..2fa9e93487c2 100644 --- a/data/sbx_cli/sbx_daemon_stop.yaml +++ b/data/sbx_cli/sbx_daemon_stop.yaml @@ -7,6 +7,14 @@ options: default_value: "false" usage: help for stop 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" diff --git a/data/sbx_cli/sbx_diagnose.yaml b/data/sbx_cli/sbx_diagnose.yaml index e0eac7110fd6..72d3e2eb25f4 100644 --- a/data/sbx_cli/sbx_diagnose.yaml +++ b/data/sbx_cli/sbx_diagnose.yaml @@ -6,6 +6,9 @@ options: shorthand: h default_value: "false" usage: help for diagnose + - name: json + default_value: "false" + usage: Output in JSON format (alias for --output json) - name: output shorthand: o usage: 'Output format: "json" or "github-issue"' @@ -13,6 +16,14 @@ options: default_value: "false" usage: Upload diagnostics to Docker support 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" diff --git a/data/sbx_cli/sbx_env.yaml b/data/sbx_cli/sbx_env.yaml index 9c64d66c74ee..4346c7a249f7 100644 --- a/data/sbx_cli/sbx_env.yaml +++ b/data/sbx_cli/sbx_env.yaml @@ -1,14 +1,152 @@ name: sbx env synopsis: | - Manage sandboxes declaratively from a .sbxenv.yaml file + Manage sandboxes declaratively from an sbxenv.yaml file experimental: true description: |- - Manage a sandbox environment declared in a .sbxenv.yaml file. + Manage a sandbox environment declared in an sbxenv.yaml file. 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. + + 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`. + + 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, + resolved against the project directory: the one holding the first PATH, or the + current directory when none is named. `workspace: .` mounts the project from + whichever file declares it. 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:`, 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, which is also what a relative "workspace:" resolves against, and is + shared by commands merged in from a file elsewhere. 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 PLAN + claude-proj + + secrets: + + anthropic: + + ref: op://vault/anthropic/key + + refresh: 55m + + lifecycle: + initialize: + ~ - command: make setup -> make setup && make seed + workdir: /Users/me/proj + + Plan: + 1 to add, ~ 1 to change, - 0 to destroy. + + Approve this plan? [y/N] + + The plan is your file: the same keys, nested the same way, in the order the + blocks are declared in, so a line is looked up where it was written. What the + plan adds is the margin, and the two values a line moves between. The totals + name every symbol the margin 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, a note in the margin 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. + + An attribute shows what 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: + ~ - source: ./mixins/tool + ~ args: + ~ version: 1.2.3 -> 1.2.4 + env: + ~ GOFLAGS: -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 --auto-approve (-y) 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. usage: sbx env COMMAND options: - name: help @@ -16,13 +154,22 @@ options: default_value: "false" usage: help for env 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" usage: Enable debug logging see_also: - sbx - Manage AI coding agent sandboxes. - - sbx env create - Create a sandbox environment from .sbxenv.yaml + - sbx env create - Create a sandbox environment from sbxenv.yaml - sbx env exec - Execute a command inside a sandbox environment + - sbx env plan - Show what an environment would change outside the sandbox - sbx env rm - Remove a sandbox environment and its scoped resources - sbx env run - Create (if needed) and attach to a sandbox environment diff --git a/data/sbx_cli/sbx_env_create.yaml b/data/sbx_cli/sbx_env_create.yaml index 1048fa27ea5f..c6aeb98a2811 100644 --- a/data/sbx_cli/sbx_env_create.yaml +++ b/data/sbx_cli/sbx_env_create.yaml @@ -1,30 +1,80 @@ name: sbx env create -synopsis: Create a sandbox environment from .sbxenv.yaml +synopsis: Create a sandbox environment from sbxenv.yaml experimental: true description: |- Read the environment file from PATH (default: current directory), provision its declared secrets at the sandbox scope, merge its credential bindings, and create the sandbox. Use "sbx env run" to attach. - Each PATH may be a directory (the file is /.sbxenv.yaml) or the + Each PATH may be a directory (the file is /sbxenv.yaml) or the path to the environment file itself. Passing more than one PATH deep-merges them in order (docker-compose `-f` semantics): later files override earlier ones. - Values may reference environment variables with ${VAR} / $VAR (and - ${VAR:-default}); see the docs for the full syntax. + Values may reference the arguments the file declares with ${{ env.args.NAME }}, + supplied by --env-arg. 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:" or "workspace:", each of which + identifies a single project. Changing its "agent:" changes the derived + - 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. usage: sbx env create [PATH...] [flags] options: + - name: auto-approve + shorthand: "y" + default_value: "false" + usage: Apply the environment plan without asking - name: clone default_value: "false" usage: | - Override workspace.clone in .sbxenv.yaml (see 'sbx create --clone') + Override workspace.clone in sbxenv.yaml (see 'sbx create --clone') + - name: env-arg + default_value: '[]' + experimental: true + usage: | + Value for an argument the environment file declares, as name=value (can be repeated) + - name: env-args-file + default_value: '[]' + experimental: true + usage: | + File of name=value environment arguments, one per line (can be repeated); --env-arg overrides - name: help shorthand: h default_value: "false" usage: help for create + - name: kit-arg + default_value: '[]' + experimental: true + usage: | + Value for an argument a kit declares, as name=value for every kit or kit.name=value for one (can be repeated); overrides the args a kits: entry pins in sbxenv.yaml + - name: kit-args-file + default_value: '[]' + experimental: true + usage: | + File of name=value kit arguments, one per line (can be repeated); --kit-arg overrides + - name: skip-host-commands + default_value: "false" + usage: Skip the host lifecycle commands the environment declares 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" usage: Enable debug logging see_also: - - sbx env - (Experimental) Manage sandboxes declaratively from a .sbxenv.yaml file + - sbx env - (Experimental) Manage sandboxes declaratively from an sbxenv.yaml file diff --git a/data/sbx_cli/sbx_env_exec.yaml b/data/sbx_cli/sbx_env_exec.yaml index 225789753ab1..a9a1dc4ae45e 100644 --- a/data/sbx_cli/sbx_env_exec.yaml +++ b/data/sbx_cli/sbx_env_exec.yaml @@ -2,17 +2,32 @@ name: sbx env exec synopsis: Execute a command inside a sandbox environment experimental: true description: |- - Run COMMAND in the sandbox declared in .sbxenv.yaml. The sandbox + Run COMMAND in the sandbox declared in sbxenv.yaml. The sandbox must already exist (see "sbx env create" and "sbx env run"); a stopped sandbox is started first. Arguments before `--` are environment-file paths, following the same rules as the other "sbx env" subcommands: each PATH may be a directory (the file is - /.sbxenv.yaml) or the path to the environment file itself, and passing + /sbxenv.yaml) or the path to the environment file itself, and passing more than one deep-merges them in order. Without a `--` every positional 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:" or "workspace:", each of which + identifies a single project. Changing its "agent:" changes the derived + - 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. + Flags match the behavior of "sbx exec". usage: sbx env exec [flags] [PATH...] -- COMMAND [ARG...] options: @@ -26,6 +41,16 @@ options: shorthand: e default_value: '[]' usage: Set environment variables + - name: env-arg + default_value: '[]' + experimental: true + usage: | + Value for an argument the environment file declares, as name=value (can be repeated) + - name: env-args-file + default_value: '[]' + experimental: true + usage: | + File of name=value environment arguments, one per line (can be repeated); --env-arg overrides - name: env-file default_value: '[]' usage: Read in a file of environment variables @@ -51,6 +76,14 @@ options: shorthand: w usage: Working directory inside the container 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" @@ -63,6 +96,6 @@ example: |4- sbx env exec -it -- bash # Run against explicitly merged environment files - sbx env exec .sbxenv.yaml override.yaml -- npm test + sbx env exec sbxenv.yaml override.yaml -- npm test see_also: - - sbx env - (Experimental) Manage sandboxes declaratively from a .sbxenv.yaml file + - sbx env - (Experimental) Manage sandboxes declaratively from an sbxenv.yaml file diff --git a/data/sbx_cli/sbx_env_plan.yaml b/data/sbx_cli/sbx_env_plan.yaml new file mode 100644 index 000000000000..4e48161870fb --- /dev/null +++ b/data/sbx_cli/sbx_env_plan.yaml @@ -0,0 +1,82 @@ +name: sbx env plan +synopsis: Show what an environment would change outside the sandbox +experimental: true +description: |- + Read the environment file from PATH (default: current directory) and print + everything applying it would set up: the host commands it runs, the credentials + and bindings it provisions, the MCP servers it registers, the directories it + creates, the ports it publishes, and the sandbox itself along with the variables + it runs with. + + The plan is compared against what this environment last applied on this machine, + against what was approved where nothing applied it, and against what is there + now, so a second run shows only what moved. Nothing is applied, approved, or + recorded: use "sbx env create" or "sbx env run" for that. + + Each PATH may be a directory (the file is /sbxenv.yaml) or the + 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:" or "workspace:", each of which + identifies a single project. Changing its "agent:" changes the derived + - 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. +usage: sbx env plan [PATH...] [flags] +options: + - name: clone + default_value: "false" + usage: | + Override workspace.clone in sbxenv.yaml (see 'sbx create --clone') + - name: env-arg + default_value: '[]' + experimental: true + usage: | + Value for an argument the environment file declares, as name=value (can be repeated) + - name: env-args-file + default_value: '[]' + experimental: true + usage: | + File of name=value environment arguments, one per line (can be repeated); --env-arg overrides + - name: help + shorthand: h + default_value: "false" + usage: help for plan + - name: kit-arg + default_value: '[]' + experimental: true + usage: | + Value for an argument a kit declares, as name=value for every kit or kit.name=value for one (can be repeated); overrides the args a kits: entry pins in sbxenv.yaml + - name: kit-args-file + default_value: '[]' + experimental: true + usage: | + File of name=value kit arguments, one per line (can be repeated); --kit-arg overrides + - name: skip-host-commands + default_value: "false" + usage: | + Plan without the host lifecycle commands the environment declares +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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +see_also: + - sbx env - (Experimental) Manage sandboxes declaratively from an sbxenv.yaml file diff --git a/data/sbx_cli/sbx_env_rm.yaml b/data/sbx_cli/sbx_env_rm.yaml index 5f43f20ade82..c6d939392dc3 100644 --- a/data/sbx_cli/sbx_env_rm.yaml +++ b/data/sbx_cli/sbx_env_rm.yaml @@ -2,22 +2,48 @@ name: sbx env rm synopsis: Remove a sandbox environment and its scoped resources experimental: true description: |- - Remove the sandbox declared in .sbxenv.yaml along with the + Remove the sandbox declared in sbxenv.yaml along with the secret values provisioned at its sandbox scope (service, custom, and registry credentials). Global credential bindings are left in place by default since they are user-wide and may be shared with other sandboxes; pass --prune-bindings to also remove the bindings this environment declares. - Each PATH may be a directory (the file is /.sbxenv.yaml) or the + Each PATH may be a directory (the file is /sbxenv.yaml) or the path to the environment file itself. Passing more than one PATH deep-merges them 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:" or "workspace:", each of which + identifies a single project. Changing its "agent:" changes the derived + - 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. usage: sbx env rm [PATH...] [flags] options: + - name: env-arg + default_value: '[]' + experimental: true + usage: | + Value for an argument the environment file declares, as name=value (can be repeated) + - name: env-args-file + default_value: '[]' + experimental: true + usage: | + File of name=value environment arguments, one per line (can be repeated); --env-arg overrides - name: force shorthand: f default_value: "false" - usage: Skip confirmation prompts + usage: | + Skip confirmation prompts and delete even if in use (e.g. an open SSH connection) - name: help shorthand: h default_value: "false" @@ -26,10 +52,21 @@ options: default_value: "false" usage: | 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 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" usage: Enable debug logging see_also: - - sbx env - (Experimental) Manage sandboxes declaratively from a .sbxenv.yaml file + - sbx env - (Experimental) Manage sandboxes declaratively from an sbxenv.yaml file diff --git a/data/sbx_cli/sbx_env_run.yaml b/data/sbx_cli/sbx_env_run.yaml index f23ca8f61518..8e3de71e4b9c 100644 --- a/data/sbx_cli/sbx_env_run.yaml +++ b/data/sbx_cli/sbx_env_run.yaml @@ -7,29 +7,79 @@ description: |- and re-attached without re-provisioning; otherwise it is created first (provisioning secrets and bindings) and then attached. - Each PATH may be a directory (the file is /.sbxenv.yaml) or the + Each PATH may be a directory (the file is /sbxenv.yaml) or the path to the environment file itself. Passing more than one PATH deep-merges them in order (docker-compose `-f` semantics): later files override earlier ones. - Values may reference environment variables with ${VAR} / $VAR (and - ${VAR:-default}); see the docs for the full syntax. + Values may reference the arguments the file declares with ${{ env.args.NAME }}, + supplied by --env-arg. 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:" or "workspace:", each of which + identifies a single project. Changing its "agent:" changes the derived + - 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. usage: sbx env run [PATH...] [flags] options: + - name: auto-approve + shorthand: "y" + default_value: "false" + usage: Apply the environment plan without asking - name: clone default_value: "false" usage: | - Override workspace.clone in .sbxenv.yaml (see 'sbx create --clone') + Override workspace.clone in sbxenv.yaml (see 'sbx create --clone') - name: detached shorthand: d default_value: "false" usage: Create/start the sandbox without attaching + - name: env-arg + default_value: '[]' + experimental: true + usage: | + Value for an argument the environment file declares, as name=value (can be repeated) + - name: env-args-file + default_value: '[]' + experimental: true + usage: | + File of name=value environment arguments, one per line (can be repeated); --env-arg overrides - name: help shorthand: h default_value: "false" usage: help for run + - name: kit-arg + default_value: '[]' + experimental: true + usage: | + Value for an argument a kit declares, as name=value for every kit or kit.name=value for one (can be repeated); overrides the args a kits: entry pins in sbxenv.yaml + - name: kit-args-file + default_value: '[]' + experimental: true + usage: | + File of name=value kit arguments, one per line (can be repeated); --kit-arg overrides + - name: skip-host-commands + default_value: "false" + usage: Skip the host lifecycle commands the environment declares 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" usage: Enable debug logging see_also: - - sbx env - (Experimental) Manage sandboxes declaratively from a .sbxenv.yaml file + - sbx env - (Experimental) Manage sandboxes declaratively from an sbxenv.yaml file diff --git a/data/sbx_cli/sbx_exec.yaml b/data/sbx_cli/sbx_exec.yaml index d060aad82f1f..6062a32fe355 100644 --- a/data/sbx_cli/sbx_exec.yaml +++ b/data/sbx_cli/sbx_exec.yaml @@ -1,9 +1,12 @@ name: sbx exec synopsis: Execute a command inside a sandbox description: |- - Execute a command in a sandbox. If the sandbox is stopped, it is started first. + Execute a command in a sandbox. If the sandbox is stopped, it is started first. Or — with --cloud — the cloud sandbox + ID (sbx_*) or name from "sbx --cloud ls". - Flags match the behavior of "docker exec". + Flags match the behavior of "docker exec". 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. usage: sbx exec [flags] SANDBOX COMMAND [ARG...] options: - name: detach @@ -41,6 +44,14 @@ options: shorthand: w usage: Working directory inside the container 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" @@ -54,5 +65,9 @@ example: |4- # Run as root sbx exec -u root my-sandbox apt-get update + + # Cloud: run a command in a cloud sandbox by ID or name + sbx --cloud exec -it sbx_abc123 bash + sbx --cloud exec -it claude/my-sandbox bash see_also: - sbx - Manage AI coding agent sandboxes. diff --git a/data/sbx_cli/sbx_kit.yaml b/data/sbx_cli/sbx_kit.yaml index 1fd478705799..28a9042c3fe8 100644 --- a/data/sbx_cli/sbx_kit.yaml +++ b/data/sbx_cli/sbx_kit.yaml @@ -4,8 +4,9 @@ experimental: true description: |- Manage kit artifacts. - Kits are declarative YAML artifacts that extend sandbox agents with additional - credentials, network policies, environment variables, startup commands, and files. + Kits are declarative YAML artifacts that define sandbox agents or extend them + with additional credentials, network policies, environment variables, startup + commands, and files. usage: sbx kit COMMAND options: - name: help @@ -13,13 +14,21 @@ options: default_value: "false" usage: help for kit 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" usage: Enable debug logging see_also: - sbx - Manage AI coding agent sandboxes. - - sbx kit add - Add a kit to a sandbox + - sbx kit add - Add a mixin to a sandbox - sbx kit inspect - Display details about a kit artifact - sbx kit pack - Package a directory as a kit artifact - sbx kit provenance - Show the SLSA provenance attached to a kit diff --git a/data/sbx_cli/sbx_kit_add.yaml b/data/sbx_cli/sbx_kit_add.yaml index e768a304ebca..2e5ffc528a97 100644 --- a/data/sbx_cli/sbx_kit_add.yaml +++ b/data/sbx_cli/sbx_kit_add.yaml @@ -1,8 +1,8 @@ name: sbx kit add -synopsis: Add a kit to a sandbox +synopsis: Add a mixin to a sandbox experimental: true description: |- - Add a kit artifact to an existing sandbox. + Add a mixin artifact to an existing sandbox. The sandbox's container is recreated with the new kit appended to its original kit list, preserving kit-owned volumes (e.g. agent session @@ -22,13 +22,31 @@ options: shorthand: h default_value: "false" usage: help for add + - name: kit-arg + default_value: '[]' + experimental: true + usage: | + Value for an argument the kit declares, as name=value for every kit or kit.name=value for one (can be repeated) + - name: kit-args-file + default_value: '[]' + experimental: true + usage: | + File of name=value kit arguments, one per line (can be repeated); --kit-arg overrides 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" usage: Enable debug logging example: |4- - # Add a local kit directory to a sandbox + # Add a local mixin directory to a sandbox sbx kit add my-sandbox ./mcp-postgres/ # Add a kit from a ZIP file @@ -39,5 +57,8 @@ example: |4- # Add a kit from a git repository sbx kit add my-sandbox git+https://github.com/org/kits.git#dir=mcp-postgres + + # Add a parameterized kit + sbx kit add my-sandbox ./mcp-postgres/ --kit-arg host=db.internal see_also: - sbx kit - (Experimental) Manage kit artifacts diff --git a/data/sbx_cli/sbx_kit_inspect.yaml b/data/sbx_cli/sbx_kit_inspect.yaml index fd985cceafbc..48761638b744 100644 --- a/data/sbx_cli/sbx_kit_inspect.yaml +++ b/data/sbx_cli/sbx_kit_inspect.yaml @@ -5,6 +5,9 @@ description: |- Load and display details about a kit artifact. The reference can be a local directory, ZIP file path, OCI registry reference, or git repository. + + Pass --kit-arg to preview how the kit resolves with a given set of + arguments; the output shows the substituted content. usage: sbx kit inspect REFERENCE [flags] options: - name: help @@ -14,7 +17,25 @@ options: - name: json default_value: "false" usage: Output in JSON format + - name: kit-arg + default_value: '[]' + experimental: true + usage: | + Value for an argument the kit declares, as name=value for every kit or kit.name=value for one (can be repeated) + - name: kit-args-file + default_value: '[]' + experimental: true + usage: | + File of name=value kit arguments, one per line (can be repeated); --kit-arg overrides 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" diff --git a/data/sbx_cli/sbx_kit_pack.yaml b/data/sbx_cli/sbx_kit_pack.yaml index 7c5d37569fdc..d46cd4bc6d82 100644 --- a/data/sbx_cli/sbx_kit_pack.yaml +++ b/data/sbx_cli/sbx_kit_pack.yaml @@ -15,6 +15,14 @@ options: shorthand: o usage: 'Output ZIP file path (default: .zip)' 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" diff --git a/data/sbx_cli/sbx_kit_provenance.yaml b/data/sbx_cli/sbx_kit_provenance.yaml index 07a876d49427..dd2e17bf344e 100644 --- a/data/sbx_cli/sbx_kit_provenance.yaml +++ b/data/sbx_cli/sbx_kit_provenance.yaml @@ -33,9 +33,20 @@ options: default_value: "false" usage: | Do not require a Rekor transparency-log entry (for private keyless signatures) + - name: json + default_value: "false" + usage: Output in JSON format - name: key usage: Public key for key-based verification (PEM) 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" diff --git a/data/sbx_cli/sbx_kit_pull.yaml b/data/sbx_cli/sbx_kit_pull.yaml index 1440d608a268..f240f131c867 100644 --- a/data/sbx_cli/sbx_kit_pull.yaml +++ b/data/sbx_cli/sbx_kit_pull.yaml @@ -24,6 +24,14 @@ options: shorthand: o usage: 'Output file path (default: derived from reference + format)' 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" diff --git a/data/sbx_cli/sbx_kit_push.yaml b/data/sbx_cli/sbx_kit_push.yaml index 9b4a6ac355d5..dfe8ccf5923d 100644 --- a/data/sbx_cli/sbx_kit_push.yaml +++ b/data/sbx_cli/sbx_kit_push.yaml @@ -24,7 +24,9 @@ description: |- 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 uses the Docker credential store. + 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. usage: sbx kit push DIRECTORY REFERENCE [flags] options: - name: help @@ -49,6 +51,14 @@ options: usage: | Upload the keyless signature to the Rekor transparency log; set false for private kits 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" diff --git a/data/sbx_cli/sbx_kit_sign.yaml b/data/sbx_cli/sbx_kit_sign.yaml index 7319af55f301..88431ea3ce6a 100644 --- a/data/sbx_cli/sbx_kit_sign.yaml +++ b/data/sbx_cli/sbx_kit_sign.yaml @@ -45,6 +45,14 @@ options: usage: | Upload the keyless signature to the Rekor transparency log; set false for private kits 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" diff --git a/data/sbx_cli/sbx_kit_validate.yaml b/data/sbx_cli/sbx_kit_validate.yaml index f11453753d1f..0551d7e51e33 100644 --- a/data/sbx_cli/sbx_kit_validate.yaml +++ b/data/sbx_cli/sbx_kit_validate.yaml @@ -5,13 +5,38 @@ description: |- Validate that a directory or ZIP file is a valid kit artifact. The reference can be a local directory, ZIP file path, or git repository. + + 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. usage: sbx kit validate REFERENCE [flags] options: - name: help shorthand: h default_value: "false" usage: help for validate + - name: json + default_value: "false" + usage: Output in JSON format + - name: kit-arg + default_value: '[]' + experimental: true + usage: | + Value for an argument the kit declares, as name=value for every kit or kit.name=value for one (can be repeated) + - name: kit-args-file + default_value: '[]' + experimental: true + usage: | + File of name=value kit arguments, one per line (can be repeated); --kit-arg overrides 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" diff --git a/data/sbx_cli/sbx_kit_verify.yaml b/data/sbx_cli/sbx_kit_verify.yaml index 8c5552fb362f..fa01fa619867 100644 --- a/data/sbx_cli/sbx_kit_verify.yaml +++ b/data/sbx_cli/sbx_kit_verify.yaml @@ -37,9 +37,20 @@ options: default_value: "false" usage: | Do not require a Rekor transparency-log entry (for private keyless signatures) + - name: json + default_value: "false" + usage: Output in JSON format - name: key usage: Public key for key-based verification (PEM) 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" diff --git a/data/sbx_cli/sbx_login.yaml b/data/sbx_cli/sbx_login.yaml index 4c3c996e03a8..08e61f0129d0 100644 --- a/data/sbx_cli/sbx_login.yaml +++ b/data/sbx_cli/sbx_login.yaml @@ -12,6 +12,14 @@ options: - name: username usage: Docker username for non-interactive login 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" diff --git a/data/sbx_cli/sbx_logout.yaml b/data/sbx_cli/sbx_logout.yaml index aaba60ee737b..815733b1880f 100644 --- a/data/sbx_cli/sbx_logout.yaml +++ b/data/sbx_cli/sbx_logout.yaml @@ -11,6 +11,14 @@ options: default_value: "false" usage: Skip confirmation prompt 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" diff --git a/data/sbx_cli/sbx_ls.yaml b/data/sbx_cli/sbx_ls.yaml index 51f664b2744f..e300738adecf 100644 --- a/data/sbx_cli/sbx_ls.yaml +++ b/data/sbx_cli/sbx_ls.yaml @@ -16,6 +16,14 @@ options: default_value: "false" usage: Only display sandbox names 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" diff --git a/data/sbx_cli/sbx_mcp.yaml b/data/sbx_cli/sbx_mcp.yaml index 9136744af8d9..0ab0dd9842b7 100644 --- a/data/sbx_cli/sbx_mcp.yaml +++ b/data/sbx_cli/sbx_mcp.yaml @@ -9,6 +9,14 @@ options: default_value: "false" usage: help for mcp 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" diff --git a/data/sbx_cli/sbx_mcp_add.yaml b/data/sbx_cli/sbx_mcp_add.yaml index 579f5a3dff10..011203fb1c5d 100644 --- a/data/sbx_cli/sbx_mcp_add.yaml +++ b/data/sbx_cli/sbx_mcp_add.yaml @@ -24,15 +24,16 @@ description: |- 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 rejected by the SSRF guard (this protects - against manifest URLs that reach internal services, cloud metadata, or - DNS-rebinding targets). 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. - Pass --skip-ssrf-check to opt out of the guard for a single add when you - trust the host. This also disables DNS-rebinding/redirect re-checks, so - use it only for URLs you control. + 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. + Pass --skip-ssrf-check to silence the check entirely for a single add when + you trust the host; 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 @@ -42,8 +43,10 @@ description: |- 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). In this CLI it - must be accompanied by --client-id. + (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 @@ -90,16 +93,35 @@ description: |- field is optional in RFC 8414), the requirement cannot be determined and the add proceeds as usual. - Default OAuth scopes (--scope): + 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). These are requested by 'sbx mcp auth' - when it is run with no --scope of its own. Scopes are validated only when the - authorization server advertises a supported set (RFC 8414 scopes_supported): - then every scope must be a member or the add fails naming the offending - scope(s). If the server advertises no supported set (the field is optional in - RFC 8414), the requested scopes are accepted as given. --scope applies both to - a hand-supplied override and to a plain --url server whose OAuth metadata is - discovered. + 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) > nothing, and + "nothing" means the 'scope' parameter is OMITTED so the authorization server + applies its own default grant (RFC 6749 §3.3). The server's advertised set is + never requested wholesale. + + 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 it and takes the server's default grant. + + Scopes you name are validated only when the authorization server advertises a + supported set (RFC 8414 scopes_supported): then every scope must be a member or + the add fails naming the offending scope(s). If the server advertises no + supported set (the field is optional in RFC 8414), the requested scopes are + accepted as given. A set derived from the resource's own required list is never + validated — it is the server's statement about itself, and scopes_supported is + allowed to be non-exhaustive. Validation is a spelling check, not a promise: scopes_supported is what + the server SUPPORTS, not what it will grant this client, so a scope it + advertises 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. Alternative input — local stdio command (--command + --args): The command runs as a subprocess on the HOST, outside the sandbox. @@ -128,25 +150,37 @@ options: - name: local default_value: "false" usage: Run registry OCI server locally via docker run + - name: no-scope + default_value: "false" + usage: | + Request no scopes during add-time authorization, so the authorization server applies its own default grant. Suppresses the resource's required set; cannot be combined with --scope. Applies to --url remote OAuth servers. - name: oauth-authorization-server usage: | Path or http(s) URL to an RFC 8414 oauth-authorization-server metadata JSON document - name: scope default_value: '[]' usage: | - Default OAuth scope to request at consent time (repeatable; must be advertised by the server's authorization metadata). Applies to --url remote OAuth servers. - - name: skip-ssrf-check + Default OAuth scope to request at consent time (repeatable; must be advertised by the server's authorization metadata, which does not promise the server will grant it). With no --scope, the scope set the resource itself requires is requested; with neither, no scopes are requested and the authorization server applies its own default grant. Applies to --url remote OAuth servers. + - name: skip-auth default_value: "false" usage: | - Disable the SSRF guard for this add: allow a --url whose host resolves to a private/metadata address (operator asserts the host is trusted) - - name: skip_auth + Register an OAuth server without starting the hosted OAuth flow + - name: skip-ssrf-check default_value: "false" usage: | - Register an OAuth server without starting the hosted OAuth flow + Silence the SSRF check for this add: a --url whose host resolves to a private/metadata address is registered either way, but with this flag no warning is printed (operator asserts the host is trusted) - name: url usage: | MCP server manifest URL, remote endpoint URL, or dhi.io image ref 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" @@ -189,6 +223,9 @@ example: |4- # by the server's authorization metadata; repeat --scope for each one) sbx mcp add acme --url https://mcp.acme.com/mcp --scope read --scope write + # URN- and URL-shaped scope values are ordinary scopes and need no quoting + sbx mcp add fastmail --url https://api.fastmail.com/mcp --scope https://www.fastmail.com/dev/mcp --scope offline_access + # Local stdio command (runs on host — development only) sbx mcp add github --command npx --args @modelcontextprotocol/server-github sbx mcp add postgres --command docker --args "run,-i,--rm,mcp/postgres" diff --git a/data/sbx_cli/sbx_mcp_auth.yaml b/data/sbx_cli/sbx_mcp_auth.yaml index 1271b8c91b47..f68e983f160b 100644 --- a/data/sbx_cli/sbx_mcp_auth.yaml +++ b/data/sbx_cli/sbx_mcp_auth.yaml @@ -19,11 +19,36 @@ description: |- local MCP server registrations. Pass --scope (repeatable) to authorize a specific set of scopes for this run, - overriding the default recorded at 'sbx mcp add' time. Scopes are validated only - when the server advertises a supported set (RFC 8414 scopes_supported); each - scope must then be a member or the command fails. If the server advertises no - supported set, the requested scopes are accepted as given. With no --scope and - no recorded default, all advertised scopes are requested. + overriding the default recorded at 'sbx mcp add' time. Precedence is --no-scope > + an explicit --scope > the recorded default > the scope set the RESOURCE says it + requires (from its RFC 9728 metadata or its WWW-Authenticate challenge) > nothing. + With none of those, the 'scope' parameter is OMITTED and the authorization server + applies its own default grant. The server's advertised set is never requested + wholesale. + + A resource that publishes a required set therefore gets it requested without any + flag, and the consent block marks that set as derived rather than chosen. Pass + --no-scope to suppress it and take the server's default grant instead. + + Scopes you choose are validated only when the server advertises a supported set + (RFC 8414 scopes_supported); each scope must then be a member or the command + fails. If the server advertises no supported set, the requested scopes are + accepted as given. A set derived from the resource's own required list is never + validated: it is the server's statement about itself, and scopes_supported is + allowed to be non-exhaustive. + Membership is not a promise: scopes_supported is what the server SUPPORTS, not + what it will grant this client, so an advertised scope can still be refused at + consent time. In local data-plane mode a refusal prints the requested set, the + advertised set, the scopes the server named, and a narrower retry command; the + hosted control plane reports only that authorization failed or timed out. + + For an existing or freshly completed authorization, the GRANTED set — what the + authorization server actually handed over — is reported alongside the status. An + authorization server may grant less than was asked for; when it restates no set + at all, RFC 6749 §5.1 makes that the set that was requested. + + Scope values may be URN-shaped (urn:ietf:params:oauth:scope:mail) or URL-shaped + (https://www.fastmail.com/dev/mcp); neither needs quoting. usage: sbx mcp auth [server-name] [flags] options: - name: all @@ -36,14 +61,29 @@ options: shorthand: h default_value: "false" usage: help for auth + - name: json + default_value: "false" + usage: Output in JSON format (alias for --format json) + - name: no-scope + default_value: "false" + usage: | + Request no scopes at all for this run, so the authorization server applies its own default grant. Suppresses both the recorded default and the resource's required set; cannot be combined with --scope - name: scope default_value: '[]' usage: | - OAuth scope to authorize for this run (repeatable; overrides the recorded default; must be advertised by the server's authorization metadata) + OAuth scope to authorize for this run (repeatable; overrides the recorded default; must be advertised by the server's authorization metadata, which does not promise the server will grant it). With no --scope and no recorded default, the scope set the resource itself requires is requested; with none of those, no scopes are requested and the authorization server applies its own default grant - name: verbose default_value: "false" usage: Print authorization polling progress 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" @@ -56,6 +96,7 @@ example: |4- sbx mcp auth --all sbx mcp auth notion sbx mcp auth notion --scope read --scope write + sbx mcp auth notion --no-scope see_also: - sbx mcp - Manage MCP servers - sbx mcp auth rm - Remove MCP server OAuth credentials diff --git a/data/sbx_cli/sbx_mcp_auth_rm.yaml b/data/sbx_cli/sbx_mcp_auth_rm.yaml index c2e351a8e3e7..cae196e5401d 100644 --- a/data/sbx_cli/sbx_mcp_auth_rm.yaml +++ b/data/sbx_cli/sbx_mcp_auth_rm.yaml @@ -17,7 +17,18 @@ options: shorthand: h default_value: "false" usage: help for rm + - name: json + default_value: "false" + usage: Output in JSON format (alias for --format json) 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" diff --git a/data/sbx_cli/sbx_mcp_auth_status.yaml b/data/sbx_cli/sbx_mcp_auth_status.yaml index f667b9454d84..4c7b59d9065b 100644 --- a/data/sbx_cli/sbx_mcp_auth_status.yaml +++ b/data/sbx_cli/sbx_mcp_auth_status.yaml @@ -16,7 +16,18 @@ options: shorthand: h default_value: "false" usage: help for status + - name: json + default_value: "false" + usage: Output in JSON format (alias for --format json) 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" diff --git a/data/sbx_cli/sbx_mcp_inspect.yaml b/data/sbx_cli/sbx_mcp_inspect.yaml index b9490f01d089..f15a289d4875 100644 --- a/data/sbx_cli/sbx_mcp_inspect.yaml +++ b/data/sbx_cli/sbx_mcp_inspect.yaml @@ -6,11 +6,26 @@ options: shorthand: h default_value: "false" usage: help for inspect + - name: json + default_value: "false" + usage: Output in JSON format 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" usage: Enable debug logging -example: ' sbx mcp inspect notion' +example: |4- + sbx mcp inspect notion + + # Machine-readable output for scripting + sbx mcp inspect notion --json see_also: - sbx mcp - Manage MCP servers diff --git a/data/sbx_cli/sbx_mcp_load.yaml b/data/sbx_cli/sbx_mcp_load.yaml index 90dc46aa1d88..da3b0d975a76 100644 --- a/data/sbx_cli/sbx_mcp_load.yaml +++ b/data/sbx_cli/sbx_mcp_load.yaml @@ -16,6 +16,14 @@ options: - name: sandbox usage: Target sandbox name (required) 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" diff --git a/data/sbx_cli/sbx_mcp_ls.yaml b/data/sbx_cli/sbx_mcp_ls.yaml index 323182f9536c..44cf78e6d18c 100644 --- a/data/sbx_cli/sbx_mcp_ls.yaml +++ b/data/sbx_cli/sbx_mcp_ls.yaml @@ -15,11 +15,26 @@ options: shorthand: h default_value: "false" usage: help for ls + - name: json + default_value: "false" + usage: Output in JSON format 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" usage: Enable debug logging -example: ' sbx mcp ls' +example: |4- + sbx mcp ls + + # Machine-readable output for scripting + sbx mcp ls --json see_also: - sbx mcp - Manage MCP servers diff --git a/data/sbx_cli/sbx_mcp_rm.yaml b/data/sbx_cli/sbx_mcp_rm.yaml index 86c1845233e3..f223faaaa7cb 100644 --- a/data/sbx_cli/sbx_mcp_rm.yaml +++ b/data/sbx_cli/sbx_mcp_rm.yaml @@ -7,6 +7,14 @@ options: default_value: "false" usage: help for rm 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" diff --git a/data/sbx_cli/sbx_move.yaml b/data/sbx_cli/sbx_move.yaml new file mode 100644 index 000000000000..51a361160678 --- /dev/null +++ b/data/sbx_cli/sbx_move.yaml @@ -0,0 +1,65 @@ +name: sbx move +synopsis: Move a sandbox between local and cloud +description: |- + Move a sandbox between the local host and Docker's hosted Sandboxes service. + + Move captures the source sandbox's filesystem as a template, transports the + OCI image across the local↔cloud boundary, and launches a new sandbox from + it on the destination. + + Semantics (per the May 2026 design): + - Source disposition: neither direction deletes the source. A local→cloud + move stops the local source. A cloud→local move also tries to stop a + source with a structured agent (best-effort: an ineligible account, or a + request/wait failure, leaves it running instead); once stopped it keeps + its ID and full state, so 'sbx --cloud run ' brings it back, and + 'sbx --cloud rm ' deletes it when you no longer need it. A source + with no reported agent is left running instead. + - The destination sandbox gets a new ID; pass --name to control its name. + - Filesystem-only: in-memory state, running processes, and open sockets + are NOT carried across. + - Network policy: a local→cloud move carries the source's egress + allow/deny rules onto the cloud sandbox. A cloud→local move starts the + local sandbox with the host's default network posture (the cloud source's + policy is not currently read back). Secrets never follow. +usage: sbx move SANDBOX [flags] +options: + - name: force + shorthand: f + default_value: "false" + usage: | + Skip the confirmation prompt when moving a sandbox whose workspace files won't travel to the cloud + - name: help + shorthand: h + default_value: "false" + usage: help for move + - name: name + usage: | + Name for the destination sandbox (default: derived from the source ID) + - name: to + usage: | + Destination of the move: 'local' (cloud→local) or 'cloud' (local→cloud) +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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +example: |4- + # Move a cloud sandbox down to the local host + sbx move sbx_abc123 --to local + + # Move a local sandbox up to the cloud + sbx move my-sandbox --to cloud + + # Give the destination sandbox a custom name + sbx move sbx_abc123 --to local --name big-refactor +see_also: + - sbx - Manage AI coding agent sandboxes. diff --git a/data/sbx_cli/sbx_policy.yaml b/data/sbx_cli/sbx_policy.yaml index 31425e8bec5e..49d04af75b49 100644 --- a/data/sbx_cli/sbx_policy.yaml +++ b/data/sbx_cli/sbx_policy.yaml @@ -13,6 +13,14 @@ options: default_value: "false" usage: help for policy 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" diff --git a/data/sbx_cli/sbx_policy_allow.yaml b/data/sbx_cli/sbx_policy_allow.yaml index bab387669886..c828e8e961c8 100644 --- a/data/sbx_cli/sbx_policy_allow.yaml +++ b/data/sbx_cli/sbx_policy_allow.yaml @@ -13,6 +13,14 @@ options: default_value: "false" usage: help for allow 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" diff --git a/data/sbx_cli/sbx_policy_allow_network.yaml b/data/sbx_cli/sbx_policy_allow_network.yaml index 1aa59f7010a4..3d703eed7e1c 100644 --- a/data/sbx_cli/sbx_policy_allow_network.yaml +++ b/data/sbx_cli/sbx_policy_allow_network.yaml @@ -19,6 +19,14 @@ options: usage: | Scope the rule to a specific sandbox (default: all sandboxes) 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" diff --git a/data/sbx_cli/sbx_policy_check.yaml b/data/sbx_cli/sbx_policy_check.yaml index a3b98ba2663e..a55b3e7c5e36 100644 --- a/data/sbx_cli/sbx_policy_check.yaml +++ b/data/sbx_cli/sbx_policy_check.yaml @@ -12,6 +12,14 @@ options: default_value: "false" usage: help for check 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" diff --git a/data/sbx_cli/sbx_policy_check_network.yaml b/data/sbx_cli/sbx_policy_check_network.yaml index 6fb09c0a0ccd..e8d63d768b53 100644 --- a/data/sbx_cli/sbx_policy_check_network.yaml +++ b/data/sbx_cli/sbx_policy_check_network.yaml @@ -21,6 +21,14 @@ options: default_value: "false" usage: Show the exact policy request fields 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" diff --git a/data/sbx_cli/sbx_policy_deny.yaml b/data/sbx_cli/sbx_policy_deny.yaml index 2211ef9680f1..5aeb5bcf8225 100644 --- a/data/sbx_cli/sbx_policy_deny.yaml +++ b/data/sbx_cli/sbx_policy_deny.yaml @@ -12,6 +12,14 @@ options: default_value: "false" usage: help for deny 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" diff --git a/data/sbx_cli/sbx_policy_deny_network.yaml b/data/sbx_cli/sbx_policy_deny_network.yaml index c0546f95d53c..37f66b74468d 100644 --- a/data/sbx_cli/sbx_policy_deny_network.yaml +++ b/data/sbx_cli/sbx_policy_deny_network.yaml @@ -18,6 +18,14 @@ options: usage: | Scope the rule to a specific sandbox (default: all sandboxes) 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" diff --git a/data/sbx_cli/sbx_policy_init.yaml b/data/sbx_cli/sbx_policy_init.yaml index a8ac9bdece17..08066478bf14 100644 --- a/data/sbx_cli/sbx_policy_init.yaml +++ b/data/sbx_cli/sbx_policy_init.yaml @@ -24,7 +24,17 @@ options: shorthand: h default_value: "false" usage: help for init + - name: sandbox + usage: Target a single cloud sandbox's policy (cloud only) 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" diff --git a/data/sbx_cli/sbx_policy_inspect.yaml b/data/sbx_cli/sbx_policy_inspect.yaml index 16999f6dabe3..8aa1cac97047 100644 --- a/data/sbx_cli/sbx_policy_inspect.yaml +++ b/data/sbx_cli/sbx_policy_inspect.yaml @@ -17,7 +17,18 @@ options: shorthand: h default_value: "false" usage: help for inspect + - name: json + default_value: "false" + usage: Output in JSON format 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" @@ -28,5 +39,8 @@ example: |4- # Inspect a rule by ID sbx policy inspect 2d3c1f0e-4a73-4e05-bc9d-f2f9a4b50d67 + + # Machine-readable output for scripting + sbx policy inspect "Developer access" --json see_also: - sbx policy - Manage sandbox policies diff --git a/data/sbx_cli/sbx_policy_log.yaml b/data/sbx_cli/sbx_policy_log.yaml index 39f398a94de8..8b1099fe8a02 100644 --- a/data/sbx_cli/sbx_policy_log.yaml +++ b/data/sbx_cli/sbx_policy_log.yaml @@ -27,6 +27,14 @@ options: usage: | Filter logs by type: "all", "network", or "filesystem" (filesystem logs are not supported yet; default "all") 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" diff --git a/data/sbx_cli/sbx_policy_ls.yaml b/data/sbx_cli/sbx_policy_ls.yaml index 6f5f4ed8639d..4538459110cf 100644 --- a/data/sbx_cli/sbx_policy_ls.yaml +++ b/data/sbx_cli/sbx_policy_ls.yaml @@ -40,6 +40,14 @@ options: default_value: "false" usage: Show detailed rule-level output with rule IDs and resources 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" diff --git a/data/sbx_cli/sbx_policy_reset.yaml b/data/sbx_cli/sbx_policy_reset.yaml index 5c6e9289392d..0ce35f1d79fa 100644 --- a/data/sbx_cli/sbx_policy_reset.yaml +++ b/data/sbx_cli/sbx_policy_reset.yaml @@ -20,6 +20,14 @@ options: default_value: "false" usage: help for reset 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" diff --git a/data/sbx_cli/sbx_policy_rm.yaml b/data/sbx_cli/sbx_policy_rm.yaml index 2c7578074d55..00d5f796135d 100644 --- a/data/sbx_cli/sbx_policy_rm.yaml +++ b/data/sbx_cli/sbx_policy_rm.yaml @@ -8,6 +8,14 @@ options: default_value: "false" usage: help for rm 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" diff --git a/data/sbx_cli/sbx_policy_rm_network.yaml b/data/sbx_cli/sbx_policy_rm_network.yaml index bdf02c7493de..6a9ef46d31f6 100644 --- a/data/sbx_cli/sbx_policy_rm_network.yaml +++ b/data/sbx_cli/sbx_policy_rm_network.yaml @@ -27,6 +27,14 @@ options: usage: | Scope the removal to a specific sandbox (default: global policy) 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" diff --git a/data/sbx_cli/sbx_ports.yaml b/data/sbx_cli/sbx_ports.yaml index 2bf7767e58e5..ce1c49c67a1f 100644 --- a/data/sbx_cli/sbx_ports.yaml +++ b/data/sbx_cli/sbx_ports.yaml @@ -3,7 +3,8 @@ synopsis: Manage sandbox port publishing description: |- Manage sandbox port publishing. - List, publish, or unpublish ports for a running sandbox. Without --publish or + List, publish, or unpublish sandbox ports. Publishing a local port starts a + stopped sandbox before creating the host binding. Without --publish or --unpublish flags, lists all published ports. Port spec format: [[HOST_IP:]HOST_PORT:]SANDBOX_PORT[/PROTOCOL] @@ -11,8 +12,21 @@ description: |- If HOST_IP is omitted, the port is bound on loopback, expanded based on PROTOCOL and the sandbox's address families: tcp/udp binds both 127.0.0.1 and ::1 (or only 127.0.0.1 if the sandbox is IPv4-only); tcp4/udp4 binds - only 127.0.0.1; tcp6/udp6 binds only ::1. PROTOCOL defaults to tcp. + only 127.0.0.1; tcp6/udp6 binds only ::1. Supported protocols: tcp, tcp4, tcp6, udp, udp4, udp6. + + When publishing without a PROTOCOL, tcp4 is used — so a sandbox service + listening only on IPv4 is reachable without a host client having to avoid + ::1 — or tcp6 when HOST_IP is an IPv6 address. Publish tcp explicitly to + bind both families. + + When unpublishing without a PROTOCOL, the mapping is removed whether it was + published with that same default or as dual-stack tcp. Name the protocol to + remove a tcp6 or udp mapping; anything left behind is reported. + + In cloud mode (--cloud), the sandbox may be given by ID (sbx_*) or name, and + only the sandbox port number is accepted. The cloud control plane assigns a + publicly reachable URL for each exposed port. usage: sbx ports SANDBOX [flags] options: - name: help @@ -25,12 +39,20 @@ options: - name: publish default_value: '[]' usage: | - Publish a port (can be repeated): [[HOST_IP:]HOST_PORT:]SANDBOX_PORT[/PROTOCOL] + Publish a port (can be repeated): [[HOST_IP:]HOST_PORT:]SANDBOX_PORT[/PROTOCOL] (local) or SANDBOX_PORT (cloud) - name: unpublish default_value: '[]' usage: | - Unpublish a port (can be repeated): [HOST_IP:]HOST_PORT:SANDBOX_PORT[/PROTOCOL] + Unpublish a port (can be repeated): [HOST_IP:]HOST_PORT:SANDBOX_PORT[/PROTOCOL] (local) or SANDBOX_PORT (cloud) 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" @@ -47,5 +69,11 @@ example: |4- # Unpublish a port sbx ports my-sandbox --unpublish 3000:8080 + + # Expose port 8080 on a cloud sandbox + sbx ports sbx_abc123 --cloud --publish 8080 + + # Remove an exposed port from a cloud sandbox + sbx ports sbx_abc123 --cloud --unpublish 8080 see_also: - sbx - Manage AI coding agent sandboxes. diff --git a/data/sbx_cli/sbx_prune.yaml b/data/sbx_cli/sbx_prune.yaml index 45576ed6db65..e9839ea1b304 100644 --- a/data/sbx_cli/sbx_prune.yaml +++ b/data/sbx_cli/sbx_prune.yaml @@ -13,12 +13,15 @@ description: |- within the last week). A sandbox whose stop time the daemon cannot report is left alone, since how long it has been stopped cannot be established. - Use --dry-run to list what would be removed without removing anything. + Use --dry-run to list what would be removed without removing anything, and + --json with it for machine-readable output. Pruning requires confirmation; use --force to skip the confirmation prompt (for non-interactive scripts) and to remove a sandbox that is in use (e.g. an open SSH connection). This action cannot be undone. + Secrets scoped to each successfully pruned sandbox are also deleted. + Local-only: cloud sandboxes expire via their TTL. usage: sbx prune [flags] options: @@ -39,7 +42,18 @@ options: shorthand: h default_value: "false" usage: help for prune + - name: json + default_value: "false" + usage: Output the --dry-run listing in JSON format 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" diff --git a/data/sbx_cli/sbx_reset.yaml b/data/sbx_cli/sbx_reset.yaml index 66eae81408f9..c64d9a86b371 100644 --- a/data/sbx_cli/sbx_reset.yaml +++ b/data/sbx_cli/sbx_reset.yaml @@ -38,6 +38,14 @@ options: default_value: "false" usage: Keep stored secrets 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" diff --git a/data/sbx_cli/sbx_rm.yaml b/data/sbx_cli/sbx_rm.yaml index 29e5ceb94125..694c4375a325 100644 --- a/data/sbx_cli/sbx_rm.yaml +++ b/data/sbx_cli/sbx_rm.yaml @@ -1,14 +1,20 @@ name: sbx rm synopsis: Remove one or more sandboxes description: |- - Remove one or more sandboxes and all associated resources. + Remove one or more sandboxes and all associated resources. Or — with --cloud — the cloud sandbox + ID (sbx_*) or name from "sbx --cloud ls". - Stops running sandboxes, removes their containers, cleans up any Git - worktrees, and deletes sandbox state. This action cannot be undone. + 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 + the sandbox in Docker Sandboxes Cloud. This action cannot be undone. Removal requires confirmation; use --force to skip confirmation prompts (for non-interactive scripts) and to delete a sandbox that is in use - (e.g. an open SSH connection). Use --all to remove every sandbox. + (e.g. an open SSH connection). Use --all to remove every sandbox. With --cloud, --all is + intentionally disabled as a safety gate — the blast radius covers every + sandbox the credential can see, which may include shared or production + workloads. Pass IDs explicitly in --cloud mode. usage: sbx rm [SANDBOX...] [flags] options: - name: all @@ -24,6 +30,14 @@ options: default_value: "false" usage: help for rm 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" diff --git a/data/sbx_cli/sbx_run.yaml b/data/sbx_cli/sbx_run.yaml index e80550ad9742..204ffc33535f 100644 --- a/data/sbx_cli/sbx_run.yaml +++ b/data/sbx_cli/sbx_run.yaml @@ -3,20 +3,44 @@ synopsis: Run an agent in a sandbox description: |- Run an agent in a sandbox, creating the sandbox if it does not already exist. - The first positional argument is the agent to run. 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. + The first positional argument identifies the agent to run. It 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; bare values + retain their agent or sandbox-name meaning. 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. Pass agent arguments after the "--" separator. Additional workspaces can be - provided as extra arguments. Append ":ro" to mount them read-only. + provided as extra arguments. Append ":ro" to mount them read-only; a read-only + argument may name a single file, which holds that one path out of reach inside a + workspace the sandbox can otherwise write. + + Omit the path to mount the current directory. Pass a path to mount a different + workspace. To create a sandbox without attaching, use "sbx create" instead, or pass --detached (-d) to print the sandbox ID and exit without opening an interactive session. - Available agents: claude, codex, copilot, cursor, docker-agent, droid, gemini, kiro, opencode, shell -usage: sbx run [flags] [AGENT] [PATH...] [-- AGENT_ARGS...] + With --cloud: the agent runs in the cloud sandbox image (started server-side). + Running an agent that has existing sandboxes (running or stopped) prompts you + to pick one to reuse or to create a new one. Pass --new to skip the prompt and + always create a fresh sandbox. --detached also skips the prompt and always + creates a new sandbox; a non-interactive run without --detached is refused. + Use --detached for non-interactive scripting (e.g. + sbx --cloud run -d claude && sbx --cloud exec ...). + Without --cpus/--memory a cloud sandbox defaults to 2 CPUs and 4 GiB. + Templates referenced via -t / --template must already exist in the cloud registry; + the CLI does not upload them automatically. See https://docs.docker.com/ai/sandboxes/ for the cloud sandbox model. + + Available agents: claude, codex, cursor, devin, docker-agent, gemini, opencode, shell +usage: sbx run [flags] [AGENT|SANDBOX_KIT] [PATH...] [-- AGENT_ARGS...] options: + - name: allow-network + default_value: '[]' + usage: | + Network pattern to allow for cloud sandbox egress (cloud only; can be specified multiple times) - name: clone default_value: "false" usage: | @@ -29,6 +53,9 @@ options: default_value: '[]' usage: | Add a per-sandbox network deny rule at creation time. Can be specified multiple times. The rule applies only to the new sandbox and can be listed or removed later with `sbx policy ls ` / `sbx policy rm network --sandbox --resource `. Safe under centralized governance because a local deny can only narrow, never widen, egress. + - name: detach-keys + usage: | + Override the detach gesture that leaves the agent running (Docker-style, e.g. "ctrl-\", "ctrl-x,ctrl-d"). Default: Ctrl-\. Use this when the default collides with an agent's keymap (cloud only). - name: env shorthand: e default_value: '[]' @@ -42,17 +69,40 @@ options: shorthand: h default_value: "false" usage: help for run + - name: image-ref + usage: | + OCI image reference for inline-mode cloud create (mutually exclusive with --template; requires --cpus and --memory) - name: kit default_value: '[]' experimental: true usage: | - Kit reference (directory, ZIP, or OCI). Can be specified multiple times + Additional kit reference (must be a mixin; directory, ZIP, git, or OCI). Can be specified multiple times + - name: kit-arg + default_value: '[]' + experimental: true + usage: | + Value for an argument the kit declares, as name=value for every kit or kit.name=value for one (can be repeated) + - name: kit-args-file + default_value: '[]' + experimental: true + usage: | + File of name=value kit arguments, one per line (can be repeated); --kit-arg overrides - name: memory shorthand: m usage: | Memory limit in binary units (e.g., 1024m, 8g). Default: 50% of host memory, max 32 GiB - name: name usage: 'Name for the sandbox (default: -)' + - name: new + default_value: "false" + usage: | + Always create a new cloud sandbox instead of prompting to reuse an existing one (cloud only) + - name: on-timeout + usage: | + What happens when --ttl lapses: 'delete' (default) tombstones the sandbox, or 'stop' stops it in place so it can be started again later (cloud only; 'stop' requires your account to be entitled to it). + - 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. - name: publish shorthand: p default_value: '[]' @@ -62,15 +112,42 @@ options: shorthand: t usage: | Container image to use for the sandbox (default: agent-specific image) + - name: ttl + default_value: 0s + usage: | + Cloud sandbox time-to-live before it times out (e.g. 30m, 2h; cloud only; default: server-side) + - name: volume + shorthand: v + default_value: '[]' + experimental: true + usage: | + Attach an existing persistent volume, NAME:MOUNTPATH (cloud only, experimental; repeatable) 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" usage: Enable debug logging example: |4- - # Create and run a sandbox with claude in current directory + # Create and run a sandbox with claude in the current directory sbx run claude + # Create and run from a local sandbox kit + sbx run ../path/to/my-agent/ + + # Create and run from an OCI sandbox kit + sbx run ghcr.io/foo/my-agent:latest + + # Add a mixin to a built-in agent + sbx run claude --kit ./my-mixin/ + # Create and run with additional workspaces (read-only) sbx run claude . /path/to/docs:ro @@ -82,5 +159,8 @@ example: |4- # Run a sandbox with agent arguments sbx run claude -- --continue + + # Create a cloud sandbox non-interactively and print its ID + sbx --cloud run --detached claude see_also: - sbx - Manage AI coding agent sandboxes. diff --git a/data/sbx_cli/sbx_secret.yaml b/data/sbx_cli/sbx_secret.yaml index 995fb119345b..acd541a17029 100644 --- a/data/sbx_cli/sbx_secret.yaml +++ b/data/sbx_cli/sbx_secret.yaml @@ -21,6 +21,14 @@ options: default_value: "false" usage: help for secret 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" diff --git a/data/sbx_cli/sbx_secret_import.yaml b/data/sbx_cli/sbx_secret_import.yaml index 10b8c397c77f..1a089073c042 100644 --- a/data/sbx_cli/sbx_secret_import.yaml +++ b/data/sbx_cli/sbx_secret_import.yaml @@ -21,7 +21,7 @@ description: |- Run `sbx secret rm ` first if you want to switch from OAuth to api-key auth. - Available services: anthropic, cursor, droid, github, google, groq, mistral, nebius, openai, openrouter, xai + Available services: anthropic, copilot, cursor, devin, droid, github, google, groq, mistral, nebius, openai, openrouter, xai usage: sbx secret import [SERVICE] [flags] options: - name: all @@ -39,6 +39,14 @@ options: default_value: "false" usage: help for import 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" diff --git a/data/sbx_cli/sbx_secret_ls.yaml b/data/sbx_cli/sbx_secret_ls.yaml index 318720d5dbe3..80ca68ad459a 100644 --- a/data/sbx_cli/sbx_secret_ls.yaml +++ b/data/sbx_cli/sbx_secret_ls.yaml @@ -15,11 +15,22 @@ options: shorthand: h default_value: "false" usage: help for ls + - name: json + default_value: "false" + usage: Output in JSON format - name: sandbox usage: Only list secrets for one sandbox - name: service usage: Filter by secret service name 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" @@ -36,5 +47,8 @@ example: |4- # Filter by service sbx secret ls --service github + + # Machine-readable output for scripting + sbx secret ls --json see_also: - sbx secret - Manage stored secrets diff --git a/data/sbx_cli/sbx_secret_rm.yaml b/data/sbx_cli/sbx_secret_rm.yaml index cac2f449b9aa..9202d8706a29 100644 --- a/data/sbx_cli/sbx_secret_rm.yaml +++ b/data/sbx_cli/sbx_secret_rm.yaml @@ -2,6 +2,9 @@ name: sbx secret rm synopsis: Remove a secret usage: sbx secret rm [SERVICE] [flags] options: + - name: all + default_value: "false" + usage: Remove every stored secret across all scopes - name: all-sandboxes default_value: "false" usage: | @@ -19,6 +22,14 @@ options: - name: sandbox usage: 'Scope the removal to one sandbox (default: global)' 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" @@ -45,5 +56,9 @@ example: |4- # Remove only the global (all-sandboxes) registry credential sbx secret rm --all-sandboxes --registry ghcr.io -f + + # Remove every stored secret across every scope (service secrets, custom + # secrets, OAuth tokens, and registry credentials) + sbx secret rm --all see_also: - sbx secret - Manage stored secrets diff --git a/data/sbx_cli/sbx_secret_set-custom.yaml b/data/sbx_cli/sbx_secret_set-custom.yaml index 3668ca5380cc..0890c0f4e036 100644 --- a/data/sbx_cli/sbx_secret_set-custom.yaml +++ b/data/sbx_cli/sbx_secret_set-custom.yaml @@ -54,6 +54,14 @@ options: - name: value usage: 'Secret value (less secure: visible in shell history)' 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" diff --git a/data/sbx_cli/sbx_secret_set.yaml b/data/sbx_cli/sbx_secret_set.yaml index cdad8cfabb51..bef655440855 100644 --- a/data/sbx_cli/sbx_secret_set.yaml +++ b/data/sbx_cli/sbx_secret_set.yaml @@ -5,7 +5,7 @@ description: |- ### Service secrets - Available services: anthropic, cursor, droid, github, google, groq, mistral, nebius, openai, openrouter, xai + Available services: anthropic, copilot, cursor, devin, droid, github, google, groq, mistral, nebius, openai, openrouter, xai Service secrets apply globally by default. Use --sandbox to scope a secret to one sandbox. When SERVICE is omitted, an interactive prompt selects it. @@ -52,7 +52,8 @@ options: usage: Skip checking the --ref or --command source when storing it - name: oauth default_value: "false" - usage: Start OAuth flow and store OAuth tokens (openai/global only) + usage: | + Start OAuth flow and store OAuth tokens (openai/global only) With --cloud: openai or anthropic, stored only in the cloud (never the local secrets-engine) - name: password-stdin default_value: "false" usage: | @@ -78,6 +79,14 @@ options: usage: | Registry username (use with --registry; omit for token-only auth) 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" diff --git a/data/sbx_cli/sbx_setup.yaml b/data/sbx_cli/sbx_setup.yaml index d7175ca0a2cd..6eeb7624faac 100644 --- a/data/sbx_cli/sbx_setup.yaml +++ b/data/sbx_cli/sbx_setup.yaml @@ -7,7 +7,9 @@ description: |- Agent secrets are detected from the built-in agent kit specs and the env vars set on this host, and accepted secrets are imported into the global - secrets store (the same store as "sbx secret set"). + secrets store (the same store as "sbx secret set"). When SSH_AUTH_SOCK is set, + setup can enable SSH-agent forwarding and either use each client's current + socket or persist a fixed socket path. usage: sbx setup [COMMAND] options: - name: help @@ -15,6 +17,14 @@ options: default_value: "false" usage: help for setup 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" diff --git a/data/sbx_cli/sbx_setup_ssh.yaml b/data/sbx_cli/sbx_setup_ssh.yaml index 0e37c56bd5ce..bdc5ac4121d8 100644 --- a/data/sbx_cli/sbx_setup_ssh.yaml +++ b/data/sbx_cli/sbx_setup_ssh.yaml @@ -19,6 +19,14 @@ options: default_value: "false" usage: help for ssh 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" diff --git a/data/sbx_cli/sbx_setup_ssh_remove.yaml b/data/sbx_cli/sbx_setup_ssh_remove.yaml index 6633cc7804c2..c282fac8e727 100644 --- a/data/sbx_cli/sbx_setup_ssh_remove.yaml +++ b/data/sbx_cli/sbx_setup_ssh_remove.yaml @@ -8,6 +8,14 @@ options: default_value: "false" usage: help for remove 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" diff --git a/data/sbx_cli/sbx_skills.yaml b/data/sbx_cli/sbx_skills.yaml index 5a56085f1674..6d531abe338f 100644 --- a/data/sbx_cli/sbx_skills.yaml +++ b/data/sbx_cli/sbx_skills.yaml @@ -1,14 +1,11 @@ name: sbx skills -synopsis: Manage skills shared across sandboxes +synopsis: Manage skills available in sandboxes experimental: true description: |- - Manage the persistent agent skills store shared across sandboxes. + Manage skills available to agents in Docker Sandboxes. - Copy skills from supported agent directories on the host into the store with: - sbx skills import - - Sandboxes with skills sharing enabled mount the store read-write. Use - --no-share-skills when creating a sandbox to opt out. + Skills are shared across sandboxes by default. Use --no-share-skills when + creating a sandbox to opt out. usage: sbx skills COMMAND options: - name: help @@ -16,11 +13,22 @@ options: default_value: "false" usage: help for skills 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" usage: Enable debug logging see_also: - sbx - Manage AI coding agent sandboxes. + - sbx skills add - Add skills from a Git repository - sbx skills import - Import skills from supported agent directories - - sbx skills ls - List imported skills + - sbx skills ls - List installed skills + - sbx skills rm - Remove installed skills + - sbx skills update - Update skills added from repositories diff --git a/data/sbx_cli/sbx_skills_add.yaml b/data/sbx_cli/sbx_skills_add.yaml new file mode 100644 index 000000000000..6d58ba52647d --- /dev/null +++ b/data/sbx_cli/sbx_skills_add.yaml @@ -0,0 +1,48 @@ +name: sbx skills add +synopsis: Add skills from a Git repository +experimental: true +description: |- + Install skills from a Git repository for use in Docker Sandboxes. The + repository must contain one or more valid SKILL.md files. + + All discovered skills are installed when --skill is omitted. Use --skill one + or more times, or pass a comma-separated list, to install only named skills. + Replacing an installed skill requires confirmation; use --force to skip + prompts. + + The repository can be specified as a Git URL or as GitHub owner/repository + shorthand. Skills installed with this command can later be refreshed with + 'sbx skills update'. +usage: sbx skills add [flags] +options: + - name: force + shorthand: f + default_value: "false" + usage: Overwrite existing skills without prompting + - name: help + shorthand: h + default_value: "false" + usage: help for add + - name: skill + shorthand: s + default_value: '[]' + usage: Add only the named skill (repeatable or comma-separated) +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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +example: |4- + sbx skills add https://github.com/anthropics/skills --skill frontend-design + sbx skills add anthropics/skills --skill frontend-design --skill pdf + sbx skills add https://github.com/anthropics/skills --force +see_also: + - sbx skills - (Experimental) Manage skills available in sandboxes diff --git a/data/sbx_cli/sbx_skills_import.yaml b/data/sbx_cli/sbx_skills_import.yaml index 25e727b4aea7..75f9942e4f61 100644 --- a/data/sbx_cli/sbx_skills_import.yaml +++ b/data/sbx_cli/sbx_skills_import.yaml @@ -2,29 +2,29 @@ name: sbx skills import synopsis: Import skills from supported agent directories experimental: true description: |- - Copy skills from supported agent directories on the host into the - persistent store shared by sandboxes. + Import skills already installed for supported coding agents on this + machine. - Sources are scanned in this order (alphabetical; first wins on conflict): + The following directories are checked in order: ~/.agents/skills ~/.claude/skills + ~/.config/opencode/skills ~/.copilot/skills ~/.cursor/skills ~/.factory/skills - If two sources contain a skill with the same name, the later source is skipped - with a warning — the first source's version is kept. + When the same skill appears in more than one directory, the first copy is used + and the others are skipped with a warning. - Each imported skill folder replaces any store folder of the same name (the - existing folder is backed up first, then the new copy is installed) so stale - files from a previous version cannot linger. You will be prompted before any - existing skill is overwritten; use --force to skip all prompts. + 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. - The store lives under the sandbox state directory and is cleared by - 'sbx reset'. Supported by Claude, Codex, Copilot, Cursor, and Droid agents. + Imported skills are available to Claude, Codex, Copilot, Cursor, Droid, and + OpenCode. usage: sbx skills import [flags] options: - name: dry-run @@ -40,9 +40,17 @@ options: default_value: "false" usage: help for import 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" usage: Enable debug logging see_also: - - sbx skills - (Experimental) Manage skills shared across sandboxes + - sbx skills - (Experimental) Manage skills available in sandboxes diff --git a/data/sbx_cli/sbx_skills_ls.yaml b/data/sbx_cli/sbx_skills_ls.yaml index a8c3c92ce99e..1a7380ba9c75 100644 --- a/data/sbx_cli/sbx_skills_ls.yaml +++ b/data/sbx_cli/sbx_skills_ls.yaml @@ -1,18 +1,28 @@ name: sbx skills ls -synopsis: List imported skills +synopsis: List installed skills experimental: true -description: | - List the skill folders in the central agent-skills store shared by sandboxes. +description: List skills available to agents in Docker Sandboxes. usage: sbx skills ls [flags] options: - name: help shorthand: h default_value: "false" usage: help for ls + - name: json + default_value: "false" + usage: Output in JSON format 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" usage: Enable debug logging see_also: - - sbx skills - (Experimental) Manage skills shared across sandboxes + - sbx skills - (Experimental) Manage skills available in sandboxes diff --git a/data/sbx_cli/sbx_skills_rm.yaml b/data/sbx_cli/sbx_skills_rm.yaml new file mode 100644 index 000000000000..c600456c9604 --- /dev/null +++ b/data/sbx_cli/sbx_skills_rm.yaml @@ -0,0 +1,33 @@ +name: sbx skills rm +synopsis: Remove installed skills +experimental: true +description: |- + Remove one or more installed skills from Docker Sandboxes. + + Running agents may be reading installed skills. Removal cannot be undone and + requires confirmation; use --force to skip confirmation in scripts. +usage: sbx skills rm ... [flags] +options: + - name: force + shorthand: f + default_value: "false" + usage: Skip confirmation prompts + - name: help + shorthand: h + default_value: "false" + usage: help for rm +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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +see_also: + - sbx skills - (Experimental) Manage skills available in sandboxes diff --git a/data/sbx_cli/sbx_skills_update.yaml b/data/sbx_cli/sbx_skills_update.yaml new file mode 100644 index 000000000000..6d5b66a0e2b6 --- /dev/null +++ b/data/sbx_cli/sbx_skills_update.yaml @@ -0,0 +1,30 @@ +name: sbx skills update +synopsis: Update skills added from repositories +experimental: true +description: |- + Download the latest versions of skills installed with 'sbx skills add'. + + With no names, every skill added from a repository is updated. Specify one or + more names to update only those skills. Skills installed with 'sbx skills + import' must be added from a repository before they can be updated. +usage: sbx skills update [skill]... [flags] +options: + - name: help + shorthand: h + default_value: "false" + usage: help for update +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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +see_also: + - sbx skills - (Experimental) Manage skills available in sandboxes diff --git a/data/sbx_cli/sbx_stop.yaml b/data/sbx_cli/sbx_stop.yaml index 97b32c1b61de..a83325061d31 100644 --- a/data/sbx_cli/sbx_stop.yaml +++ b/data/sbx_cli/sbx_stop.yaml @@ -1,9 +1,21 @@ name: sbx stop synopsis: Stop one or more sandboxes without removing them description: |- - Stop one or more running sandboxes without removing them. + Stop one or more running sandboxes without removing them. Or — with --cloud — the cloud sandbox + ID (sbx_*) or name from "sbx --cloud ls". Stopped sandboxes retain their state and can be restarted with "sbx run". + + With --cloud, stop suspends each sandbox in place: its full state (memory + + disk) is preserved, the host is released, and the sandbox keeps its ID. + Restart it — same ID — by running its agent again ("sbx --cloud run ") + and picking the stopped sandbox from the prompt. A detached run (--detached) + creates a new sandbox instead of restarting a stopped one. + + Stop does not create a template and does not delete the sandbox. To capture + a durable, shareable template from a running sandbox instead, use + "sbx --cloud template save SANDBOX TAG" (which leaves the sandbox + running). usage: sbx stop SANDBOX [SANDBOX...] options: - name: help @@ -11,6 +23,14 @@ options: default_value: "false" usage: help for stop 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" diff --git a/data/sbx_cli/sbx_template.yaml b/data/sbx_cli/sbx_template.yaml index ca5a6cea2e23..45022f1e8792 100644 --- a/data/sbx_cli/sbx_template.yaml +++ b/data/sbx_cli/sbx_template.yaml @@ -5,6 +5,9 @@ description: |- Templates are saved snapshots of sandboxes that can be reused to create new sandboxes with: sbx run -t TAG AGENT [WORKSPACE] + + Cloud mode (--cloud) snapshots and loads typically produce multi-GB artifacts + and take several minutes. See https://docs.docker.com/ai/sandboxes/ for details. usage: sbx template COMMAND options: - name: help @@ -12,12 +15,21 @@ options: default_value: "false" usage: help for template 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" usage: Enable debug logging see_also: - sbx - Manage AI coding agent sandboxes. + - sbx template inspect - Show full metadata for a single template - sbx template load - Load an image from a tar file into the sandbox runtime - sbx template ls - List template images - sbx template rm - Remove a template image diff --git a/data/sbx_cli/sbx_template_inspect.yaml b/data/sbx_cli/sbx_template_inspect.yaml new file mode 100644 index 000000000000..5e81c4111946 --- /dev/null +++ b/data/sbx_cli/sbx_template_inspect.yaml @@ -0,0 +1,39 @@ +name: sbx template inspect +synopsis: Show full metadata for a single template +description: |- + Show full metadata for a single template. + + NAME|ID can be either a template name (resolved to its ID via the server's + ?name= filter) or a template ID (tmpl_*). + + Cloud-only in v1: requires --cloud. +usage: sbx template inspect NAME|ID [flags] +options: + - name: help + shorthand: h + default_value: "false" + usage: help for inspect + - name: json + default_value: "false" + usage: Output in JSON format +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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +example: |4- + sbx template inspect my-template --cloud + sbx template inspect tmpl_abc123 --cloud + + # Output in JSON format + sbx template inspect my-template --cloud --json +see_also: + - sbx template - Manage sandbox templates diff --git a/data/sbx_cli/sbx_template_load.yaml b/data/sbx_cli/sbx_template_load.yaml index 0aeef27e2cb6..9e5778581aeb 100644 --- a/data/sbx_cli/sbx_template_load.yaml +++ b/data/sbx_cli/sbx_template_load.yaml @@ -5,13 +5,47 @@ description: |- The loaded image can be used as a template for new sandboxes. Tar files are typically created with: sbx template save SANDBOX TAG --output FILE -usage: sbx template load FILE [flags] + + 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 (the server enforces power-of-two + CPUs and memory:cpu ratio constraints). --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. + + 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. +usage: sbx template load FILE [NAME] [flags] options: + - name: capture-mode + default_value: disk + usage: | + What gets captured for this template. "disk" (default) captures only the filesystem — cold-boot from a standard OCI image, faster load. "all" captures memory + disk + microVM checkpoint — sub-second TTI on resume, slower load. Only effective with --cloud. + - name: cpus + default_value: "0" + usage: Number of CPUs (1, 2, 4, 8, or 16; required with --cloud) + - name: description + usage: Optional template description (--cloud only) - name: help shorthand: h default_value: "false" usage: help for load + - name: memory-mib + default_value: "0" + usage: | + Memory in MiB (512–32768, must satisfy 2:1/1:1/1:2 ratio with --cpus; required with --cloud) 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" @@ -23,5 +57,14 @@ example: |4- # Use the loaded image as a template sbx run -t myimage:v1.0 claude + + # Cloud: upload a tar as a cloud-managed template (disk capture, faster load) + sbx template load /tmp/myimage.tar my-template --cloud --cpus 2 --memory-mib 2048 + + # Cloud: capture memory + disk + microVM checkpoint for sub-second resume + sbx template load /tmp/myimage.tar my-template --cloud --cpus 2 --memory-mib 2048 --capture-mode all + + # Cloud: with a description + sbx template load /tmp/myimage.tar my-template --cloud --cpus 2 --memory-mib 2048 --description "Nightly baseline" see_also: - sbx template - Manage sandbox templates diff --git a/data/sbx_cli/sbx_template_ls.yaml b/data/sbx_cli/sbx_template_ls.yaml index 90b28d7740aa..96c5514d8eb2 100644 --- a/data/sbx_cli/sbx_template_ls.yaml +++ b/data/sbx_cli/sbx_template_ls.yaml @@ -12,6 +12,14 @@ options: default_value: "false" usage: Output in JSON format 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" diff --git a/data/sbx_cli/sbx_template_rm.yaml b/data/sbx_cli/sbx_template_rm.yaml index f0dd4b670cbe..de08c5345b51 100644 --- a/data/sbx_cli/sbx_template_rm.yaml +++ b/data/sbx_cli/sbx_template_rm.yaml @@ -6,13 +6,25 @@ description: |- The image can be identified by tag (e.g. "myimage:v1.0") or by image ID (full or prefix, e.g. "abc123"). Use "sbx template ls" to see available images and their IDs. -usage: sbx template rm TAG|ID [flags] + + With --cloud: + The template can be identified by its tmpl_* ID or by its human name + (resolved via the server-side ?name= filter). Use "sbx template ls --cloud". +usage: sbx template rm TAG|ID|NAME [flags] options: - name: help shorthand: h default_value: "false" usage: help for rm 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" @@ -23,5 +35,11 @@ example: |4- # Remove by image ID (prefix) sbx template rm abc123 + + # Cloud: remove by name + sbx template rm my-template --cloud + + # Cloud: remove by tmpl_* id + sbx template rm tmpl_abc123 --cloud see_also: - sbx template - Manage sandbox templates diff --git a/data/sbx_cli/sbx_template_save.yaml b/data/sbx_cli/sbx_template_save.yaml index cc569b3ea58c..ee46385b1620 100644 --- a/data/sbx_cli/sbx_template_save.yaml +++ b/data/sbx_cli/sbx_template_save.yaml @@ -8,8 +8,28 @@ description: |- 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 + + With --cloud: + Snapshot a running cloud sandbox into a cloud-managed template. The + snapshot can take several minutes for kit-sized images; the command + polls for completion. Use --description to attach a free-form description + to the saved template. + + --capture-mode controls what gets captured: "disk" (default) 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. + + Cloud snapshots typically produce multi-GB templates and take several + minutes to complete. See https://docs.docker.com/ai/sandboxes/ for the snapshot/load model. usage: sbx template save SANDBOX TAG [flags] options: + - name: capture-mode + default_value: disk + usage: | + What gets captured for this template. "disk" (default) captures only the filesystem — cold-boot from a standard OCI image, faster load. "all" captures memory + disk + microVM checkpoint — sub-second TTI on resume, slower load. Only effective with --cloud. + - name: description + shorthand: d + usage: Description for the template (cloud only) - name: help shorthand: h default_value: "false" @@ -18,6 +38,14 @@ options: shorthand: o usage: Also export the image to a tar file 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" @@ -28,5 +56,14 @@ example: |4- # Also export to a shareable tar file sbx template save my-sandbox myimage:v1.0 --output /tmp/myimage.tar + + # Cloud: snapshot a running cloud sandbox into a cloud-managed template + sbx template save sbx_abc123 my-snap --cloud + + # Cloud: attach a description to the saved template + sbx template save sbx_abc123 my-snap --cloud --description "nightly build" + + # Cloud: capture memory + disk + microVM checkpoint for sub-second resume + sbx template save sbx_abc123 my-snap --cloud --capture-mode all see_also: - sbx template - Manage sandbox templates diff --git a/data/sbx_cli/sbx_ttl.yaml b/data/sbx_cli/sbx_ttl.yaml new file mode 100644 index 000000000000..8b8a32474d23 --- /dev/null +++ b/data/sbx_cli/sbx_ttl.yaml @@ -0,0 +1,40 @@ +name: sbx ttl +synopsis: Inspect or extend a cloud sandbox's TTL +description: |- + Inspect or extend a cloud sandbox's TTL. + + With one argument, prints the current expiration and the maximum + remaining time before the sandbox's hard 24h-from-creation ceiling. + + With two arguments — a duration prefixed with '+' followed by a sandbox + ID or name — extends the TTL by that amount, subject to the server-enforced + ceiling. The server cannot shorten an expiration, so DURATION must be + positive. + + SANDBOX may be given by ID (sbx_*) or name, as shown by "sbx --cloud ls". + + Cloud-only: local sandboxes are not TTL-managed. +usage: sbx ttl [+DURATION] SANDBOX +options: + - name: help + shorthand: h + default_value: "false" + usage: help for ttl + - name: json + default_value: "false" + usage: Output as JSON +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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +see_also: + - sbx - Manage AI coding agent sandboxes. diff --git a/data/sbx_cli/sbx_tui.yaml b/data/sbx_cli/sbx_tui.yaml index 982f8f16d24b..ab37e9082a3a 100644 --- a/data/sbx_cli/sbx_tui.yaml +++ b/data/sbx_cli/sbx_tui.yaml @@ -7,6 +7,14 @@ options: default_value: "false" usage: help for tui 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" diff --git a/data/sbx_cli/sbx_version.yaml b/data/sbx_cli/sbx_version.yaml index cdab8a1f1695..543bb2eeb10a 100644 --- a/data/sbx_cli/sbx_version.yaml +++ b/data/sbx_cli/sbx_version.yaml @@ -6,7 +6,19 @@ options: shorthand: h default_value: "false" usage: help for version + - name: json + default_value: "false" + usage: | + Output in JSON format, including the server version and, when the backend reports them, the runtime component versions 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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. - name: debug shorthand: D default_value: "false" diff --git a/data/sbx_cli/sbx_volume.yaml b/data/sbx_cli/sbx_volume.yaml new file mode 100644 index 000000000000..a2e0f74f4c9f --- /dev/null +++ b/data/sbx_cli/sbx_volume.yaml @@ -0,0 +1,36 @@ +name: sbx volume +synopsis: Manage persistent volumes (cloud-only) +description: |- + Manage persistent volumes for cloud sandboxes. + + Volumes provide persistent storage that survives across sandbox runs. + Data is saved as a snapshot when a sandbox exits, not continuously + synced. If multiple sandboxes mount the same volume concurrently, the + last sandbox to exit wins — its snapshot overwrites the others. + + Volumes are a cloud-only feature; every subcommand requires --cloud. +usage: sbx volume COMMAND +options: + - name: help + shorthand: h + default_value: "false" + usage: help for volume +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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +see_also: + - sbx - Manage AI coding agent sandboxes. + - sbx volume create - Create a new persistent volume + - sbx volume inspect - Show details for a volume + - sbx volume ls - List persistent volumes + - sbx volume rm - Delete a persistent volume diff --git a/data/sbx_cli/sbx_volume_create.yaml b/data/sbx_cli/sbx_volume_create.yaml new file mode 100644 index 000000000000..9e9ba768d652 --- /dev/null +++ b/data/sbx_cli/sbx_volume_create.yaml @@ -0,0 +1,32 @@ +name: sbx volume create +synopsis: Create a new persistent volume +description: |- + Create a new persistent volume. + + The volume name must be unique per account; an attempt to create a volume + with a name already in use is rejected. +usage: sbx volume create NAME [flags] +options: + - name: help + shorthand: h + default_value: "false" + usage: help for create + - name: json + default_value: "false" + usage: Output in JSON format +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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +example: ' sbx --cloud volume create my-cache' +see_also: + - sbx volume - Manage persistent volumes (cloud-only) diff --git a/data/sbx_cli/sbx_volume_inspect.yaml b/data/sbx_cli/sbx_volume_inspect.yaml new file mode 100644 index 000000000000..e1d4929cdeef --- /dev/null +++ b/data/sbx_cli/sbx_volume_inspect.yaml @@ -0,0 +1,24 @@ +name: sbx volume inspect +synopsis: Show details for a volume +usage: sbx volume inspect NAME [flags] +options: + - name: help + shorthand: h + default_value: "false" + usage: help for inspect +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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +example: ' sbx --cloud volume inspect my-cache' +see_also: + - sbx volume - Manage persistent volumes (cloud-only) diff --git a/data/sbx_cli/sbx_volume_ls.yaml b/data/sbx_cli/sbx_volume_ls.yaml new file mode 100644 index 000000000000..fc87f8abf883 --- /dev/null +++ b/data/sbx_cli/sbx_volume_ls.yaml @@ -0,0 +1,27 @@ +name: sbx volume ls +synopsis: List persistent volumes +usage: sbx volume ls [flags] +options: + - name: help + shorthand: h + default_value: "false" + usage: help for ls + - name: json + default_value: "false" + usage: Output in JSON format +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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +example: ' sbx --cloud volume ls' +see_also: + - sbx volume - Manage persistent volumes (cloud-only) diff --git a/data/sbx_cli/sbx_volume_rm.yaml b/data/sbx_cli/sbx_volume_rm.yaml new file mode 100644 index 000000000000..2f11d7f9961c --- /dev/null +++ b/data/sbx_cli/sbx_volume_rm.yaml @@ -0,0 +1,33 @@ +name: sbx volume rm +synopsis: Delete a persistent volume +description: |- + Delete a persistent volume by name. + + Volumes attached to active sandboxes cannot be deleted; detach them + first by stopping or deleting the sandbox(es) that mount the volume. +usage: sbx volume rm NAME [flags] +options: + - name: force + shorthand: f + default_value: "false" + usage: Skip confirmation prompt + - name: help + shorthand: h + default_value: "false" + usage: help for rm +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: cloud-api-url + default_value: https://api.sandboxes-cloud.docker.com/v1 + usage: | + Cloud Sandboxes API URL; only used with --cloud. Defaults to prod (https://api.sandboxes-cloud.docker.com/v1). Set DOCKER_CLOUD_API_URL or pass this flag to override. + - name: debug + shorthand: D + default_value: "false" + usage: Enable debug logging +example: ' sbx --cloud volume rm my-cache' +see_also: + - sbx volume - Manage persistent volumes (cloud-only)