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 matcher; use separate exact ports. Deny wins within domain rules or within CIDR rules. A decisive domain decision is evaluated before CIDR rules: an allowed hostname is not checked against a CIDR deny for its resolved IP. Do not rely on a CIDR deny alone to block an already-allowed hostname.

  permissions:
    network:
      allow:
        - registry.npmjs.org
      deny:
        - telemetry.example.com
  

• permissions.network.allow is additive across a composition, and a kit's own allow list is not the only thing granting a sandbox egress. The sandbox already carries the base agent's own allow list, plus whatever the global or per-sandbox network policy (sbx policy, independently of any kit) permits — see docker-sandboxes-network- credentials. Removing a host from one kit's allow list does not by itself prove that host is blocked — the global policy defaults (balanced allows common package registries and AI services; allow-all allows everything) or another composed kit may still permit it. Never claim a host is blocked without checking the actual effective decision with sbx policy check network --sandbox <name> <host> on a real sandbox.
• Declare the egress a kit requires explicitly for reproducibility. Credential injection does not itself grant network access. Omitting an allow entry leaves reachability dependent on the existing global/per-sandbox policy; it does not necessarily block the host. Check the effective decision.

credentials — what the kit needs, never how the user stores it

• Each entry declares a service identity and where to inject the resolved value (apiKey and/or oauth); it never declares how the user obtains or stores the credential — that lives in the user's own bindings file, wired through sbx secret set (see docker-sandboxes-network-credentials).
• apiKey.inject[] needs a domain and either an explicit header+ format (format must contain exactly one %s) or the scheme: sugar: scheme: bearer expands to Authorization: Bearer %s (no username), scheme: basic requires username and is mutually exclusive with format. Pick a service name no composed base agent already declares (see the duplicate-service rule above) — see references/spec-v2-fields.md for a complete fragment.
• apiKey.proxyManaged: true sets the in-container env var to the literal proxy-managed sentinel rather than leaving it unset; the real value is substituted only by the proxy, on the allow-listed inject domains.
• oauth needs tokenEndpoint.host/.path and, unless passthrough: true, non-empty sentinels.accessToken/.refreshToken. passthrough: true is a security downgrade — the real token reaches the container instead of a sentinel — use it only when the kit's own design requires it and say so in description.

setup — install (once) vs. startup (every start) vs. files (startup-time writes)

Block	Command shape	Runs
setup.install[].command	string, via sh -c	Once, synchronously, before the agent first launches. Runs for every kit, built-in or not.
setup.startup[].command	list, exec-style (no shell)	On every container start (create, stop/start, daemon restart, host reboot) — must be idempotent.
setup.files[]	file write via shell exec	At container startup; path absolute; only ${WORKDIR} placeholder allowed in content.

Optional fragment for the shell kit in assets/spec-sandbox.yaml:

setup:
  startup:
    - command: ["sh", "-c", "mkdir -p ~/.my-kit"]
  files:
    - path: /home/agent/.my-kit/config.json
      content: '{"workdir": "${WORKDIR}"}'

• setup.files is not the same mechanism as the files/ directory tree (below). setup.files entries are dynamic, ${WORKDIR}- substituted writes performed at startup time; the files/home/ and files/workspace/ directory tree is a set of static files packed alongside spec.yaml and copied in at container-create time, and it is specifically the files/workspace/ half of that tree — not setup.files — that is written after the workspace is populated (e.g. after an in-container git clone under --clone). Do not conflate the two: setup.files has no "after workspace population" timing guarantee of its own.
• All three setup: lists concatenate in --kit order across composed kits.
• Default execution users: install as root (user: "0") unless overridden; startup/entrypoint as the agent user (uid 1000) unless overridden. Root install steps writing under /home/agent must chown it back to agent:agent, or later agent-user writes there fail.

volumes — creation-time only, every volume must set a size

• Each entry needs an absolute path:, optional type: tmpfs (RAM-backed; omit/"" for the default block-backed volume), optional size: (byte-size string) and mode: (octal).
• Volumes apply only at sandbox-create time — sbx kit add (runtime injection) skips volume changes entirely; a kit that needs one must be present at creation.
• Always set size: on a block volume. An unsized volume inherits a 50 GiB default and costs real host disk immediately (ext4 inode-table zeroing); 512 MiB is the practical floor — below it mke2fs switches inode density and the space savings mostly disappear.

args — parameterizing a kit

• Declare under top-level args: (v2 only — the frozen v1 grammar has no args block), each with exactly one of default/required: true, plus optional description/enum/pattern. Reference with ${{ kit.args.NAME }} anywhere in spec.yaml or files/; substitution happens before the spec is decoded. Every reference must be declared, or loading fails — that is what makes the block a trustworthy list of a kit's inputs. Quote a placeholder used in a string field (VERSION: "${{ kit.args.version }}"), or an unquoted numeric-looking value decodes as a number and fails to decode into a string field.
• Supply values with --kit-arg name=value (every kit) or --kit-arg kitname.name=value (one kit only), or --kit-args-file. Never pass a secret this way — --kit-arg values are not masked; see docker-sandboxes-network-credentials.

extends and mixins — composition, not runtime injection

• extends: resolves only built-in agent names at this pinned release (shell, claude, etc.). Remote git/OCI parents fail to resolve, even if pinned; the broader format specification is not an implementation guarantee. The minimal asset uses the supported extends: shell.
• mixins: is accepted with a warning but is not applied by this runtime. Use --kit or sbx kit add for composition. The format's immutable-ref requirements do not make unimplemented remote inheritance work.
• Prefer digest/commit-pinned CLI kit references for reproducibility. --kit and sbx kit add still accept mutable tags/branches; the CLI parser does not enforce this recommendation.
• requires.agent (mixin-only; rejected on kind: sandbox) pins the single base agent a mixin is designed for (e.g. Claude-specific env vars). It is well-formedness-checked by the spec library; the actual agent-affinity mismatch is enforced by the composition consumer, not by sbx kit validate alone.

Validating, packaging, and distributing

Command	Purpose
sbx kit validate REFERENCE [--kit-arg ...]	Local directory, ZIP, or git reference; OCI is rejected. Schema-only well-formedness check. Never composes against a base agent — cannot catch a duplicate-service credential collision or confirm any domain is reachable at runtime.
sbx kit inspect REFERENCE [--kit-arg ...] [--json]	Loads and prints the decoded artifact before composing it, including --kit-arg substitution preview.
sbx kit pack DIRECTORY [-o OUTPUT.zip]	Packages a validated directory as a ZIP.
sbx kit pull REFERENCE [-o OUTPUT]	Pulls a kit's raw layer payload from an OCI registry without composing it.
sbx kit push DIRECTORY REGISTRY/REPO:TAG [--sign]	Packages and pushes; every push attaches an unsigned-by-default SLSA provenance attestation.
sbx kit provenance REFERENCE [--certificate-identity ...]	Prints the attestation push attached; marked UNSIGNED unless verified against a matching key/identity.
sbx kit sign REFERENCE / sbx kit verify REFERENCE	Sigstore sign/verify (keyless by default); prefer --identity-token-file over --identity-token.
sbx kit add SANDBOX REFERENCE [--kit-arg ...]	Injects a mixin only into an existing sandbox at runtime (recreate-aware label required); container-immutable settings (security.privileged, volumes:) cannot take effect this way.

See references/kit-distribution-commands.md for full flag lists and worked examples of each command above.

Related skills

• For the sandboxes a kit is composed into (sbx create/run --kit, sbx kit add SANDBOX), use docker-sandboxes-lifecycle.
• For what a kit's credentials:/permissions.network: declarations mean at runtime — proxy injection, allow/deny precedence, the effective policy a sandbox actually has once global/per-sandbox policy is included, where the user stores the actual secret value — use docker-sandboxes-network-credentials.
• For the sbxenv.yaml file whose kits:/agent: fields reference a kit by this schema, use docker-sandboxes-env.

References

• references/sources.md — provenance for every rule above (spec package, SPEC-v2.md, help captures, docs URLs).
• references/spec-v2-fields.md — the complete v2 field table (common fields, sandbox-only fields, mixin-only fields, shared blocks) for lookup without re-reading the full spec.
• references/kit-distribution-commands.md — full flags and worked examples for sbx kit validate/inspect/pack/pull/push/provenance/sign/verify/add.

Assets

• assets/spec-sandbox.yaml — a genuine minimal kind: sandbox kit that extends: shell to inherit a real, working image rather than inventing one.
• assets/spec-mixin.yaml — a genuine minimal kind: mixin kit with no credentials at all (an egress-only extension), which composes cleanly with every built-in agent.

Checks

• checks/verification.md — Schema, composition, egress, and kit-add checks (unexecuted integration runbook; isolated --app-name, no registry publishing or signing).