/docker-sandboxes-kits

name: docker-sandboxes-kits
description: >-
  Use this skill when authoring, validating, packaging, signing, or composing a Docker Sandboxes kit `spec.yaml` (`sbx kit add/inspect/pack/pull/push/sign/validate/verify`), even if the user just says they want to "add a tool to a sandbox agent", "build a reusable sandbox extension", "publish a kit to a registry", or "give a mixin its own credentials and network access". Covers the kit-spec v2 grammar (`kind: sandbox` vs `kind: mixin`, the `sandbox:` block, `permissions.network`, `ports`, `credentials` apiKey/oauth, `environment`, `setup` install/startup/files, `volumes`, `args`, `extends`, `mixins`, `requires.agent`), composition via `--kit`/`sbx kit add`, and distribution (pack/push/pull/sign/verify/provenance).
license: Apache-2.0
compatibility: Requires standalone sbx with sbx kit support and kit-spec schemaVersion "2", 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: Kits (spec.yaml)

Overview

A **kit** is a directory (or ZIP/OCI/git artifact) containing a `spec.yaml` plus an optional `files/` tree. `sbx` composes a kit into a running or about-to-be-created sandbox at `sbx create`/`sbx run --kit`/`sbx env` time or at `sbx kit add` time. This skill owns kit-spec v2 authoring, validation, and distribution — everything under `spec.yaml`'s own grammar — and defers what a kit's declarations *mean at runtime* (credential injection, network enforcement) to `docker-sandboxes-network-credentials`, and the sandboxes a kit is composed into to `docker-sandboxes-lifecycle`.

When to use this skill

Activate this skill when:

• The user wants to write, validate, or pack a `spec.yaml` for a `kind:

sandbox` (complete agent) or `kind: mixin` (extension) kit.

• The user wants a mixin to add a tool, credential, network allowance, or

files to an existing built-in agent.

• The user wants to publish a kit to (or pull one from) an OCI registry,

sign it, or verify a signature/provenance attestation.

• The user is debugging a kit-validation error, an argument-substitution

error, or `sbx kit add`'s recreate-aware requirement.

Do not use this skill when

Do not use this skill when:

• The task is creating/running/removing the sandbox a kit is composed into,

independent of the kit's own content — use `docker-sandboxes-lifecycle`.

• The task is what a credential or network rule a kit declares actually

does at runtime (proxy injection, allow/deny precedence, or what the CURRENT network/global policy already permits), or is about secrets/ policy that have nothing to do with a kit — use `docker-sandboxes-network-credentials`.

• The task is the `sbxenv.yaml` file format that references kits via its

own `kits:` block — use `docker-sandboxes-env` for that file's schema (this skill still owns what goes inside the referenced kit itself).

Core guidance

`kind: sandbox` vs `kind: mixin` — pick the right one

• Exactly one `kind: sandbox` kit composes into any sandbox (a complete

agent: base image + launch config). Any number of `kind: mixin` kits layer onto it (tools, credentials, network, files). A mixin **must not** declare a `sandbox:` block, `extends:`, or `mixins:`.

• Every kit needs `schemaVersion: "2"` (the current clean grammar — no

legacy shims), `kind`, and `name` matching `^[a-z0-9]([a-z0-9-]{0,62}[a-z0-9])?$`. **Decoding is strict**: any unrecognized field anywhere is a hard error (e.g. a typo like `permissions.netwrok:`), so a kit that validates has no silent typos.

  schemaVersion: "2"
  kind: mixin
  name: extra-egress

• Do not redefine a base agent's credential in a mixin: declaring a new

`apiKey.name` or `proxyManaged` for the same service fails composition. `shell`, `docker-agent`, and `opencode` already own `github`. An additive routing-only entry (`apiKey.inject`, no name/proxyManaged/oauth, and `required: false`) can extend the base credential instead. OAuth belongs on sandbox kits, never mixins. See `references/spec-v2-fields.md`. Inspect built-in definitions at `sandboxlib/agentkits/agents/<agent>/spec.yaml` in the pinned source; `sbx kit inspect` takes artifact references, not built-in names. Standalone mixin validation does not test composition.

The `sandbox:` block (sandbox kits only)

• **Required** for `kind: sandbox` (unless the kit `extends:` a parent that

already supplies it); **forbidden** for `kind: mixin`.

• `image:` is the pre-built base image. `entrypoint:` is the fixed process

prefix (`entrypoint[0]` is the binary); `command:` is the mode-specific argument tail — either a bare list (sets `default`, `interactive` falls back to it) or `{default: [...], interactive: [...]}`. For a complete minimal kit, use `assets/spec-sandbox.yaml`, which inherits the embedded shell definition rather than inventing an image or command.

• `sandbox.build:` (Dockerfile build) is **accepted but not built by the

runtime this release** — a kit that sets `build:` must still set `image:`, or it is rejected at load with an actionable error.

• **`extends:` (below) is the simplest way to get a real, working image

without inventing one.** A sandbox kit that extends a built-in agent (e.g. `extends: shell`) inherits that agent's real `sandbox.image` and may omit `sandbox:` entirely — see the minimal example asset, which does exactly this rather than naming a made-up image reference.

Egress: `permissions.network` — and the all-egress-declared rule

• `permissions.network.allow`/`deny` are the v2 home for what v1 spelled as

top-level `network:`. Enforced shapes include exact host, exact host+port, single-label wildcards (`*.example.com`), multi-label wildcards (`**.example.com`), and CIDR prefixes. Port ranges are not supported by the runtime matche