docker-sandboxes-kits

Docker Sandboxes：Kit（spec.yaml）

概要

Kit は、spec.yaml と任意の files/ ツリーを含むディレクトリ（または ZIP／OCI／git アーティファクト）です。sbx は、sbx create／sbx run --kit／sbx env の実行時、または sbx kit add の実行時に、Kit を実行中または作成直前のサンドボックスに組み込みます。このスキルでは、kit-spec v2 の作成、検証、配布（spec.yaml 自体の文法に関するすべて）を扱います。Kit の宣言が実行時に何を意味するか（認証情報の注入、ネットワークの適用）は docker-sandboxes-network-credentials に委ね、Kit が組み込まれるサンドボックスについては docker-sandboxes-lifecycle に委ねます。

このスキルを使う場合

次の場合にこのスキルを有効にしてください。

• ユーザーが、kind: sandbox（完全なエージェント）または kind: mixin（拡張）の Kit 用に spec.yaml を作成、検証、またはパッケージ化したい場合。
• ユーザーが、既存の組み込みエージェントにツール、認証情報、ネットワーク許可、またはファイルを追加する Mixin を作成したい場合。
• ユーザーが、Kit を OCI レジストリに公開（またはそこからプル）、署名、あるいは署名／プロベナンス証明を検証したい場合。
• ユーザーが、Kit の検証エラー、引数置換エラー、または sbx kit add の再作成要件をデバッグしている場合。

このスキルを使わない場合

次の場合はこのスキルを使わないでください。

• Kit 自体の内容とは関係なく、Kit が組み込まれるサンドボックスの作成／実行／削除を行うタスクの場合は、docker-sandboxes-lifecycle を使ってください。
• Kit が宣言する認証情報やネットワークルールが実行時に実際に何をするか（プロキシ注入、許可／拒否の優先順位、または現在のネットワーク／グローバルポリシーですでに許可されている内容）、あるいは Kit に関係のないシークレット／ポリシーに関するタスクの場合は、docker-sandboxes-network-credentials を使ってください。
• 独自の kits: ブロックを使って Kit を参照する sbxenv.yaml ファイル形式に関するタスクの場合は、そのファイルのスキーマには docker-sandboxes-env を使ってください（参照先の Kit 自体の内容は引き続きこのスキルが扱います）。

基本ガイダンス

kind: sandbox と kind: mixin — 適切な方を選ぶ

• 1 つのサンドボックスに組み込める kind: sandbox Kit は 1 つだけです（ベースイメージと起動設定を備えた完全なエージェント）。その上には、任意の数の kind: mixin Kit を重ねられます（ツール、認証情報、ネットワーク、ファイル）。Mixin では sandbox: ブロック、extends:、mixins: を宣言してはいけません。
• すべての Kit には、schemaVersion: "2"（現行のクリーンな文法で、レガシー互換シムはありません）、kind、および ^[a-z0-9]([a-z0-9-]{0,62}[a-z0-9])?$ に一致する name が必要です。デコードは厳密です。どこにあっても未認識のフィールドはハードエラーになります（例：permissions.netwrok: のようなタイプミス）。そのため、検証に通る Kit に見逃されたタイプミスはありません。

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

• Mixin でベースエージェントの認証情報を再定義しないでください。同じサービスに対して新しい apiKey.name または proxyManaged を宣言すると、組み込み時に失敗します。shell、docker-agent、opencode はすでに github を所有しています。追加のルーティング専用エントリ（apiKey.inject のみで、name／proxyManaged／oauth がなく、required: false）なら、代わりにベース認証情報を拡張できます。OAuth はサンドボックス Kit に設定し、Mixin には設定しないでください。詳しくは references/spec-v2-fields.md を参照してください。固定されたソース内の組み込み定義は sandboxlib/agentkits/agents/<agent>/spec.yaml で確認してください。sbx kit inspect が受け取るのはアーティファクト参照であり、組み込み名ではありません。単独での Mixin 検証では、組み込み時の検証は行われません。

sandbox: ブロック（サンドボックスキットのみ）

• kind: sandbox では必須です（extends: で、この設定をすでに提供する親を継承している場合を除く）。kind: mixin では使用できません。
• image: はビルド済みのベースイメージです。entrypoint: は固定されたプロセスのプレフィックスです（entrypoint[0] はバイナリです）。command: はモードごとの引数部分です。単独のリスト（default を設定し、interactive はそれにフォールバックします）、または {default: [...], interactive: [...]} のいずれかを指定します。 完全な最小キットには assets/spec-sandbox.yaml を使用してください。イメージやコマンドを新たに定義するのではなく、埋め込みのシェル定義を継承します。
• sandbox.build:（Dockerfile ビルド）は受け付けられますが、このリリースのランタイムではビルドされません。build: を設定するキットは image: も設定する必要があります。そうしないと、読み込み時に対処方法を示すエラーで拒否されます。
• 実際に動作するイメージを新たに定義せずに取得する最も簡単な方法は、（後述の）extends: です。 組み込みエージェント（例：extends: shell）を継承するサンドボックスキットは、そのエージェントの実際の sandbox.image を継承するため、sandbox: 全体を省略できます。存在しないイメージ参照を指定するのではなく、まさにこの方法を使った最小のアセット例を参照してください。

エグレス：permissions.network と「すべてのエグレスを宣言する」ルール

• permissions.network.allow／deny は、v1 のトップレベル network: に代わる v2 の設定先です。適用される形式には、ホスト完全一致、ホストとポートの完全一致、単一ラベルのワイルドカード（*.example.com）、複数ラベルのワイルドカード（**.example.com）、CIDR プレフィックスがあります。ランタイムのマッチャーはポート範囲をサポートしていません。ポートごとに個別の完全一致を使用してください。 ドメインルール内または CIDR ルール内では、拒否が優先されます。 ドメインによる確定判定は CIDR ルールより先に評価されます。許可されたホスト名は、解決先 IP に対する CIDR の拒否ルールではチェックされません。すでに許可されているホスト名をブロックするために、CIDR の拒否ルールだけに頼らないでください。

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

• permissions.network.allow は構成全体にわたって加算されます。また、サンドボックスのエグレスを許可するのはキット自身の許可リストだけではありません。 サンドボックスには、ベースエージェント自身の許可リストに加え、グローバルまたはサンドボックスごとのネットワークポリシー（キットとは独立した sbx policy）で許可された内容が適用されます。docker-sandboxes-network-credentials を参照してください。あるキットの allow リストからホストを削除しても、それだけでそのホストがブロックされたことにはなりません。グローバルポリシーのデフォルト（balanced は一般的なパッケージレジストリと AI サービスを許可し、allow-all はすべてを許可します）や、構成に含まれる別のキットによって、引き続き許可される場合があります。実際のサンドボックスで sbx policy check network --sandbox <name> <host> を実行して実効判定を確認せずに、ホストがブロックされていると断言しないでください。
• 再現性を確保するため、キットに必要なエグレスを明示的に宣言してください。認証情報の注入自体はネットワークアクセスを許可しません。許可エントリーを省略すると、到達可能性は既存のグローバル／サンドボックスごとのポリシーに依存します。必ずしもホストがブロックされるわけではありません。実効判定を確認してください。

credentials — キットが必要とするものを定義し、ユーザーによる保存方法は定義しない

• 各エントリーでは、service の識別情報と、解決済みの値をどこに注入するか（apiKey および／または oauth）を宣言します。認証情報をユーザーがどう取得・保存するかは宣言しません。それはユーザー自身のバインディングファイルで設定し、sbx secret set を通じて接続します（docker-sandboxes-network-credentials を参照）。
• apiKey.inject[] には domain と、明示的な header＋format（format には %s がちょうど1つ含まれる必要があります）、または scheme: の糖衣構文が必要です。scheme: bearer は Authorization: Bearer %s に展開されます（username は不要です）。scheme: basic には username が必要で、format とは併用できません。ベースエージェントを構成するどのエージェントも宣言していない service 名を選んでください（上記のサービス重複ルールを参照）。完全な断片については references/spec-v2-fields.md を参照してください。
• apiKey.proxyManaged: true を設定すると、コンテナー内の環境変数には未設定のままではなく、リテラルの proxy-managed センチネルが設定されます。実際の値は、許可リストにある注入ドメインでプロキシによってのみ置き換えられます。
• oauth には tokenEndpoint.host／.path と、passthrough: true でない場合は空でない sentinels.accessToken／.refreshToken が必要です。passthrough: true はセキュリティを低下させます。実際のトークンがセンチネルではなくコンテナーに届くため、キット自体の設計上必要な場合に限って使用し、その旨を description に記載してください。

setup — インストール（1回）と起動時（起動のたび）とファイル（起動時の書き込み）

ブロック	コマンドの形式	実行タイミング
setup.install[].command	文字列、sh -c 経由	エージェントの初回起動前に1回、同期的に実行されます。組み込みかどうかを問わず、すべてのキットで実行されます。
setup.startup[].command	list、exec 形式（シェルなし）	コンテナーの起動のたび（作成、停止／起動、デーモンの再起動、ホストの再起動）に実行されます。べき等でなければなりません。
setup.files[]	shell exec によるファイル書き込み	コンテナーの起動時に実行されます。path は絶対パスです。content で使用できるプレースホルダーは ${WORKDIR} のみです。

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 は files/ ディレクトリーツリー（以下）と同じ仕組みではありません。 setup.files のエントリーは、起動時に動的に書き込まれ、${WORKDIR} に置換されます。一方、files/home/ と files/workspace/ のディレクトリーツリーは、spec.yaml と一緒にパッケージ化され、コンテナー作成時にコピーされる静的ファイル群です。また、このツリーのうち、ワークスペースへのファイル配置後（たとえば --clone によるコンテナー内での git clone 後）に書き込まれるのは files/workspace/ 側だけであり、setup.files ではありません。混同しないでください。setup.files 自体には、「ワークスペースへのファイル配置後」に実行される保証はありません。
• 3つの setup: リストはすべて、構成されたキットの --kit 順に連結されます。
• デフォルトの実行ユーザー：インストールは、上書きされない限り root（user: "0"）として実行されます。起動時の処理／エントリーポイントは、上書きされない限りエージェントユーザー（uid 1000）として実行されます。/home/agent 以下に書き込む root のインストール手順では、後続のエージェントユーザーによる書き込みが失敗しないよう、必ず agent:agent に chown で所有権を戻してください。

volumes — 作成時のみ有効。すべてのボリュームにサイズの設定が必要です

• 各エントリーには絶対パスの path: が必要です。type: tmpfs（RAM ベース）を任意で指定できます（デフォルトのブロックベースのボリュームを使用する場合は省略するか、"" を指定します）。size:（バイトサイズの文字列）と mode:（8進数）も任意で指定できます。
• ボリュームの設定はサンドボックスの作成時にのみ適用されます。sbx kit add（実行時の注入）では、ボリュームの変更はすべてスキップされるため、ボリュームが必要なキットは作成時に含める必要があります。
• ブロックボリュームには必ず size: を設定してください。 サイズを指定しないボリュームにはデフォルトの 50 GiB が引き継がれ、ホストのディスク領域をすぐに実際に消費します（ext4 の inode テーブルをゼロ初期化するため）。実用上の下限は 512 MiB です。それ未満では mke2fs が inode 密度を切り替えるため、容量の節約効果はほとんどなくなります。

args — キットのパラメーター化

• トップレベルの args: の下で宣言します（v2 のみ。凍結された v1 の文法には args ブロックがありません）。各引数には default と required: true のいずれか一方を必ず指定し、description／enum／pattern は任意で指定できます。spec.yaml または files/ の任意の場所で ${{ kit.args.NAME }} を参照します。置換は spec のデコード前に行われます。すべての参照は必ず宣言されている必要があり、宣言されていない場合は読み込みに失敗します。これにより、キットの入力一覧として信頼できるブロックになります。文字列フィールドでプレースホルダーを使う場合は引用符で囲んでください（VERSION: "${{ kit.args.version }}"）。引用符で囲まないと、数値に見える値は数値としてデコードされ、文字列フィールドへのデコードに失敗します。
• --kit-arg name=value（すべてのキットに適用）または --kit-arg kitname.name=value（1 つのキットのみに適用）、あるいは --kit-args-file で値を指定します。この方法でシークレットを渡さないでください。--kit-arg の値はマスクされません。詳しくは docker-sandboxes-network-credentials を参照してください。

extends と mixins — ランタイム注入ではなく合成

• extends: で解決できるのは、この固定リリースに組み込まれたエージェント名（shell、claude など）のみです。リモートの git／OCI 親は、固定されていても解決に失敗します。より広範な形式仕様は、実装を保証するものではありません。最小アセットでは、サポート対象の extends: shell を使用しています。
• mixins: は警告付きで受け付けられますが、このランタイムでは適用されません。合成には --kit または sbx kit add を使用してください。形式に不変参照の要件があっても、未実装のリモート継承が機能するわけではありません。
• 再現性を確保するには、ダイジェストまたはコミットで固定した CLI キット参照を使用してください。--kit と sbx kit add は変更可能なタグ／ブランチも受け付けますが、CLI パーサーはこの推奨を強制しません。
• requires.agent（mixin 専用。kind: sandbox では拒否されます）は、mixin が対象とする単一のベースエージェント（Claude 固有の環境変数など）を固定します。形式ライブラリによって整形式かどうかがチェックされますが、エージェントとの適合性の不一致は合成を行う側で強制され、sbx kit validate だけでは検出されません。

検証、パッケージ化、配布

コマンド	目的
sbx kit validate REFERENCE [--kit-arg ...]	ローカルディレクトリ、ZIP、または git 参照を検証します。OCI は拒否されます。スキーマのみの整形式チェックです。ベースエージェントとの合成は行わないため、重複サービスの認証情報の競合は検出できず、実行時にドメインへ到達できるかも確認できません。
sbx kit inspect REFERENCE [--kit-arg ...] [--json]	デコード済みのアーティファクトを合成前に読み込み、出力します。--kit-arg による置換のプレビューも含まれます。
sbx kit pack DIRECTORY [-o OUTPUT.zip]	検証済みディレクトリを ZIP としてパッケージ化します。
sbx kit pull REFERENCE [-o OUTPUT]	合成せずに、OCI レジストリからキットの未加工レイヤーペイロードを取得します。
sbx kit push DIRECTORY REGISTRY/REPO:TAG [--sign]	パッケージ化してプッシュします。プッシュのたびに、デフォルトでは署名なしの SLSA 来歴アテステーションが付与されます。
sbx kit provenance REFERENCE [--certificate-identity ...]	push で付与されたアテステーションを出力します。一致するキー／IDで検証されない限り、UNSIGNED と表示されます。
sbx kit sign REFERENCE / sbx kit verify REFERENCE	Sigstore による署名／検証を行います（デフォルトではキーレス）。--identity-token より --identity-token-file を使用してください。
sbx kit add SANDBOX REFERENCE [--kit-arg ...]	既存のサンドボックスに実行時にmixin のみを注入します（再作成を考慮したラベルが必要です）。コンテナ作成後に変更できない設定（security.privileged、volumes:）は、この方法では反映できません。

各コマンドのフラグ一覧と実例については、references/kit-distribution-commands.md を参照してください。

関連するスキル

• キットを組み込むサンドボックス（sbx create／run --kit、 sbx kit add SANDBOX）については、docker-sandboxes-lifecycle を使用してください。
• キットの credentials:／permissions.network: 宣言が実行時に何を意味するかについては、 docker-sandboxes-network-credentials を使用してください。これには、プロキシの注入、許可と拒否の優先順位、グローバル／サンドボックス単位のポリシーを含めた場合にサンドボックスが実際に適用されるポリシー、ユーザーが実際のシークレット値を保存する場所が含まれます。
• このスキーマでキットを参照する kits:／agent: フィールドを持つ sbxenv.yaml ファイルについては、docker-sandboxes-env を使用してください。

参考資料

• references/sources.md — 上記の各ルールの出典情報（仕様パッケージ、SPEC-v2.md、ヘルプの記録、ドキュメントの URL）。
• references/spec-v2-fields.md — 完全な v2 フィールド一覧（共通フィールド、サンドボックス専用フィールド、ミックスイン専用フィールド、共有ブロック）。仕様全体を読み直さずに確認できます。
• references/kit-distribution-commands.md — sbx kit validate/inspect/pack/pull/push/provenance/sign/verify/add のすべてのフラグと、詳しい使用例。

アセット

• assets/spec-sandbox.yaml — 実在する最小限の kind: sandbox キットです。架空のイメージではなく、実際に動作するイメージを継承するために extends: shell を指定しています。
• assets/spec-mixin.yaml — 認証情報を一切持たない（エグレス専用の拡張）実在する最小限の kind: mixin キットです。すべての組み込みエージェントと問題なく組み合わせられます。

チェック

• checks/verification.md — スキーマ、構成、エグレス、キット追加のチェック（未実行の統合テスト手順書。分離された --app-name を使用し、レジストリへの公開や署名は行いません）。