ツールリファレンス

エージェントが ParallelSandbox で行えることは、すべてこれらの MCP ツールを通ります。接続時に OAuth で一度サインインし（クイックスタート）、以後のすべての呼び出しはサインインしたアカウントに作用します。streamable HTTP エンドポイント https://mcp.parallelsandbox.com/mcp と npm の stdio アダプター parallelsandbox-mcp は同じツール群を公開します。sandbox_sync と sandbox_pull はエージェント自身のディスクを読み書きするため、アダプター経由でしか動きません。素の HTTP では、その理由を書いたエラーを返します。クライアントごとの設定はクイックスタートを参照してください。アダプターも既定で OAuth を使い、ログインを待つ間は parallelsandbox_connect がログインリンクを返します。

ツールごと、そしてツールに共通するトピックごとに、それぞれのページがあります。このページはそのすべてを、何のためのものかとあわせて並べます。各ページは URL に index.md を付けるとプレーンな Markdown でも読めます（例：/ja/docs/tools/sandbox-start/index.md）。llms-full.txt には英語版の全ページが 1 つのファイルにまとまっています。

ボックス

`sandbox_start`

goal を持つ新しいボックスを起動します。リポジトリが公開するサービスをそれぞれの名前で宣言でき、環境、シークレット、サイズ、ツールチェーンも選べます。ボックスの id、URL、受け取ったサービスを返します。

`sandbox_list`

チームメイトのものも含めてアカウントのボックスを最近使われた順に一覧し、それぞれの名前、goal、状態、URL を返します。読むだけで、ボックスを起こしません。

`sandbox_media`

アカウントのすべてのボックス（停止したものも含む）で各ステップが残したスクリーンショットと録画を時間順に一覧し、ボックスの名前と goal、画像ごとのダウンロード URL を返します。ある期間に作ったもの・確かめたものをまとめるときに使います。読むだけで、ボックスを起こしません。

`sandbox_status`

1 つのボックスのすべて：状態、goal、直近 30 件のステップ、使っている会話がまだ作業中か、配線、サービス、実行中のコマンド、クレジット。読むだけです。

`sandbox_stop`

ボックスを完全に止め、マシンとデバイスを解放します。/work の中身はすべて消えます。人に見せるものがなくなったら、すぐに呼びます。

仕上げ

ボックスの作業の終え方：人に結果を試してもらうなら sandbox_review、見せるものがなければ sandbox_stop。それぞれ何が残るかも。

別の会話が残したボックスを引き継ぐ

別の会話が残したボックスを続ける方法：sandbox_list で見つけ、sandbox_status で goal、steps[]、agent を読みます。元の会話がまだ作業中かもしれないときは、先に人に聞きます。

`sandbox_exec`

ボックスでシェルコマンドを 1 つ実行します。タイムアウト付きのフォアグラウンドか、ログファイルに出力するバックグラウンドで動かします。画面が変わると、フォアグラウンドのステップはスクリーンショットと録画を人のために残します。

`sandbox_procs`

sandbox_exec の background: true で始めたコマンドを一覧し、終了を待ち、止めます。pkill -f や pgrep -f の代わりに使います。それらのパターンは、コマンドラインにそれを含むすべてのプロセスに一致し、ほかのジョブも含まれるからです。

`sandbox_sync`、`sandbox_get`、`sandbox_pull`

手元のマシンとボックスの間でファイルを動かす 3 つのツールです。

`sandbox_sync`

ローカルのディレクトリ、または 1 つのファイルをボックスの /work/<dest> にアップロードします。違うファイルだけを送ります。stdio アダプター経由でのみ動きます。

`sandbox_get`

/work、/tmp、/dev/shm の下のファイルやディレクトリを 1 時間有効なダウンロード URL として取り出します（ディレクトリは tar.gz）。小さな画像は結果にも直接入ります。

`sandbox_pull`

sandbox_get とダウンロードを合わせたもの：ボックスのファイルをローカルのパスに書き、ディレクトリならそこに展開します。stdio アダプター経由でのみ動きます。

`sandbox_build`

インストールやコンパイルの手順を実行して出力を保存します。入力が同じボックスは、ビルドし直さずに数秒で復元します。

`sandbox_wire`

宣言した名前の行き先をボックス内の自分のプロセスと externalBaseUrl の間で切り替えます。動作中のボックスに新しい名前を宣言したり、名前を別のボックスや公開したバージョンに向けたりもします。

別のボックスへのリンク

リンクを使うと、あるボックスから、自分の別のボックスで動くサービスを、呼び出し側がもともと使う名前で呼べます。宣言の仕方、ルール、相手のボックスの状態ごとに接続がどうなるか。

リンクや環境のアドレスを引き取る

新しいボックスでは、リンクやコネクタ経由で外に出ていた名前を、sandbox_wire がその場で自分のプロセスや公開したバージョンに切り替えます。ボックスの URL は変わりません。

`sandbox_shot`

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

`sandbox_scene`

人が自分の端末でボックスの URL から開いているページで JavaScript を実行し、結果を返します。

`sandbox_say`

アプリでボックスを見ている人に状態を 1 行知らせます。人に質問する手段ではありません。相手のメモは fromHuman で返ってきます。

`sandbox_review`

試したバージョンを人に渡し、カードをすぐ表示して、レポートか確認完了を待ちます。open は人が試すものに合わせて選びます（Web ページはその port を付けた web、デスクトップアプリやスマホアプリはボックスの画面の box）。宣言がないクライアントは最大 25 秒、長い待機を設定したクライアントは最大 30 分待ちます。reviewId で同じ回を再開します。

`sandbox_report`

固定の reportId で人のレポートを読み直します。囲み画像、録画、時刻付き文字起こしと更新済みのファイル URL が含まれます。

`sandbox_takeover`

人にしかできないこと（サインイン、CAPTCHA、確認コード）をボックスのライブ画面でしてもらい、リンクが有効な間（30 分、人が初めて開くと開いてから 30 分）、戻してもらうのを待ちます。

`sandbox_feedback`

何をどう動かし、何に困り、何を変えるべきかを ParallelSandbox チームに報告します。セッションでボックスを使ったら 1 件送ります。

`sandbox_secrets`

アカウントのシークレットの名前を一覧するか（値は返しません）、指定したシークレットを動作中のボックスに環境変数として注入します。

`sandbox_environments`

人の環境（自分の dev や staging）を一覧します。コネクタ経由でボックスから届くプライベートアドレス、各接続がオンラインか、ボックスが設定を受け取れるサービス。

`sandbox_device`

ボックスに Android エミュレーターか iPhone シミュレーターを借ります。ボックスの画面に表示されます。ボックスのデバイスの一覧と、1 台の返却もできます。

バージョン

公開したバージョンがあれば、ほかのボックスはビルドし直さずにそのサービスを動かせます。

`sandbox_publish_version`

アカウントのレジストリに push したイメージを、サービスの名前付きバージョンとして記録します。ほかのボックスはビルドし直さずに動かせます。

`sandbox_versions`

公開したバージョンを新しい順に一覧します。1 つのサービスに絞ることもできます。ほかのボックスは services[].version で動かします。

公開したバージョンを動かす

version で宣言したサービスは、公開したイメージをビルドなしでその名前で動かします。ボックスによる pull と起動、env の追加変数、進み具合の確かめ方と切り替え方。

作る前に設計する

新しく作るもの・変えるものは、作る前に人と一緒に設計します。順番は、画面を sandbox_draft、サービスを sandbox_architecture、保存するデータを sandbox_schema で描き、それからボックスで作って sandbox_review で渡します。作業が触れない段階だけを飛ばします。人がラフ、スケッチ、構成図、スキーマを求めたときもこれらを使い、HTML や画像ファイルを書いて代わりにしません。どのツールも JSON だけを受け取り、ボックスは要りません。各版をツールの結果に返すとともに人のアプリの設計のページに表示し、人はそこで丸で囲み、話し、文字を書き込みます。sandbox_draft は手描き風のスマホのラフ、sandbox_architecture はすっきりした一般的な構成図で、どちらもサーバーが描く画像です。sandbox_schema は画像ではなくテキストで、すべてのフィールドに短い note が必要です。new: true は今と比べて新しいもの・違うものに付け（ラフは赤、構成図は青、スキーマは [new]）、前の版から変えたことは note に書きます。画像の凡例などの決まった文字はアカウントの言語に従い、あなたが書く文字は渡したとおりに出ます。人の報告は確認のフィードバックと同じようにその版を描いた会話に戻り（自動で戻るには stdio アダプター 0.6.0 以降。sandbox_report に reportId だけを渡して読みます）、同じ topic で同じツールを呼ぶと次の版（v2、v3…）になります。承認の手順はありません。設計はボックスではなく、アカウントとそれを描いた会話に属し、ボックスが停止しても残ります。id は任意で、この作業のボックスを渡すとそのボックスのページにも設計が表示されます。これらの呼び出しでボックスが起きることはありませんが、成功すると使用に数えられ、呼んだ会話がそのボックスを持ちます。

`sandbox_draft`

画面を作る前にラフを描きます。JSON を送るとサーバーが手描き風のスマホのラフ（最大 3 枚、1 枚にスマホ最大 4 台）を描き、ツールの結果に返すとともに、人のアプリの設計のページにも表示します。人はそこでスマホを 1 台ずつ見て、丸で囲み、話し、文字を書き込んで報告します。

`sandbox_architecture`

作る前に、各部分のつながりを描きます。アプリ、サービス、データベース、キュー、外部 API ごとに箱を 1 つ、誰が誰を呼ぶかに矢印を 1 本描き、上から下へ自動で並べたすっきりした構成図（新しいものは青）にして、ツールの結果と人のアプリの設計のページに表示します。

`sandbox_schema`

作る前に、保存するデータを画像ではなくテキストで並べます。テーブルとそのフィールドを並べ、フィールドごとに型、何が入るかの短い説明（すべてのフィールドで必須）、参照するテーブルを書きます。テキストはツールの結果に返り、人はアプリの設計のページでテキストの表として見ます。

ログ

3 つのツールは ParallelSandbox 自身のログサービスを読みます。ページはブラウザ SDK でそこにログを送ります。Sentry などほかのエラートラッカーは読みません。

ツールリファレンス

ボックス

sandbox_sync、sandbox_get、sandbox_pull

バージョン

作る前に設計する

ログ

`sandbox_sync`、`sandbox_get`、`sandbox_pull`