sandbox_shot

ボックスの画面、最前面のウィンドウ、新しいブラウザで開いた URL、またはボックスのブラウザですでに開いているタブのスクリーンショットを撮ります。複数ページをまとめて撮ったり、画面を mp4 に録画したりもします。

• record なし：スクリーンショット。結果に画像がそのまま入り、1 時間有効な URL と、撮影した時刻 capturedAt も返ります。path はその画像のボックス内のコピーで、/work/.sbx/shots/ にあります（/work からの相対パス。新しい 100 枚を保持）。画像そのものを保存したり人に渡したりするときは、sandbox_pull か sandbox_get でこれを取ってください。
• 人がボックスを引き継いでいる間も target: "screen"、"window"、"url" は撮影でき、結果に takeover: true が付きます。写っているのは人が見ている画面です。target: "tab" は人が使っているかもしれないタブを変えるので、sandbox_exec と同じく返されるまで待ちます。
• target: "screen"（既定）は仮想ディスプレイを撮ります（390 × 844 の縦向きで、orientation: "landscape" で起動したボックスだけ 1280 × 800）。target: "window" は最前面のウィンドウだけを（デスクトップなしで）撮り、結果に window が加わります。これはウィンドウの画面上の x,y,幅,高さ（例："100,80,900,600"）なので、画像上の座標でクリックするときは x と y を足してください。画面より大きいウィンドウは画面に入っている部分だけを撮り、clipped がそう伝えます。windows は画面上の見えているウィンドウすべてで、撮ったものが先頭です。それぞれ id、name、x、y、width、height と、プログラムが報告していれば開いた pid を持ちます。ウィンドウはプログラムが終わるまで残るので、作業を終える前に自分のものが残っていないかをこれで確かめます（background: true で開いたものは sandbox_procs の stop で終了、どれでも xdotool windowkill <id> で閉じられます）。どちらでも stableMs（100〜10000）を指定すると、画面がその時間変わらなくなってから撮るので、ページ遷移やアニメーションの途中を撮りません。待つのは最大 20 秒で、落ち着かなければ最後のフレームを stable.settled: false 付きで返します。
• target: "url" は新しい、ログインしていない headless Chromium で url を開いて撮ります。width と height はビューポートを CSS ピクセルで決めます（既定はボックスの画面の大きさで、縦向き 390 × 844、横向き 1280 × 800。width だけなら高さは画面のまま）。ページはちょうどその幅で、Chromium のウィンドウ最小幅 500 ピクセルより狭くてもレイアウトされます。スマホやタブレットのレイアウトを見るときはこれを使います（width: 390, height: 844）。deviceScaleFactor（0.5〜4、iPhone なら 3 など）で画像はビューポートのその倍数になり、mobile: true はタッチ付きのスマホを模すので何もホバーせず、<meta name=viewport> のないページは実機と同じく 980 ピクセル幅でレイアウトされます。fullPage: true はビューポートだけでなくページ全体を撮ります（height は無視されます）。開けなかったページには loadError が付きます。urls（URL のリスト）を渡すと複数ページを一度に撮ります（同じ大きさのページは 1 つのブラウザを共有します）。画像は結果に入らず、ボックスの /work/.sbx/shots/ に書かれ、結果の files[] に各ページの url、path（/work からの相対パス）、bytes、capturedAt が並びます。見たいものを sandbox_get で取り出してください（paths で複数まとめて取り出せます）。このまとめ撮りはステップ 1 つ（summary は 2 urls のよう）として記録され、画像は付きません。人はアプリでそれらの画像を見られず、/media にもなく、ボックスを止めると /work と一緒に消えます。
• target: "tab" は、ボックスのブラウザですでに開いていて、ログインしたままのページをそのまま撮ります。スクロールもポインターの移動もしないので、ホバーの状態も写ります。そのブラウザは --remote-debugging-port=9222 付きで起動しておく必要があります（Electron も同じ引数です）。ボックスで複数のブラウザがデバッグポートを開いているときは port で指定します。起動中のブラウザは最大 45 秒待つので、起動後の sleep は要りません。tab はタブの id、または URL かタイトルの一部でタブを選び（既定：ビューポートを保っているタブ、なければ最近使ったタブ）、結果の tab がどれを撮ったかを示します。width はそのタブにその幅のビューポートを与え、height（既定：ウィンドウ自身の高さ）、deviceScaleFactor、mobile は上と同じです。ボックスは reset: true、タブが閉じる、またはブラウザが終わるまでそれを保つので、タブでクリックや入力を続けてもスマホのレイアウトが崩れません（自分の CDP スクリプトから送った Emulation.setDeviceMetricsOverride は、その接続が閉じると元に戻ります）。width、height、deviceScaleFactor、mobile のどれかを付けた呼び出しは、エミュレーションするビューポート全体を置き換え、保てるタブは一度に 1 つです。結果の viewport はページが実際に見た大きさです。
• waitFor（target: "url" または "tab"）：この CSS セレクターが見えている要素に一致してから、または js: を付けたときはこの JavaScript の式が真になってから（await 可）撮ります。待つのは最大 30 秒で、条件が満たされなくてもスクリーンショットは waitFor.met: false 付きで返り、評価できない条件はエラーになります。
• pageErrors（target: "url" または "tab"）：ページ自身が報告したエラーです。console は console.error、失敗した console.assert、捕捉されなかった例外（スクリプトと行番号付き）、ブラウザーが止めたもの（Content Security Policy 違反など）、failedRequests は読み込めなかったリソースで、URL の後に理由が続きます（net::ERR_NAME_NOT_RESOLVED、the server responded with a status of 404 (Not Found)）。それぞれ最初の 10 件まで、1 件 300 文字までで、残りの件数は more です。何も報告しなかったページには pageErrors がありません。対象は今表示しているページの最後のページ遷移以降で、target: "tab" では呼び出し前に起きたものも含むので、読み込み画面で止まったページの原因がわかります。

sandbox_exec { "id": "<id>", "cmd": "chromium --no-sandbox --remote-debugging-port=9222 --user-data-dir=/tmp/chrome http://localhost:5173/", "background": true, "note": "ボックスのブラウザでアプリを開く" }
sandbox_shot { "id": "<id>", "target": "tab", "width": 390, "height": 844, "mobile": true, "deviceScaleFactor": 3, "waitFor": "nav [aria-label='Menu']" }
sandbox_shot { "id": "<id>", "target": "tab", "waitFor": "js:document.querySelectorAll('.order').length > 0" }
sandbox_shot { "id": "<id>", "target": "tab", "reset": true }

• ボックスの画面に自分でページを置いておくとき（操作し続ける Chromium）は、画面の向きに合った引数で Chromium を開いてください。sandbox_exec の「ボックスの画面のブラウザ」を参照してください。
• record: "start" でディスプレイの mp4 録画を開始し、record: "stop" で終了してそのダウンロード URL（1 時間有効）を返します。録画がボックスの凍結を止めるのは、ボックスが最後に使われてから（ボックスに作用するツール呼び出しの終了か復帰。ボックスの状態を参照）まる 1 時間までです。バックグラウンドのコマンドがボックスを起こしておけるのも同じ時点までです。最後の使用がフォアグラウンドのコマンドなら、この 1 時間はそのコマンドが終わった時点から数えます。録画そのものの長さは関係ありません。それを過ぎ、ほかにボックスを起こしておくもの（フォアグラウンドのコマンド、人の引き継ぎなど。ボックスの状態 を参照）がなくなると、ParallelSandbox は録画をアップロードせずに止め、ボックスはいつもどおり凍結します。mp4 はボックスの /work/.sbx/rec/rec-<unix 時刻>.mp4 に残るので、sandbox_get で取り出します（ボックスが凍結していても、この呼び出し自体がボックスを復帰させます）。自動で止められた録画はステップになりません。アプリにも /media にも出ず、取り出さなければボックスを止めたときに /work と一緒に消えます。sandbox_get で取り出したコピーは一時転送ファイルで、約 1 日後に自動削除され、保存ファイルの料金はかかりません（クレジットを参照）。必要なファイルはボックス停止前にダウンロードしてください。停止後は新しい URL を取得できません。
• 録画から 1 コマを 1 枚の画像として取り出す：ffmpeg -ss 5 -i in.mp4 -frames:v 1 -update 1 out.png（-update 1 で、out%03d.png のような連番パターンではなく 1 つのファイルに書きます）。ffmpeg はボックスに入っています。
• スクリーンショットと、record: "stop" で止めた録画はどれもボックスのステップとして、人のアプリのそのボックスの「スクリーンショットと録画」に表示されます（停止後も「停止済み（過去 7 日）」で見られます。sandbox_exec を参照）。ファイルは 7 日後に削除されます。urls でまとめて撮ったものは例外で、まとめて 1 つのステップとして記録されるだけで、画像は付きません（上記を参照）。1 時間を過ぎた URL は取り直せます（sandbox_shot をもう一度呼んでも新しい画面を撮るだけで、前のものは戻りません）：API キー（Authorization: Bearer <key>）を付けて GET https://api.parallelsandbox.com/v1/boxes/{id}/media を呼びます（REST だけで、対応する MCP ツールはありません）。このボックスで直近 7 日間に撮られた、画面が残っているステップを新しい 200 件まで古い順に、止めたボックスでも返します：{"keepDays": 7, "steps": [...]}。各ステップのフィールドは sandbox_status の steps[] と同じで、ほかに media[] があり、それぞれ kind（video か image）、url、bytes、動画には durationSec が付きます。URL は呼ぶたびに署名し直され、少なくとも 1 時間有効です（REST を参照）。画面の記録がそれぞれいつまで残り、ボックスを止めたあと誰が見られるかは、仕上げの表を参照してください。

すべてのツールとトピックはツールリファレンスに並んでいます。