ParallelSandbox
アプリを開く

ツールリファレンス

エージェントが ParallelSandbox で行えることは、すべてこれらの MCP ツールを通ります。すべてテナントの API キーを伴います。名前、入力、出力は凍結された契約です。streamable HTTP エンドポイント https://mcp.parallelsandbox.com/mcp と npm の stdio アダプター parallelsandbox-mcp は同じツール群を公開します。

ボックス

ツール 入力 出力
sandbox_start services[{name, port}]、externalBaseUrl、secrets（名前の一覧）、idleTimeoutMin（任意） id、sceneUrl、takeoverUrl、status、startedFrom（spare または cold）
sandbox_exec id、cmd、cwd、timeoutSec、background stdout、stderr、exitCode、bgId
sandbox_sync id、localPath、dest ok
sandbox_get id、path 署名付きダウンロード URL、1 時間有効
sandbox_wire id、service、mode（box または external） 現在の配線表
sandbox_shot id、target（screen または url）、record（start または stop） 署名付き URL
sandbox_status id 状態、boxd の健全性、配線表、takeoverUrl、interrupted の理由
sandbox_stop id ok
sandbox_publish_version service、label、image、gitSha、note versionId
sandbox_versions なし 一覧
sandbox_takeover id、note 人が返すときに残したメッセージ。最長 30 分待つ
sandbox_secrets なし 名前の一覧、値は含まない

sandbox_start

  • services：リポジトリがボックス上で公開するサービス名とポート。名前は配線可能になります。sandbox_wire の後、その名前はボックス内でそのポート（box）または externalBaseUrl（external）に解決されます。ポートはボックス上で公開されている必要があり、docker compose の ports: がそれを行います。
  • externalBaseUrl：変更していないサービスがある場所、たとえばステージング環境。任意。
  • secrets：sandbox_secrets の名前から、ボックスが割り当てられた時点で環境変数として注入するものを選びます。列挙しないものは注入されません。
  • idleTimeoutMin：ツール呼び出しがこの分数ない場合にボックスを停止します。プラットフォーム側の既定値も最長稼働時間もありません。停止するかクレジットがゼロになるまでボックスは動き続けます。
  • startedFrom：spare は待機ボックスが割り当てられたこと（15 秒以内に利用可能）、cold はあなたのためにマシンを起動したこと（90 秒以内）を示します。

同時に動かせるボックス数は Free 3、Pro 5、Max 20 です。

sandbox_exec

  • cwd はボックスの作業ディレクトリ /work からの相対パスで、既定はそこです。
  • timeoutSec はフォアグラウンドコマンドを制限します。サーバーや長いビルドには background: true を使います。bgId が返り、出力は /work/.sbx/ 配下のログファイルにあり、別の sandbox_exec で読めます。
  • 人が takeoverUrl 経由で接続している間、sandbox_exec は実行せずロックエラーを返します。待って再試行してください。
  • ボックスの仮想ディスプレイは :99 です。sandbox_shot や takeoverUrl で見たいものは DISPLAY=:99 を付けて実行します。

sandbox_sync と sandbox_get

  • sandbox_sync はローカルディレクトリ（localPath、エージェントの作業ディレクトリからの相対）を tar にして /work/<dest> に展開します。node_modules、.git、dist、build などは除外されます。コミットしていない作業に使い、コミット済みなら sandbox_exec で git clone します。
  • sandbox_get は /work 配下のファイルまたはディレクトリの署名付きダウンロード URL を返します。ディレクトリは tar.gz になります。URL は 1 時間で失効します。

sandbox_wire

  • mode: "box"：そのサービス名はボックス内で、起動時に宣言したポートのボックス自身に解決されます。
  • mode: "external"：externalBaseUrl に解決されます。
  • 戻り値は変更したサービスだけでなく配線表全体です。
  • 同じ docker compose プロジェクト内のサービスは compose ネットワークで互いに到達できます。配線はボックス上のそれ以外のもの（テストランナー、Chromium、他のコンテナ、シーン URL）のためのものです。

sandbox_shot

  • record なし：スクリーンショット。target: "screen"（既定）は仮想ディスプレイを撮り、target: "url" はディスプレイ上に新しい Chromium でその URL を開いて撮ります。
  • record: "start" でディスプレイの mp4 録画を開始し、record: "stop" で終了して署名付き URL を返します。

sandbox_takeover

人がボックスを返すか、30 分経つまでブロックします。人はアプリであなたの note を見て、ライブ画面で作業し、「返す」を押し、メッセージを残せます。そのメッセージがツールの結果です。ログイン、CAPTCHA、支払い確認など、単独でやってはいけないことに使います。

バージョン

sandbox_publish_version は、テナントのレジストリに push したイメージをサービスの名前付きバージョンとして登録し、他のボックス（またはチームの他のエージェント）が再ビルドせずに動かせるようにします。sandbox_versions が一覧を返します。イメージ参照はテナントのレジストリ名前空間内でなければならず、sandbox_status に必要なレジストリログイン情報が含まれます。

ログ

ツール 入力 出力
logs_search project、since、query、boxId 行
logs_errors project、since、boxId 行、アップロード済みソースマップで解決されたスタック付き
logs_tail project、boxId ストリーム

project はアプリで作るログプロジェクトで、ページはブラウザ SDK でそこにログを送ります。since は期間（10m、2h、7d）または ISO タイムスタンプを受け付けます。boxId は特定のボックス内で動くページからのログに絞ります。ログは期限なく保持されます。

ボックスの状態

spare → claimed → ready → takeover（任意）→ stopping → terminated
                     ↕
                   frozen

アイドル状態の microVM ボックスは frozen になります。メモリをスナップショットに保存し、ボックス時間の課金が止まります。そのボックスへのツール呼び出しはまず復帰させてから実行され（数秒）、sandbox_stop も凍結中のボックスに有効です。何も失われません。

どの状態からも interrupted になり得ます。基盤のスポットマシンがクラウドに回収された状態です。sandbox_status が理由を報告し、そのボックスへの次のツール呼び出しも同じ内容を返します。新しいボックスを起動してやり直してください。中断されたボックス上のものは何も残りません。

REST

Web とデスクトップのアプリ、およびエージェント以外のもの向け。同じ API キーを Authorization: Bearer で送ります。

エンドポイント 用途
/v1/auth/github GitHub ログイン
/v1/keys API キーの作成と失効
/v1/boxes ボックスの一覧と詳細
/v1/boxes/{id}/screencast ライブ画面、WebSocket
/v1/boxes/{id}/input マウスとキーボード入力
/v1/takeovers 引き継ぎ待ちのリクエスト
/v1/takeovers/{id}/return メッセージを添えてボックスを返す
GET /v1/secrets, PUT /v1/secrets/{name}, DELETE /v1/secrets/{name} シークレットの管理
/v1/versions 公開済みバージョン
/v1/usage 使用量イベント
/v1/credits クレジット残高とバケット
/v1/billing/checkout Stripe Checkout
/v1/billing/portal Stripe カスタマーポータル
/v1/billing/webhook Stripe webhook
/v1/projects (log.parallelsandbox.com) ログプロジェクト
/v1/projects/{id}/sourcemaps (log.parallelsandbox.com) ソースマップのアップロード

その他の事実

  • シーン URL：https://<id>.box.parallelsandbox.com。edge 経由でボックスに到達します。
  • 引き継ぎトークン：ボックス id と有効期限を含む HMAC。ボックスはコントロールプレーンが発行した使い捨てトークンしか受け付けません。
  • 使用量イベント：稼働中のボックスごとに毎分 1 件、計量対象の操作ごとに 1 件。フィールドは tenant、box、kind、quantity、unit、cost_usd、credits、at。
  • ボックス同士は互いに見えず、クラウドの認証情報を一切持ちません。