跳到主内容
智客 ZICQ

技能库 智客分类:运维与云 docker-sandboxes-env

Docker Sandboxes Env

在为多克沙盒('sbx env create/run/plan/exec/rm')编写,规划,或运行一个声明式的'sbxenv.yaml'文件时使用这一技能,即使用户只是说他们想要"在沙盒配置中检查","为沙盒制作可复制","在代理开始前运行一个设置脚本",或者"为共享沙盒环境进行定义论证". 涵盖sbxenv.yaml schema(schemaVersion,代理,工具包,工作空间/额外工作空间,参数,env,秘密,注册,绑定,mcp,端口,沙盒可选),主机"生命周期:"命令(初始化/后创造/前再移动)及其审批计划模式,多文件合并("-f"风格的深度合并和用户级".sbxenv.yaml"基础层),以及文件写入保护("sandbox可选.writableEnvFiles").

1024 安装量

官方网址:skills.sh

技能介绍

先看中文介绍;官方 description 原文单独保留,不改写 SKILL.md。

做什么

在为多克沙盒('sbx env create/run/plan/exec/rm')编写,规划,或运行一个声明式的'sbxenv.yaml'文件时使用这一技能,即使用户只是说他们想要"在沙盒配置中检查","为沙盒制作可复制","在代理开始前运行一个设置脚本",或者"为共享沙盒环境进行定义论证". 涵盖sbxenv.yaml schema(schemaVersion,代理,工具包,工作空间/额外工作空间,参数,env,秘密,注册,绑定,mcp,端口,沙盒可选),主机"生命周期:"命令(初始化/后创造/前再移动)及其审批计划模式,多文件合并("-f"风格的深度合并和用户级".sbxenv.yaml"基础层),以及文件写入保护("sandbox可选.writableEnvFiles").

何时用

这个技能

代理如何加载

按 Agent Skills 渐进披露:启动时只加载 name 与 description(约 100 token);任务匹配后才读入整份 SKILL.md 正文;scripts/、references/、assets/ 仅在需要时再读。 本文件正文结构:Docker Sandboxes: Declarative sbxenv.yaml Environments、Overview、When to use this skill、Do not use this skill when、Core guidance、File resolution and required fields。

文件分析

文件分析:除 SKILL.md 外,正文引用了 scripts/seed-fixtures.sh、scripts/archive-state.sh、references/env-schema-fields.md、references/sources.md、assets/sbxenv.yaml,属于带资源的技能包,这些文件按需再读。

官方 description(原文)

Use this skill when authoring, planning, or running a declarative `sbxenv.yaml` file for Docker Sandboxes (`sbx env create/run/plan/exec/rm`), even if the user just says they want to "check in a sandbox config", "make onboarding reproducible for a sandbox", "run a setup script before the agent starts", or "define arguments for a shared sandbox environment". Covers the sbxenv.yaml schema (schemaVersion, agent, kits, workspace/additionalWorkspaces, args, env, secrets, registries, bindings, mcp, ports, sandboxOptions), host `lifecycle:` commands (initialize/postCreate/preRemove) and their approval-plan model, multi-file merge (`-f`-style deep merge and the user-level `.sbxenv.yaml` base layer), and file-write-protection (`sandboxOptions.writableEnvFiles`).

Docker Sandboxes: Declarative sbxenv.yaml EnvironmentsOverviewWhen to use this skillDo not use this skill whenCore guidanceFile resolution and required fieldsNaming, workspace, and the `.sbxenv.yaml` user base layer`args:` — parameterizing a shared file`lifecycle:` — host commands and the approval planThe environment plan: what it is and is notSecrets, registries, and bindings scoped to the environment`kits:`, `additionalWorkspaces:`, `mcp:`, `ports:`, and `sandboxOptions:`

兼容:Requires standalone sbx with sbx env support and sbxenv.yaml schemaVersion "1", not the legacy docker sandbox wrapper. Verified against docker/sandboxes df5c96ba60484fa2c375469dbac912c205da6c37; installed-help version and provenance are in references/sources.md. docker_help does not cover standalone sbx. · 许可:Apache-2.0

来源分类:skills.sh agent-skill

SKILL.md 与 Agent 调用

官方规范 ↗
name
docker-sandboxes-env
description
Use this skill when authoring, planning, or running a declarative `sbxenv.yaml` file for Docker Sandboxes (`sbx env create/run/plan/exec/rm`), even if the user just says they want to "check in a sandbox config", "make onboarding reproducible for a sandbox", "run a setup script before the agent starts", or "define arguments for a shared sandbox environment". Covers the sbxenv.yaml schema (schemaVersion, agent, kits, workspace/additionalWorkspaces, args, env, secrets, registries, bindings, mcp, ports, sandboxOptions), host `lifecycle:` commands (initialize/postCreate/preRemove) and their approval-plan model, multi-file merge (`-f`-style deep merge and the user-level `.sbxenv.yaml` base layer), and file-write-protection (`sandboxOptions.writableEnvFiles`).
compatibility
Requires standalone sbx with sbx env support and sbxenv.yaml schemaVersion "1", not the legacy docker sandbox wrapper. Verified against docker/sandboxes df5c96ba60484fa2c375469dbac912c205da6c37; installed-help version and provenance are in references/sources.md. docker_help does not cover standalone sbx.
许可
Apache-2.0
  1. 发现技能客户端向 Agent 提供名称与描述目录。
  2. 匹配与调用用户指定或任务匹配后,载入 SKILL.md 指令。
  3. 按需加载按步骤读取参考文档、使用脚本与素材。
指令中引用的文件 · 5
  • scripts/seed-fixtures.sh
  • scripts/archive-state.sh
  • references/env-schema-fields.md
  • references/sources.md
  • assets/sbxenv.yaml

以下路径提取自原文;文件是否齐全请以来源仓库中的完整目录为准。

具体调用语法与可用工具以目标 Agent 客户端为准。 查看调用机制说明 ↗

安装这个技能

Skills CLI ↗

先选择目标 Agent 和安装范围,保留技能包的附属文件,安装后检查客户端能否发现该技能。

该技能引用了附属文件,请从来源获取完整目录;仅复制 SKILL.md 可能缺少依赖。

交给 Agent 安装

复制安装指令给支持 Agent Skills 的代理,确认其中的目标目录与客户端匹配。

把 Agent Skill「docker-sandboxes-env」安装到我的项目:SKILL.md 原文与官方 description 见 https://zicq.com/zh/skills/skl-2f67e0932ad7eb28-%E5%A4%9A%E5%85%8B%E6%B2%99%E7%9B%92%E4%BF%A1%E5%B0%81.html
请存为 .cursor/skills/docker-sandboxes-env/SKILL.md 或 .claude/skills/docker-sandboxes-env/SKILL.md,frontmatter 的 name 与 description 保持原样,不要改写。
该技能还带 scripts/、references/、assets/ 等文件,请从 https://github.com/docker/skills 取完整目录,不要只建一个 SKILL.md。

GitHub 完整包 ↗

终端安装 · Skills CLI

需要 Node.js 与 npx。先查看仓库技能列表,确认实际名称。

npx skills add 'https://github.com/docker/skills' --list

npx skills add 'https://github.com/docker/skills' --skill 'docker-sandboxes-env'

CLI 会交互选择目标 Agent,默认安装到项目;用户级安装使用 -g。先通过查看命令核对仓库内容,再用 npx skills list 检查已安装技能。

阅读排版
--- name: docker-sandboxes-env description: Use this skill when authoring, planning, or running a declarative `sbxenv.yaml` file for Docker Sandboxes (`sbx env create/run/plan/exec/rm`), even if the user just says they want to "check in a sandbox config", "make onboarding reproducible for a sandbox", "run a setup script before the agent starts", or "define arguments for a shared sandbox environment". Covers the sbxenv.yaml schema (schemaVersion, agent, kits, workspace/additionalWorkspaces, args, env, secrets, registries, bindings, mcp, ports, sandboxOptions), host `lifecycle:` commands (initialize/postCreate/preRemove) and their approval-plan model, multi-file merge (`-f`-style deep merge and the user-level `.sbxenv.yaml` base layer), and file-write-protection (`sandboxOptions.writableEnvFiles`). license: Apache-2.0 compatibility: Requires standalone sbx with sbx env support and sbxenv.yaml schemaVersion "1", not the legacy docker sandbox wrapper. Verified against docker/sandboxes df5c96ba60484fa2c375469dbac912c205da6c37; installed-help version and provenance are in references/sources.md. docker_help does not cover standalone sbx. --- # Docker Sandboxes: Declarative sbxenv.yaml Environments ## Overview `sbxenv.yaml` (schemaVersion `"1"`, EXPERIMENTAL) declaratively describes one sandbox environment — agent, mixin kits, workspace mounts, environment variables, secrets/registries/bindings to provision, MCP servers, ports, and host-side lifecycle commands — so `sbx env create|run|plan|exec|rm` can stand it up and tear it down reproducibly instead of a long flag invocation. This skill owns that file format end to end. It delegates the sandbox lifecycle semantics it wraps, the credential/network model it provisions into, and the kit schema its `kits:` entries reference, to their own skills. ## When to use this skill Activate this skill when: - The user wants a checked-in, reproducible definition of a sandbox environment instead of a long `sbx create`/`sbx run` command line. - The user wants host-side setup/teardown commands (cloning a repo, seeding fixtures, archiving state) tied to a sandbox's create/attach/remove lifecycle. - The user wants to parameterize a shared environment file with named arguments (`args:` + `--env-arg`). - The user is debugging why `sbx env create`/`run` is asking for approval, or why a file, kit, or secret it declares was skipped or flagged. ## Do not use this skill when Do not use this skill when: - The task is the underlying `sbx create`/`run`/`rm` flag-based workflow with no `sbxenv.yaml` file involved — use `docker-sandboxes-lifecycle`. - The task is choosing network policy or storing a secret/registry credential independent of any environment file — use `docker-sandboxes-network-credentials` (this skill's `secrets:`/ `registries:`/`bindings:` blocks provision into that same store, but do not redefine its rules here). - The task is authoring the kit `spec.yaml` a `kits:` entry points at — use `docker-sandboxes-kits`. ## Core guidance ### File resolution and required fields - The file `sbx env` reads from a directory is exactly `sbxenv.yaml` — no other name, and a directory-named `.sbxenv.yaml` at the project level is **not** read as a project's own file (only the home-directory base layer uses that hidden name; see below). - Every environment file requires `schemaVersion: "1"` and `agent:` (a built-in agent name or the manifest name of an agent kit supplied via `kits:`). Everything else is optional. `agent: shell` needs no credentials and is the simplest way to validate a file's mechanics. - `sbx env create|run|plan|exec|rm` accept one or more `PATH` arguments. Each `PATH` is either a directory (resolved to `/sbxenv.yaml`) or the file itself. Passing more than one deep-merges them in declaration order — **`docker compose -f`-style semantics**: later files override earlier ones, mappings merge key-by-key, sequences concatenate. ```bash sbx env create sbxenv.yaml override.yaml ``` ### Naming, workspace, and the `.sbxenv.yaml` user base layer - Unless the file sets `name:` or `--name` overrides it, the sandbox is named after the mounted directory (or the project directory when nothing is mounted) — so an environment that mounts nothing is still the same sandbox every time it is applied. **Two different environment files in the same directory derive the same sandbox name and collide** unless each sets its own `name:` (or you pass a distinct `--name` per invocation) — always give each environment its own explicit `name:` when more than one may exist in the same directory. - `workspace:` names the read/write mount, exactly like `sbx create`'s omitted-path behavior: **omitting `workspace:` mounts nothing** at all. A relative `workspace:` path resolves against the **directory of the file that declares it** — `workspace: .` mounts the directory the file sits in. `${{ env.projectDir }}` names the project directory (the one holding the first `PATH`, or cwd when none is named); `${{ env.fileDir }}` names the declaring file's own directory. Nothing else is expanded — a bare `$` is literal text, so a value written for the container (`PATH: $PATH:/opt/bin`) reaches it unchanged. ```yaml workspace: . # mounts the directory this file sits in # workspace: ${{ env.projectDir }} # mounts the project directory explicitly ``` - Relative kit sources follow the same file-directory anchoring rule as `workspace:` (see `docker-sandboxes-kits` for kit reference syntax). - **Files within a mounted workspace get default read-only masking, and that protection is complete only when the file sits directly at the mount's own root.** A read-only bind at the mount point cannot be renamed by the sandbox — there is nothing above it inside the mount to rename. But an environment file in a **subdirectory** of a read-write mount is protected only at its current path: the sandbox can rename the containing directory (which it can write to) and then recreate the original path itself, landing a sandbox-controlled file back where the read-only bind no longer applies. `sbx env plan` calls this gap out explicitly for a file that is not at a mount's root. Do not claim renaming the containing directory creates no gap — for anything but the mount root, it does. - With **no `PATH`** given, an `.sbxenv.yaml` in the **home directory** is merged underneath as a base layer for defaults shared across projects; naming any `PATH` skips this layer entirely. The base layer may not set `name:` (which identifies one project) and its `workspace:` must be rooted at `${{ env.projectDir }}` — any other value would mount one fixed directory under every project that merges it. ### `args:` — parameterizing a shared file - Declare named inputs under `args:`, each with a `default` (making it optional, `default: ""` counts as a real default) or `required: true` (mutually exclusive), plus optional `description`, `enum`, or `pattern`. - Reference one as `${{ env.args.NAME }}` anywhere a value appears in the file, and supply it with `--env-arg NAME=VALUE` (repeatable) or `--env-args-file PATH`. ### `lifecycle:` — host commands and the approval plan - `lifecycle:` declares shell commands that run **on the host, outside the sandbox, with your own privileges** — not inside the container. Three phases, run in this order per invocation: - **`initialize`** — runs on **every** `create` **and** `run`, including one that only attaches to an existing sandbox. It is the one phase that can produce what the environment needs to exist (a cloned workspace, a generated file), so **it must be idempotent** — it reruns on every reattach. - **`postCreate`** — runs once, after the sandbox exists, before an interactive attach takes the terminal. - **`preRemove`** — runs before `sbx env rm` deletes the sandbox, while `sbx env exec` can still reach it. **A failing `preRemove` is only a warning** — the failure itself does not block removal. After the hook, removal rechecks the approved destroy plan and sandbox identity. A new credential or changed binding not covered by that approval, or a replacement sandbox under the same name, stops removal before deletion. Review the new destroy plan before retrying. - `sbx env exec` **runs no lifecycle commands at all, and requires the sandbox to already exist** — it does not create one. Run `sbx env create`/`sbx env run` first. ```yaml 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 ``` - Every command runs through the shell from the **project directory** by default (override per-command with `workdir:`; bound its runtime with `timeout:`). - **A file that declares any lifecycle command is asked about on every invocation that reaches it, whether or not this particular invocation changed anything** — approving a command also trusts whatever it invokes, including a script whose contents can change after the answer, so the question is repeated rather than remembered by default. The one exception: `sbx settings set env.rememberHostCommands true` makes it ask again only when the commands actually change. **Never treat an untrusted file's or an untrusted kit's lifecycle commands as pre-approved**, and never enable `rememberHostCommands` for a file whose commands you have not reviewed. An environment that declares **no** host commands at all, and whose config is otherwise unchanged from what was last approved, applies silently with no prompt. Use `--skip-host-commands` to run none of the declared commands for one invocation. ### The environment plan: what it is and is not - `sbx env plan [PATH...]` prints everything applying the file would set up — host commands, credentials/bindings, MCP registrations, directories, published ports, the sandbox itself, and its variables — compared against what was last applied/approved. **It changes nothing.** - `sbx env create`/`sbx env run` show the same plan and require approval before doing any work (`--auto-approve`/`-y` skips the prompt for non-interactive use — **never default to `-y` for a file or kit you have not reviewed**). A secret's literal `value:` is the one field shown both in the plan and recorded to state as a `sha256:` digest rather than in the clear; a `ref:`/`command:` secret shows where the credential comes from, not its resolved value. ### Secrets, registries, and bindings scoped to the environment - `secrets:` and `registries:` provision into the **same credential store** `sbx secret set` uses, at this environment's **sandbox scope**, so `sbx env rm` can remove exactly what it created. Each entry uses the same `value`/`ref`/`command` shape as `sbx secret set` (exactly one of the three) — see `docker-sandboxes-network-credentials` for what those mean at runtime and why a literal secret value should not otherwise appear in a checked-in file. - `bindings:` are per-service credential bindings merged into the user's **global** `credentials.yaml`; unlike `secrets:`/`registries:`, they are **left in place by default** by `sbx env rm` (they are user-wide and may be shared with other sandboxes/environments) — pass `--prune-bindings` to also remove them. - **Never write a literal secret value directly into a checked-in `sbxenv.yaml`.** Use `ref:` (1Password/AWS Secrets Manager) or `command:` so the value never lives in the file at all; if a literal `value:` is used transiently, both the plan and state show only its digest, but the original environment file still contains the plaintext secret. See the labeled `secrets:` fragment below for the shape — it is intentionally not part of the minimal asset, which needs no credentials at all to validate. ```yaml # OPTIONAL fragment — add only if this environment actually needs a # credential; the minimal asset omits this entirely. secrets: anthropic: ref: op://Private/Anthropic/api-key # never a literal `value:` in a checked-in file refresh: 55m ``` ### `kits:`, `additionalWorkspaces:`, `mcp:`, `ports:`, and `sandboxOptions:` - `kits:` composes mixin kits (and, exactly once, an agent kit whose name matches `agent:`) onto the base agent; a relative source anchors to the **declaring file's own directory**, the same rule as `workspace:`. - `additionalWorkspaces:` mounts extra directories beyond the primary `workspace:` (a file cannot declare one without the other) — the `sbxenv.yaml` equivalent of `sbx run`'s extra positional workspace arguments with `:ro`. - `mcp.servers:` registers MCP servers on the host and adds them to the sandbox's fixed (static) MCP set at create time; registrations are host-global and **left in place** by `sbx env rm`. - `ports:` pins explicit host-port bindings for container ports the sandbox exposes — the equivalent of `sbx ports --publish` — and is torn down automatically when `sbx env rm` deletes the sandbox. - `sandboxOptions:` (beyond `writableEnvFiles`, below) maps onto the remaining `sbx create` flags: `template`, `memory`, `cpus`, `pullPolicy`, `profile`, `skills`. See `references/env-schema-fields.md` for the exact field shapes, required keys, and a YAML example for each of the five blocks above. ### `sandboxOptions.writableEnvFiles` — a deliberate, explicit downgrade - By default, **every environment file mounted inside the workspace is read-only at its own path**, even though the rest of the mount is writable. This stops an agent editing the very file that decides what host lifecycle commands and secret-resolving commands run on your machine on the next invocation. - Set `sandboxOptions.writableEnvFiles: true` only where an agent is deliberately meant to edit its own environment file. This is a real security downgrade — the plan then reports the file as writable — so treat it the same as any other explicit trust decision, not a default. - **The protection is complete only at a mount's own root.** A file placed directly at the root of a read-write mount cannot be reached even by renaming, because the sandbox cannot rename the mount point itself. A file in a subdirectory of that mount is a different case: it is read-only at its current path, but the sandbox can rename the directory holding it (which it can write to) and recreate a file at the original path, ending up with a sandbox-controlled file there. `sbx env plan` flags this gap for a file that is not directly at a mount's root — read the plan's output rather than assuming renaming is always harmless. ## Related skills - For the `sbx create`/`run`/`rm` flag-based workflow this file wraps, use `docker-sandboxes-lifecycle`. - For what `secrets:`/`registries:`/`bindings:` mean at runtime, and for configuring network policy independent of any environment file, use `docker-sandboxes-network-credentials`. - For the schema of the kit `spec.yaml` a `kits:` entry (or `agent:` pointing at an agent kit) references, use `docker-sandboxes-kits`. ## References - `references/sources.md` — provenance for every rule above (help captures, source paths, docs URLs). - `references/env-schema-fields.md` — exact field shapes and YAML examples for `kits:`, `additionalWorkspaces:`, `mcp:`, `ports:`, and `sandboxOptions:`. ## Assets - `assets/sbxenv.yaml` — a complete, minimal, safe example: a `shell` agent mounting the declaring file's own directory, one static env var, and no credentials at all — it validates and plans without any onboarding authentication. ## Checks - `checks/verification.md` — Verification runbook for sbxenv.yaml commands (unexecuted runbook; run manually with an isolated, uniquely-named `--app-name`, never with real secret values or untrusted lifecycle commands auto-approved).

相关技能

运维与云

Docker Essentials

用于容器管理,图像操作,调试的基本道克命令和工作流程.

运维与云

Find Skills

从开放的代理技能生态系统中发现并安装技能. 使用时:(1)用户问"我如何做X",X可能拥有现有技能,(2)用户说"为X找到技能"或"是否为X有技能",(3)用户问"你能否做X",X是专门能力,(4)用户想扩展代理能力,(5)用户想搜索工具,模板,或工作流程,(6)用户提到他们希望…

运维与云

Microsoft Foundry

构建,部署,评价,优化,微调,管理微软创始代理,模型,资源最终结束. 用法:铸造、azd ai代理、azd 提供/部署、托管代理脚手架/开发/运行/部署/拖放、即时代理创建、创建代理、更新代理、添加代理工具、援引代理、代理.yaml、评估代理、批量活化、连续活化、持续监测、代理C…

运维与云

Azure Deploy

执行已有.azure/部署计划.md和基础设施文件的ALREADY-PREPARED应用程序的Azure部署。 当用户向 CREATE 请求新应用程序时, 请不要使用此技能 。 这种技能运行了 azd上行, azd 部署, trarraform 应用, 和 az 部署命令带有内置…