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. ```yaml 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. ```yaml 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<string>**, 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`: ```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).