Docker Sandboxes Kits

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)

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.