crabbox

Crabbox

• 入念なリモートでの検証：［検証ポリシー](../openclaw-testing/SKILL.md#proof-policy)に従ってください。 条件を満たす利用可能なホストでの、範囲を限定したローカル検証を優先します。コストの高い作業や プラットフォーム固有の作業には、リモートのリソースを使用できます。キュー待ちの場合：自分が確保した リソースを解放し、PR CI または安全なローカル範囲を使用して、未確認の要件を報告してください。
• キューを待ったり、プロバイダーのフォールバックを連鎖させたりしないでください。

バックエンド：

• blacksmith-testbox：信頼できるメンテナーのソース。CI 用に準備済み。tbx_...。
• aws：Crabbox を直接ブローカー経由で利用します。新規の PR 向け。カスタムの同期／環境変数／キャプチャに対応。cbx_...。
• local-container：Docker のフォールバック。リモート検証ではありません。
• ssh：既存のオペレーターのホスト。macOS／Windows／WSL2。

プロバイダー、ID、実行 URL、コマンド、結果を必ず報告してください。Testbox を「AWS Crabbox」と呼んではいけません。

リポジトリの契約

• 例として示すコマンド、ブートストラップ、コンテナーイメージ、PR は、信頼できる利用者向け 手順から特定してください。コマンドを捏造したり、別の利用者のセットアップをコピーしたりしないでください。
• 利用者固有のセットアップは、ポータブルなスキルの外に置いてください。 プレースホルダーの定義を参照してください。

認可と分離

• タスクに必要な作成、再利用、クリーンアップ、一時状態、クリーンなチェックアウト： 事前承認済みです。既存のブランチ、チェックアウト、無関係な編集は保持してください。
• ソースの信頼性、認証情報、本番環境へのアクセス、予算、公開は、引き続き権限の境界です。状態を分離し、 タスクごとの承認がない限り、オペレーターの Gateway には触れないでください。

まずルートを選択

• 特定済みのプロバイダーを維持してください。信頼できるソースには Testbox、セマンティクス上必要な場合は直接 AWS、 信頼できないコードにはシークレットを使わない CI／AWS を使用してください。信頼できないラッパーや設定をローカルで実行したり、 信頼できないリースをハイドレートしたりしないでください。
• コマンドの準備ができたら確保し、自分が所有する ID を再利用して、終了後に停止してください。
• 実証済みの最小プロファイルを使用してください。より大きなプロファイルには、記録済みのメモリに関する根拠、または 総コストを測定したうえでの利点が必要です。一般的な失敗／遅延／タイムアウトは根拠になりません。補うために ワーカー数を増やしてはいけません。
• Testbox のサイズ指定：--blacksmith-workflow を使用し、--class／--type を直接指定しないでください。 プロファイルを変更する場合は、新しいリースが必要です。
• Blacksmith のランナーラベルが指定するのはティアであり、CPU や RAM が保証されるわけではありません。 Blacksmith は、サービスの利用状況に応じて、より小さなマシンを割り当てることがあります。 リソースに左右されるテストやベンチマークでは、割り当てられたマシン上で利用可能な CPU、アフィニティ／クォータ、 使用可能な RAM を測定してください。これらの測定値に基づいて、ワーカー数とワークロードの規模を決めてください。 要求したティアと観測したリソースは分けて記録してください。ラベルだけを根拠に、ハードウェアや性能を評価してはいけません。
• サイズ、実行時間、ハイドレーションの失敗、容量を理由にプロバイダーを上書きしてはいけません。明示的なユーザーの選択、 または必須のバックエンドセマンティクスがある場合に限ります。

事前確認

信頼できるリポジトリのルートで .crabbox.yaml を読み、インストール済みバイナリを特定し、 プロバイダー／コマンドを確認してください：

export CRABBOX="$(command -v crabbox)"
test -n "$CRABBOX"
"$CRABBOX" --version
"$CRABBOX" config show --json | jq '{provider, profile, target}'
"$CRABBOX" run --help

• 利用者が信頼しているラッパー／インストール手順を使用してください。
• 修復する場合：上流を確認し、タスク専用のクリーンなチェックアウトを使用してください。インストール済みの バイナリと無関係なソースは保持してください。名前だけを根拠に、隣接するチェックアウトを信頼してはいけません。

リースの有効期間

• TTL は作成時からカウントされ、ハイドレーション中も含まれます。アイドルタイムアウトは非アクティブな時間をカウントします。 より早い期限が適用されます。デフォルトはそれぞれ 30m、最大 4h です。オーナー／組織の上書き設定では 最大 24h まで許可できます。要求した期間ではなく、有効なポリシーとサニタイズ済みの上限通知を使用してください。 ポリシーの厳格化は稼働中のリースにも適用されます。
• --keep と stop: never は期限切れを防ぎません。保持する直接リースには、明示的に上限付きの TTL とアイドル時間を要求してください。通常のハートビート、セットアップ、同期、SSH、デスクトップでの利用では合計 TTL は延長されません。 run は、ポリシー、予算、プロバイダーの機能の範囲内で、コマンドの実行中に限り、上限付きの自動延長を要求します。
• ソースに依存する長時間の作業の前に、合計有効期間の残りを確認してください。許可されている場合は、上限付きの extend <id> --ttl <desired-total> --json を一度要求します。延長してもアイドル時間はリセットされません。拒否、予算超過、非対応、期限が進まない、非アクティブといった結果は、目に見える形でスキップまたは失敗として扱う必要があり、プロバイダーの切り替えや無限のリース連鎖で回避してはいけません。 Daytona など、作成時にプロバイダーが固定される場合は、割り当て時に十分な TTL を設定してください。
• 直接リースのゲスト更新に失敗すると、オンボックスの期限が古いまま、プロバイダー側の期限だけが延びている場合があります。同じローカル状態を維持し、調整のために同じ固定合計 TTL で再試行してください。失敗した延長を保護策として扱ってはいけません。
• 信頼できる directLeases: deny と directLeaseAllow の設定に従ってください。プロバイダーが拒否された場合は、設定済みのコーディネータールートが必要です。直接認証情報で迂回してはいけません。 Testbox にはネイティブのジョブ制限とアイドル制限が適用されます。 --ttl で委任されたワークフローの有効期間を延長することはできません。
• list はコーディネーターの稼働中リースを表示します。list --retained は、クリーンアップが未確認の保持済み終了リソースも追加で表示します。復旧には正確な ID を指定して inspect/stop を使用してください。 ブロッキング stop で完了が確認されるまで、保持に関する申告と復旧状態を維持してください。

信頼済み Testbox

解決されたプロバイダーが Testbox（または明示的に要求されたプロバイダー）の場合、コマンドはそのプロバイダーを維持します。 明示的に上書きする場合に限り、--provider blacksmith-testbox を追加してください。

"$CRABBOX" run --timing-json -- CI=1 <check-command>

複数のコマンドを実行する場合：一度ウォームアップして ID を保存し、再利用してから停止します。

"$CRABBOX" warmup --keep --timing-json
"$CRABBOX" run --id <tbx_id> --timing-json -- <check-command>
"$CRABBOX" stop <tbx_id>

ルール：

• 1 つのリースにつき、アクティブなコマンドは 1 つです。実行中に同期／再要求してはいけません。
• bash -c を優先してください。ログインプロファイルによってディレクトリが変更される場合があります。実行シェル内で、 チェックアウトの実パスと想定されるソース／パッチを検証してください。HEAD だけでは、未コミットの同期が証明されたことにはなりません。 利用側が文書化しているハイドレーション用シェルの契約に従ってください。
• Testbox のネイティブ実行では、--id を再利用した実行も含め、毎回独自に同期が行われます。リモートのベースラインに対して --no-sync をあてにしてはいけません。Blacksmith にはネイティブなバイパスがなく、リリース済みの Crabbox バージョンではフラグが黙って無視されることがあります。意図的に変更なしで再実行する場合も例外ではありません。
• --reclaim は、チェックアウトパスの所有権を意図的に移転する場合に限ります。
• ベースまたは head が変わった場合は停止し、再度ウォームアップしてください。古いリースを上書きしてはいけません。
• warmup --ref では生の SHA は信頼できません。ブランチまたはタグを使用してください。
• blacksmith testbox list では一部の状態が表示されません。list --all または status --id <tbx_id> を使用してください。
• Testbox の status/stop では --id を使用します。status に --json はありません。
• 委任されたプロバイダーでは、--fresh-pr、--full-resync、--script*、 --env-helper、capture/download フラグは拒否されます。

Blacksmith のディレクトリダウンロード

再帰ダウンロードと必須のリモート末尾スラッシュについては、 ディレクトリダウンロードを参照してください。

信頼できない AWS

• 信頼済みのデフォルトブランチをクリーンにチェックアウトします。信頼済みの Crabbox バイナリをインストールします。
• レビュー済みの完全な head SHA ごとに新しいリースを使用します。インスタンスロール、Tailscale、ハイドレーションは使用しません。
• CI のみを転送します。信頼済みのブートストラップを --fresh-pr と一緒にアップロードします。

cd <clean-trusted-default-branch-checkout>
env -u CRABBOX_AWS_INSTANCE_PROFILE \
  "$CRABBOX" config show --json | \
  jq -e '.aws.instanceProfile == ""' >/dev/null

env -u CRABBOX_AWS_INSTANCE_PROFILE \
  -u CRABBOX_TAILSCALE \
  -u CRABBOX_TAILSCALE_AUTH_KEY \
  -u CRABBOX_TAILSCALE_AUTH_KEY_ENV \
  -u CRABBOX_TAILSCALE_EXIT_NODE \
  -u CRABBOX_TAILSCALE_EXIT_NODE_ALLOW_LAN_ACCESS \
  -u CRABBOX_TAILSCALE_HOSTNAME_TEMPLATE \
  -u CRABBOX_TAILSCALE_TAGS \
  "$CRABBOX" warmup \
  --provider aws --network public --tailscale=false \
  --tailscale-exit-node= \
  --tailscale-exit-node-allow-lan-access=false \
  --ttl 4h --idle-timeout 90m --keep --timing-json

"$CRABBOX" inspect --provider aws --id <cbx_id> --json | \
  jq -e '.network == "public" and .tailscale == null' >/dev/null

env -u CRABBOX_AWS_INSTANCE_PROFILE \
  CRABBOX_ENV_ALLOW=CI \
  "$CRABBOX" run \
  --provider aws --id <cbx_id> \
  --fresh-pr <owner/repo#number> \
  --no-hydrate --timing-json \
  --script <trusted-bootstrap-script> -- \
  <expected_full_head_sha> <check-command>

env -u CRABBOX_AWS_INSTANCE_PROFILE \
  "$CRABBOX" stop --provider aws <cbx_id>

• 信頼済みのブートストラップでは、IMDSv2 IAM 認証情報が 404 を返すことを証明し、SHA を検証し、 実行時の注入変数を削除し、ツールチェーンを固定し、インストール／テストの前に HOME を分離する必要があります。
• head が変わった場合は新しいリースを使用します。リモート PR がない場合、またはロールがないことを証明できない場合は、シークレットを使わないフォーク CI を使用してください。

直接 AWS

• 信頼済みの AWS コマンド、認証診断、再同期、クリーンな PR／コンテナー実行については、 直接プロバイダーを参照してください。
• コンテナー実行では --no-hydrate を維持し、ローカルコンテナーでの証明はローカルとして報告してください。

可観測性

• 成果物の収集／認証情報の注入については、 キャプチャと環境フラグを参照してください。
• キーは正確に指定し、コマンドは1つだけにします。シークレットを表示したり、リポジトリに書き込んだり、シェルの履歴に残したりしないでください。
• 安全な注入方法がない場合、実際の認証はブロックされます。偽のキーによる証明では不十分です。

実際のE2E

• リモートの単体テストだけでなく、分離された利用側の状態で、要求されたユーザーのエントリーポイントを実行してください。
• インストール／プロバイダー／対話型の検証と安全なリビジョン比較については、 E2Eの手順を参照してください。

デスクトップ／クロスOS

SSHターゲット、有料macOSの事前確認、WebVNC、アプリの引き継ぎ検証については、デスクトップとクロスOSのコマンドを参照してください。

失敗のトリアージ

ラッパー、プロバイダー、ハイドレーション、同期、SSH、またはコマンドの失敗を特定します。

"$CRABBOX" doctor
"$CRABBOX" status --id <id>
"$CRABBOX" inspect --id <id> --json
"$CRABBOX" logs <run_id>
"$CRABBOX" results <run_id>
blacksmith testbox list --all
blacksmith testbox status --id <tbx_id>

• キューの容量不足：自身が確保した割り当てを停止し、検証ポリシーに従ってください。リトライの集中やプロバイダーの切り替えは行わないでください。
• 同期の陳腐化：--debug --timing-jsonを実行し、直接接続するプロバイダーでは--full-resyncを1回だけ実行してください。
• 対象を絞って再実行する前に、失敗したフェーズ／JUnitを確認してください。ラッパーの不具合は、同じプロバイダー上でインストール済みCLIを使って診断し、利用側の信頼された経路を通じて更新してください。
• 停止するのは自身が確保したIDのみです。stopは--timing-jsonを受け付けません。