ParallelSandbox

parallelsandbox-mcp

ParallelSandbox MCP サーバー用の stdio アダプターです。https://mcp.parallelsandbox.com/mcp と同じツール（sandbox_*、logs_*）を公開し、OAuth でサインインします。また、sandbox_sync と sandbox_pull をローカルで実装しています。エージェントはコミットせずに作業ディレクトリをボックスにアップロードし、ボックス内のファイルを自分のマシンに書き戻すことができます。バージョン 0.4.0 以降では、サインインと接続の許可のためにブラウザーが開きます。API キーは不要です。

使用方法

npx -y parallelsandbox-mcp

Claude Code：

claude mcp add parallelsandbox -- npx -y parallelsandbox-mcp

その他の MCP クライアントでは、上記のコマンドを stdio サーバーとして実行してください。

初回の接続はすぐに開始され、その後 OAuth のためにブラウザーが開きます。サインインが完了するまで、parallelsandbox_connect ツールはサインインリンクを返します。サインイン完了後、アダプターはサンドボックスとログのツールを通知します。ツール一覧を再読み込みしないクライアントは、一度再接続する必要があります。parallelsandbox_connect を再度呼び出すと、状態を確認したり、キャンセルされたサインインを再試行したりできます。再試行が必要になるまで、サインインは 5 分間待機します。

トークンファイルは ~/.parallelsandbox に保存され、MCP エンドポイントごとに分かれています。パーミッションは 0600 です。複数の会話で同じサインインを共有し、ファイルロックを使ってトークンの更新を直列化します。更新応答が失われた場合は、新たにサインインする必要があります。使用済みの更新トークンが再利用されることはありません。既存の PARALLELSANDBOX_API_KEY 設定も引き続き使用できます。

sandbox_sync または sandbox_pull を使う必要がない場合は、このパッケージを使わず、OAuth でサインインして HTTP 経由で直接接続してください（その後、Claude Code で /mcp を実行します。キーは不要です）。通常の HTTP 接続では、これら 2 つのツールはエラーを返します。お使いのマシン上のファイルを読み書きするためです。

claude mcp add --transport http parallelsandbox https://mcp.parallelsandbox.com/mcp

環境変数

変数	デフォルト値	用途
PARALLELSANDBOX_API_KEY	未設定	既存の API キー（任意）。設定すると OAuth をスキップします
PARALLELSANDBOX_AUTH_DIR	~/.parallelsandbox	OAuth トークンファイルとロック
PARALLELSANDBOX_NO_BROWSER	未設定	1 に設定すると、ブラウザーを開かずにサインインリンクを取得します
PARALLELSANDBOX_MCP_URL	https://mcp.parallelsandbox.com/mcp	MCP エンドポイント
PARALLELSANDBOX_API_URL	https://api.parallelsandbox.com	sandbox_sync が使用する REST のベース URL
PSBX_TOOL_TIMEOUT_SEC	60	MCP ホストで設定されたツールの絶対的な期限（秒単位）。安全なレビュー待機時間の判定に使用します（デフォルトは 25 秒、最大は 1800 秒）
PSBX_ADAPTER_SILENCE_MS	75000	アダプターが呼び出しを諦めるまで、呼び出しの接続が無応答のままになってもよい時間（「タイムアウト」を参照）
PSBX_FEEDBACK_HOST	未設定	開発用フィードバックブリッジ：claude-code または codex。通常の MCP 接続には影響しません
PSBX_CODEX_CLI	ホストの codex プロセス	codex queue によるフィードバック配信に使用する codex 実行ファイルの絶対パス（明示的にペアリングされた App Server にも使用）
PSBX_FEEDBACK_DIR	~/.cache/parallelsandbox/feedback	フィードバックチケット、メールボックス、リレー状態
PSBX_HOOK_HOLD_SEC	1200	レビューが要求された直後に、Cursor と Gemini CLI のターン終了フックが待機する時間
PSBX_CODEX_HOST_SOCKET	未設定	既存の App Server のプライベート制御ソケットの絶対パス。Desktop IPC はサポートされていません
PSBX_CODEX_FEEDBACK_DIR	~/.cache/parallelsandbox/codex-feedback	Codex フックとアダプターで共有されるプライベートなバインドチケット

開発用エンドポイントを使用する場合は、PARALLELSANDBOX_MCP_URL と PARALLELSANDBOX_API_URL の両方に、その開発用アドレスを設定してください。

sandbox_sync

{"id": "<box id>", "localPath": "/abs/path/to/repo", "dest": "repo"} は、localPath をボックス上の /work/<dest> に同期します。 dest は /work からの相対パスです（/work/repo ではなく repo です。先頭の /work/ は削除され、それ以外の絶対パスはアップロード前に拒否されます）。 絶対パスを指定してください。相対パスは、このアダプターの作業ディレクトリ（MCP クライアントを起動した場所）を基準に解決されますが、これはエージェントの作業ディレクトリとは限りません。Git の作業ツリー内では、追跡対象のファイルと、.gitignore で除外されていない未追跡ファイルを取得し、その中から dest に既にあるファイルと異なるものをボックスに問い合わせ、該当するファイルだけをアップロードします。そのため、編集後に同期すると、その編集箇所だけが送信されます。ボックス内で変更されたファイルは異なるものとして扱われ、ローカル版で上書きされます。ただし、"exclude" の glob が対象に含まれる場合（["capacitor.config.ts", "renderer/dist-win"] など）は、そのパスは送信も比較もされず、ボックス内のコピーが古いファイルとして一覧表示されたり削除されたりすることもありません。Git 管理外の場合、および commit を指定した場合も、同じ方法で差分のみを比較して送信します。Git 管理外では、node_modules、.git、dist、build、coverage、.venv などを除くすべてのファイルを取得します。.git は送信されません。

送信対象のディスク上のサイズが 100 MB を超える同期では、何も送信されず、サイズの大きいフォルダーが一覧表示されます。そのサイズが想定内の場合は、"maxMB" で上限を引き上げてください。"dryRun": true を指定すると、ボックスとの比較を行い、送信または削除せずに送信対象を報告します。実行中は、進捗を要求するクライアントに対して、アダプターが 10 秒ごとに進捗（ハッシュ計算、比較、アップロード済みメガバイト数）を報告します。fetch failed、接続のリセット、または HTTP 502/504 で失敗したアップロードは、もう一度送信され、その旨が notes に記載されます。2 分間何も進行しない場合、またはすべてを受信した後にボックスが 10 分以内に応答しない場合は、その段階を示すメッセージとともに失敗します。

結果には処理内容が示されます。sentPaths（送信したファイルの先頭 50 件。件数は sentFiles）、changedOnBox（ボックスが実際に書き換えたファイル）、remotePath、および作業ツリー内の場合は uncommitted（HEAD と異なるパス）です。ほかのセッションが同じチェックアウトを共有している場合、それらは未完了の作業である可能性があります。その場合は、"commit": "HEAD" を指定し、"alsoPaths" に自分のファイルを列挙してください。commit には任意のリビジョンを指定でき、存在しない場合は失敗します。commit を指定しない場合、alsoPaths はそのパスだけを送信します。

ローカルで削除または名前変更されたファイルはボックスに残り、無視ルールで除外されるパス（node_modules、ビルド出力、.env）を除いて、staleInDest に一覧表示されます。"prune": true を指定すると、それらを削除します。localPath 内のファイルが 1 つだけの場合は、dest 自体に配置されます（"dest": "renderer/.env" は /work/renderer/.env に書き込みます）。ただし、dest が / で終わる場合、またはボックス上ですでにフォルダーである場合は除きます。

node_modules は送信されません。そのため、package-lock.json、pnpm-lock.yaml、または yarn.lock があるフォルダーについて、ボックスに node_modules がない場合、あるいは npm の場合はインストール済みパッケージがロックファイルと異なる場合、notes（および deps）にボックス上で実行するコマンドが記載されます。dest への初回同期では、無視ルールによって除外されたビルド設定（tsconfig.json、.env.local）も notes に一覧表示され、送信方法が示されます。また、送信対象となる gradlew、mvnw、または #! で始まる *.sh スクリプトに実行ビットがない場合は、その都度通知されます。

サブモジュール：commit を指定しない場合、初期化済みのサブモジュールは、ディスク上のすべての内容を含む通常のディレクトリとして送信されます。git archive ではサブモジュールが除外されるため、commit を指定する場合は "submodules": true を指定し、ツリーに記録されたコミットの各初期化済みサブモジュールを追加してください。"baseline": "origin/main" を指定すると、そのコミットも <dest>-baseline に送信されます。これにより、テストが失敗した場合に両方で実行して、すでに失敗していたかどうかを確認できます。dest 内の各 node_modules は、ベースライン側にない場合はハードリンクとしてコピーされます（"baselineDeps": false を指定すると省略されます）。Vite のキャッシュは除外されるため、2 つのツリーで共有されることはありません。同期が失敗した場合、新しいデータはボックスに届きません。そのボックスで次に実行する sandbox_exec には、その旨のリマインダーが付加されます。

sandbox_pull

{"id": "<box id>", "path": "<path under /work>", "localPath": "/abs/path/on/your/machine"} は、ボックスからファイルまたはディレクトリをダウンロードします。ファイルは localPath に書き込まれます。ディレクトリの内容は localPath に直接展開されます。これは sandbox_sync と逆の動作です。path が app/dist、localPath が /abs/dist の場合、/abs/dist/dist/index.html ではなく /abs/dist/index.html になります（0.3.3 より前のバージョンでは、余分な階層が追加されていました）。結果には、書き込まれたファイル数を示す files と、先頭50件のパスを示す paths が含まれます。"extract": false を指定すると、tar.gz を1つのファイルとして保持します。tar.gz 内では、ディレクトリ自体が最上位のエントリーになります。相対パスの解決方法は sandbox_sync と同じです。dest も localPath の別名として使用できます。残るのはローカルコピーのみです。ParallelSandbox 側の受け渡し用コピーは、約1日後に削除されます。

展開すると、既存の localPath の内容にマージされます。"clean": true を指定すると、ボックスのディレクトリと完全に同じ状態になります。まずアーカイブをその隣に展開し、成功した場合にのみ置き換えます。また、結果の removed には削除されたローカルファイルの数が記録されます。git チェックアウト、ホームディレクトリ、アダプターの作業ディレクトリ、およびそれらの親ディレクトリに対しては、clean は拒否されます。ボックスがディレクトリのパッキング中に書き込みを続けていたファイルは、changedWhileReading に一覧表示されます。ダウンロードは進行状況を報告し、データが2分間届かないと中断します。最初のリンクが拒否された場合は、新しいリンクを1回取得します。

ボックスを使用している会話

通常の MCP 接続では、アダプターの起動時にランダムな ID を選び、すべての呼び出しで X-Psbx-Agent として送信します。登録済みのネイティブセッションでは、スーパーバイザーが所有する1つの ID をすべてのターンで使い続けます。スーパーバイザーは、停止するまでその存在を維持します。最初のツール呼び出し後は、1分ごとに /v1/agents/<id>/heartbeat に報告し、会話が終了すると（stdin が終了するか、SIGTERM、SIGINT または SIGHUP を受け取ると）/v1/agents/<id>/leave に報告します。アプリはこれを使って、AI がまだ作業中のボックスと、sandbox_review または sandbox_stop が呼び出されないまま会話が終了したボックスを区別します。会話が強制終了された場合（leave が送信されない場合）は、最後のハートビートから3分後に終了したものとして扱われます。ほかに送信されるものはありません。プロンプトも会話の記録も送信されません。

クライアントを再起動すると、新しい ID を持つ新しいアダプターが起動します。そのため、再起動前に会話で使用していたボックスは、再び使用されるまで agent.state が left と表示されます。再起動後の会話では、そのボックスをそのまま使い続けられます。

タイムアウト

sandbox_takeover は、人がボックスを返すまでブロックします。上限は30分です。sandbox_review は、人のレビューカードをすぐに作成し、その後、呼び出し元が宣言した予算内で報告または完了を待ちます。デフォルトのアダプターとサポート対象外の HTTP クライアントは最大25秒待機します。明示的にサポートされているクライアントは最大30分待機できます。明示的に指定した waitSec は、その予算とレビューの準備にかかった時間によって制限されます。結果には、実効 waitSec と callerWaitMaxSec が含まれます。最終結果の前に、レビュー ID とエントリー URL を含む進捗が通知されます。待機せずに明示的に引き継ぐには waitSec: 0 を使用します。別のカードを what で作成する代わりに、タイムアウトしたラウンドを reviewId で再開することもできます。アダプターは、引き継ぎとレビューでは31分、その他の呼び出しでは65分待機します（フォアグラウンドの sandbox_exec の実行時間は最大60分です）。 クライアント呼び出しをキャンセルすると、その制御接続もキャンセルされます。レビューやフィードバックは削除されません。 各フォアグラウンドの sandbox_exec には、アダプターが選ぶ execId が付与されます。結果が戻る途中で失われた場合（75秒間データがない場合、または結果を受信する前にストリームが終了した場合）、コマンドはボックス上で実行を続けます。エラーには sandbox_procs {action: "wait", bgId: <execId>} が示され、実行終了後に終了コードと出力の末尾を返します。 また、アダプターは10分ごとにサーバーのツール一覧を確認し、変更があれば notifications/tools/list_changed を送信するため、会話が長くなっても古いスキーマを使い続けることはありません。 待機ツールのルートは、その呼び出しが有効な間だけ存続します。登録済みのネイティブセッションは、ターン終了後も継続するために、以下のスーパーバイザーを使用します。

AI の終了後も続行する

parallelsandbox-agent は、登録済みのネイティブな Claude Code、Codex、または Gemini CLI セッション用の永続的なスーパーバイザーを実行します。最初のプロンプトも以降のすべてのプロンプトも、各プロバイダーのネイティブな会話履歴を使用します。そのセッションで作成されたレビューは、ボックスとレビューを同じスーパーバイザーに登録します。App の報告が送信されると、スーパーバイザーはそれを取得し、現在のネイティブターンが終了するまで待ってから、保存されているセッション UUID を正確に再開します。再開した AI は sandbox_report を呼び出し、ネイティブの MCP 接続を通じてテキスト、画像、録画、タイムスタンプ付き文字起こしを受け取ります。報告を読み取ったネイティブターンが正常に完了した場合にのみ、配信を確認できます。App の受領確認は送信後に独立してポーリングされます。「受信済み」は、要求された変更が完了したことを意味しません。

npx -y --package parallelsandbox-mcp parallelsandbox-agent start \
  --provider claude-code --cli /absolute/path/to/claude --cwd /absolute/path/to/project \
  --prompt "Work on this project and use sandbox_review when it is ready to try."

同じコマンド内で、ネイティブの Codex 実行ファイルを使う場合は codex、ネイティブの Gemini 実行ファイルを使う場合は gemini を選択します。コマンドは正確なセッションディレクトリを返します。後続のプロンプトには send --session <directory> --prompt <text>、結果の確認には status --session <directory>、スーパーバイザーの停止には stop --session <directory> を使用します。プロバイダーの実行時認証情報が利用可能である必要があります。有効なプロバイダーエンドポイントとともに、ANTHROPIC_API_KEY、CODEX_API_KEY/OPENAI_API_KEY、または GEMINI_API_KEY を設定してください。ランナーはプライベートなネイティブ設定ディレクトリを使用します。グローバル CLI の OAuth サインインは自動的には引き継がれません。設定、復旧、権限プロファイルについては、SESSION_FEEDBACK.md を参照してください。

登録は、元のセッションをこのランナーで開始したときに行われます。以前の実験的な Claude Channel と Codex App Server のペアリングブリッジは、引き続き別個のオプトイン連携として利用できます。これらは、登録済みのネイティブランナーによる配信には使われません。

元の会話へのフィードバック（Codex、Claude Code、Cursor、Gemini CLI）

sandbox_review が成功すると、そのレビューに対する App のフィードバックは、レビューを依頼した同じ会話に戻ります。sandbox_draft、sandbox_architecture、sandbox_schema で描画した各バージョンも同様です。App でユーザーが丸で囲んだ箇所や、それについて述べた内容は、描画した会話に戻ります。 アダプターはチケット（ボックス、レビュー、アダプター自身のエージェント ID。認証情報は含みません）を書き込み、アカウントごとに小規模なローカルリレーを 1 つ起動します。リレーはその会話用のフィードバックコンシューマーを登録し、送信されたレポートを取得して、sandbox_report でどのレポートを読むべきかを伝える短いフォローアップを会話に渡します。この読み取りにより、App の受領確認が既読になります。ホストごとの違いは、フォローアップが会話に届く方法だけです。

ホスト	フック	会話が受け取る方法
Codex（Desktop、CLI、IDE）	なし	スレッドは Codex のツール呼び出しメタデータから取得されます。リレーはホスト独自の codex queue --thread を実行します。アイドル状態のスレッドではターンが開始され、処理中のスレッドでは現在のターンの後に受け取ります。
Claude Code（CLI、デスクトップ）	install claude-code	バックグラウンドの asyncRewake フックがアイドル状態のセッションを起動します。処理中のセッションでは、次のツール呼び出しの後に読み取ります。セッションを再度開くと、閉じている間に届いた内容が引き継がれます。claude -p "<prompt>" はフックをフォアグラウンドで実行するため、この場合、レビューを開く呼び出しはレポートを待ち、sandbox_report はすぐに返ります。
Cursor	install cursor	afterMCPExecution がレビューを添付し、stop フックが followup_message として返します。実際の Cursor エージェントで、エンドツーエンドの検証はまだ行われていません。
Gemini CLI	install gemini	AfterTool がレビューを添付し、AfterAgent フックが decision: "block" とともに返します。

手動で設定する必要はありません。マシン上にクライアントのフックがない場合、アダプターのサーバー指示は、会話内で AI がユーザーに、使用しているクライアント用のコマンドを実行してよいか尋ねるよう指示します（npx -y parallelsandbox-mcp install <client>。ユーザー設定を変更します）。また、sandbox_review の結果には、レビューがまだ会話に戻るようルーティングされていない場合にその旨が示されます。ユーザーが同意したら、AI は最初のレビューの前にコマンドを実行します（またはコマンドを実行して、reviewId と waitSec: 0 を指定してレビューを再度リクエストします）。Claude Code と Cursor では、この方法で追加したフックが実行中の会話に適用されます。Gemini CLI は起動時にフックを読み込むため、最初のレビューはそのボックスで次に実行する sandbox_status または sandbox_review によって引き渡され、以降のセッションでは自動的に処理されます。install はクライアントのユーザー設定に変更をマージし（Claude Code は CLAUDE_CONFIG_DIR を尊重します）、それ以外の内容を保持したうえで、変更前のファイルの .psbx-backup を作成します。Cursor はデフォルトで Claude Code のフックも実行します。Claude Code のフックは、それを実行した Claude Code セッション内（CLAUDE_CODE_SESSION_ID）でのみ動作するため、Cursor の会話をブロックしたり、誤った宛先にルーティングしたりすることはありません。

Cursor と Gemini CLI には、アイドル状態の会話を起動する手段がありません。これらのホストでは、レビューがリクエストされた直後、ターン終了時のフックが最大 20 分間（PSBX_HOOK_HOLD_SEC）待機します。それ以外の場合は、その会話の次のターンが終了したときに、待機中のフィードバックを渡します。

状態は ~/.cache/parallelsandbox/feedback に、モード 0600 で 7 日間保存されます（PSBX_FEEDBACK_DIR で変更できます）。 レポートが別の会話に渡されること、二重にキューに入れられること、ホストプロセスの終了後にフックが何かを取得することはありません。レビューを登録できない場合（サーバーでは、レビューを開いた会話だけがそのフィードバックをルーティングできます）、その旨は 1 回だけログに記録され、保留されます。他のレビューのフィードバックが遅れることはなく、一時的なサーバーエラーやネットワークエラーは、バックオフしながら再試行されます。別の会話から、またはアダプターの再起動後に既存の reviewId を指定して sandbox_review を呼び出しても、そのレビューの元のルートが維持されます。アダプターがホストの codex プロセスを検出できない場合（たとえば Windows の場合）に限り、PSBX_CODEX_CLI を設定してください。 Codex で 30 分間待機するには、この MCP サーバーの tool_timeout_sec = 1920 と、サーバーのアダプター環境で PSBX_TOOL_TIMEOUT_SEC = "1920" を設定し、アダプター 0.4.2 以降を使ってサーバーを再起動または再接続してください。他のホストでは、同等の絶対ツールタイムアウトが必要です。両方の設定が必要です。waitSec またはアダプター設定だけを増やしても、ホストの期限は延長されません。既存のキャッシュ済みアダプタープロセスには、再起動するまで古い設定が適用されます。このパッケージはクライアント設定を自動的に変更しません。

sandbox_report は id と reportId を使ってアカウント所有のレポートを読み込みます。メディア URL、タイムスタンプ付きトランスクリプト、注釈付きフレームも含まれます。先行するツールがすでに返したレポートを再生でき、ボックスを占有したり、他の保留中メッセージを消費したりすることはありません。レポートとメディアは 7 日間利用できます。レシートが記録するのはツール結果全体の準備であり、AI が要求された変更を理解したり完了したりしたことではありません。

呼び出しの実行中、サーバーは接続上に 20 秒ごと（sandbox_takeover では 15 秒ごと）に「まだ実行中」の行を書き込みます。クライアントが進捗通知を要求している場合、アダプターはこれらを MCP の進捗通知として転送します。そのため、一定時間応答がないと呼び出しをキャンセルするクライアント（Claude Code は 30 分後にキャンセルします）も、長時間のビルドを待ち続けます。結果が届かないまま接続が終了した場合、または PSBX_ADAPTER_SILENCE_MS の間何も届かなかった場合、アダプターはタイムアウトを待たずにエラーを返します。再生安全なツール（sandbox_report、sandbox_list、sandbox_get、logs_* ツールなど）は、まず 1 回だけ再試行されます。それ以外の場合、エラーには呼び出しが実行中、またはボックス上ですでに完了している可能性があると表示されます。再実行する前に sandbox_status（steps[] に実行された内容が記載されています）を確認してください。sandbox_status は保留中の人間からのフィードバックを一度引き渡すことがあるため、結果を受信できなかった後に自動再試行はされません。レポートを復元するには、アプリから取得したレポート ID を指定して sandbox_report を使ってください。

トラブルシューティング

• クライアントがサーバーの起動中にタイムアウトし（60 秒後の MCP initialize）、アダプターのエラーが表示されません。 npx がまだパッケージをダウンロード中のため、アダプターは起動していません。~/.npm/_logs/ 内の最新ファイルを確認してください。registry.npmjs.org に対する ENETUNREACH（または ETIMEDOUT）は、通常、マシンが到達できない IPv6 アドレスを解決していることを意味します。クライアントの MCP 設定で、サーバーの env に "NODE_OPTIONS": "--dns-result-order=ipv4first" を追加するか、npm i -g parallelsandbox-mcp で一度インストールし、npx の代わりに parallelsandbox-mcp を実行してください。
• the result never came back (connection from this computer to ParallelSandbox (...) failed: fetch failed (ENOTFOUND ...))。 このコンピューターと ParallelSandbox の間のリンクが切断されました（DNS、プロキシ、VPN、Wi-Fi が原因です）。ボックス自体のネットワークの問題ではありません。括弧内のコードは Node が報告した原因です。お使いの環境へのボックスの接続は、sandbox_status の environment.connections[] に表示されます。

ソースと問題の報告

ソース：https://github.com/parallel-sandbox/parallelsandbox-mcp。バグは issue として報告するか、セッション内で sandbox_feedback ツールを使って報告してください。MIT ライセンスです。