ParallelSandboxアプリを開く

エンジニア向け Q&A

AI に作業を任せる前に、ParallelSandbox の仕組み、コードとデータの行き先、何が残るのかを確認するためのページです。人が読むためのページで、AI は SKILL.md とツールリファレンスを読みます。

ParallelSandbox を操作するのは AI です。ボックスを開く、設定する、削除する、どれもあなたは AI に一言頼むだけで、AI が対応するツールや REST を呼びます。以下に出てくる sandbox_* ツールや /v1/... エンドポイントは、AI が実際に何をしているかを知るためのものです。

ParallelSandbox で何ができる？

  • あなたの AI（Claude Code、Codex、Cursor、Gemini CLI、または MCP に対応した任意のクライアント）が、作業ごとにボックスを開きます。Docker、git、Node、Go、Chromium と仮想ディスプレイを備えた、リモートの小さな Linux 仮想マシンです。
  • AI はボックスの中で変更したサービスを動かし、本物のブラウザや Android・iPhone シミュレーターでテストし、スクリーンショットと録画を撮って、アプリで試せるようあなたに渡します（「確認待ち」）。問題を丸で囲んで話して伝えると、そのフィードバックは元の会話に戻ります。
  • 作業ごとに 1 つのボックスで、互いに隔離されています。複数を同時に進めても、ポート、データベース、手元の環境を取り合いません。
  • ボックスの中に AI はいません。作業するのはあなた自身の AI で、MCP ツールを通じてボックスを操作します。ParallelSandbox 自身があなたのコードを AI モデルに渡すことはありません。

ボックスのスペックは？

x86_64 の Linux（Debian 12）です。サイズ 1 単位あたり 2 vCPU、メモリ 8 GB、ディスク 40 GB で、ボックスは 1、2、4、8 単位から選びます。Docker、git、Node、Go、Python、PHP、Chromium と仮想ディスプレイが入っていて、Java、Android、.NET、Rust、Flutter のツールチェーンは必要なときに追加します。

どこから始める？

  1. まず実際の流れを見る：サンプルリポジトリは公開リポジトリ 2 つで、手元で docker compose up すれば動きます。ボックスで動かす手順もすべて載っています。
  2. つなぐ：クイックスタートの一文を AI に貼り付けます。AI が skill をインストールし、OAuth であなたのアカウントにサインインします。キーを AI に渡す必要はありません。
  3. 最初の作業は小さく。たとえば「このリポジトリをボックスで動かして、ブラウザでトップページをテストし、レビューに回して」。

アーキテクチャは？

ParallelSandbox のアーキテクチャ：あなたのコンピューター、ParallelSandbox（AWS）、あなたのネットワーク

構成要素 場所 役割
AI クライアント あなたのコンピューター MCP ツールを呼ぶ：ボックスを開く、コマンドを実行する、スクリーンショットを撮る、引き渡す
ローカルアダプター parallelsandbox-mcp（任意） あなたのコンピューター ローカルのフォルダーをボックスに送る（sandbox_sync）か、ファイルを手元に取り戻す（sandbox_pull）ときだけ必要
コントロールプレーン AWS MCP と REST API、アカウント、シークレット、計量
ホストとボックス AWS 各ボックスは独立した小さな仮想マシンで、専用のディスクとネットワークを持ち、互いに隔離されています
URL の転送 AWS https://<id>-<key>.box.parallelsandbox.com のような URL をボックス内の Web サービスにつなぐ
ストレージとレジストリ AWS スクリーンショットと録画、取り出したファイル、ビルドキャッシュ、公開したイメージ
Android エミュレーター AWS sandbox_device で借りる Android 端末
iPhone シミュレーター 専用の Mac ホスト sandbox_device で借りる iPhone 端末
コネクタ（任意） あなたのネットワーク あなたが動かすコンテナ。ParallelSandbox へ外向きに接続し、列挙した dev のデータベースやサービスにボックスが届くようにする

1 つの作業は最初から最後までどう進む？

  1. 開く：AI が sandbox_start を呼び、ボックスの目的、動かすサービスと待ち受けポート、持ち込むシークレット、つなぐ環境を宣言します。ボックスはアカウントのデータを含まないクリーンなスナップショットから起動します。
  2. コードを入れる：AI がボックス内で git clone するか、sandbox_sync で手元の作業ツリーを ParallelSandbox の API 経由でボックスに送ります。
  3. 動かしてテスト：AI が sandbox_exec でビルド、起動、テストを行い、sandbox_shot でスクリーンショットと録画を撮ります。
  4. 引き渡す：AI が sandbox_review でボックスをあなたに渡します。アプリの「確認待ち」に表示され、ページやシミュレーターを実際に操作して、問題があれば丸で囲みます。
  5. 片付ける：確認が済んだら AI が sandbox_stop を呼び（またはアプリで「片付ける」）、ボックスのディスクも一緒に削除されます。残したいものはその前に commit、push するか手元に取り戻してください。

ボックスはいつまで残る？

  • 10 分操作がない → 凍結：クレジットは消費されず、メモリと /work は残り、次の呼び出しで数秒で再開します。
  • 最後に使ってから 24 時間 → 完全に停止し、ディスクは削除されます。もっと残したいときは AI に「このボックスを 3 日残して」と頼めば、ボックスを開くときに設定します。最長 7 日です。
  • 停止したボックスの URL は使えなくなり、/work も戻りません。新しいボックスには新しい URL が付きます。

フロントエンドとバックエンドが複数のリポジトリに分かれている場合は？

1 つのボックスで複数のリポジトリを動かせる？

できます。ボックスは 1 台の Linux なので、AI は /work の下に複数のリポジトリを clone し、docker compose やそれぞれのコマンドでまとめて動かせます。サービス同士は名前で見つけます（たとえば api:3000）。手元で compose を使うのと同じです。

それともサービスごとに 1 つのボックス？

それもできます。サービスが別々のボックスにあるときは、リンクでボックス B の名前をボックス A のポートに向けます。B のプログラムはいつものホスト名で呼べばよく、設定の変更は要りません。2 人（または 2 つの AI 会話）がそれぞれ 1 つのサービスを変更し、つないでテストしたいときに向いています。

2 人がそれぞれ開いたボックスをつなげる？

同じアカウントならつなげます。チームでは 1 つの ParallelSandbox アカウントを共有し（チームのセットアップを参照）、ボックス、環境、シークレット、公開したバージョン、クレジットはそのアカウントにあります。リンクは同じアカウントのボックス同士だけです。今のところアカウントにメンバーや役割の区別はありません。

今回変更していないサービスは？

どこで動いているかで決まります：

状況 方法
あなたの dev や staging（AWS、Kubernetes、オフィス）で動いている 環境を作り、あなたのネットワークでコネクタを動かして、ボックスに届けてよい host:port を列挙します。ボックスはいつものホスト名で dev 上のものにつながります。データベース、Redis、内部サービスも同じです。
URL のある HTTP サービス ボックスを開くときに externalBaseUrl を指定すると、ボックス内でそのサービス名への HTTP がその URL に転送されます。
誰かがビルドしてバージョンとして公開済み ボックスを開くときに services でそのバージョンを宣言すると、ボックスはイメージを pull して動かします。ビルドし直す必要はありません（公開済みバージョンを動かす）。

環境は AI が REST で設定し、画面はありません。あなたがするのは、自分のネットワークでコネクタを動かすこと（docker run 1 行）だけです。環境のアドレスや設定を変えると、その後に開いたボックスにだけ反映されます。

自分の手元にないサービス（別チーム、サードパーティ）は？

あなたのネットワークから届くものなら、ボックスからも届きます。届く場所でコネクタを動かし、その host:port を列挙してください。既知の IP しか受け付けない外部サービスも同じように列挙すれば、通信はあなたのネットワークからあなたのパブリック IP で出ていきます。あなた自身が届かないサービスには、ボックスも届きません。

dev 上のサービスから、ボックス内で変更した方を呼べる？

社内ネットワーク経由では呼べません。コネクタはボックスから外へつなぐだけで、あなたのネットワークからコネクタを通ってボックスに入る手段はありません。dev 上で内部のホスト名を呼んでいるサービスは、そのまま dev 上のものを呼びます。

一方、ボックスの公開 URL（https://<id>-<key>.box.parallelsandbox.com）はインターネットにつながるものなら何からでも開けるので、webhook のようなコールバックの宛先にできます。

「呼び出し側 → 変更したサービス」をテストするなら、呼び出し側も同じボックスに入れるか、リンクでつないだ別のボックスに入れるのがいちばん簡単です。

コードとデータ

ボックスには必ずリポジトリ全体が入る？

とは限りません。AI がどう入れるかによります：

  • git clone：ボックスが自分で取得します。プライベートリポジトリには、あらかじめトークンをシークレットとして保存し（たとえば GITHUB_TOKEN）、AI がボックスを開くときに指定します。
  • sandbox_sync：あなたのコンピューターから送ります。git が追跡しているファイルと、.gitignore で除外されていない新しいファイルだけです。1 つの commit のツリーだけを送ることもできます。無視されたファイル（多くのプロジェクトの .env や node_modules）は、既定では送られません。

送りたくないファイルは .gitignore に入れるか、特定の commit だけを送るよう AI に頼んでください。

コードとデータはどこに送られる？

  • ボックス、コントロールプレーン、ストレージ、レジストリ、ログサービスは、すべて AWS 上にあります。
  • iPhone シミュレーターを使うと、ビルドしたアプリが専用の Mac ホストに送られ、そこでインストール・実行されます。
  • ボックスは、あなたのプログラムがもともと接続する先に接続します。npm、GitHub、あなたの dev、外部の API などです。
  • ボックスから dev への通信は、ParallelSandbox を通ってあなたのコネクタに届きます。コネクタと ParallelSandbox の間は TLS で、あなたのサービス自身の TLS（データベースの SSL など）は、ボックスからサービスまでの途中で解かれません。
  • ParallelSandbox 自身があなたのコードを AI モデルに渡すことはありません。あなたの AI が見るもの（コマンドの出力、スクリーンショット）は、あなたの AI クライアントを通じて利用中の AI プロバイダーに届きます。手元で使うときと同じです。
  • アプリの音声入力はリアルタイムでテキストに変換されます。音声もテキストも保存しません。

詳しくはプライバシーポリシーをご覧ください。

ボックスを止めたら、ディスクは本当に消える？

消えます：

  • ボックスを止めると、その仮想マシンが停止し、ディスクファイルがすぐに削除されます。ホストのディスクは暗号化されていて、ホストが片付けられるとディスクごと削除されます。
  • 凍結中のボックスのメモリと /work は、暗号化されたストレージに一時保存されることがあります。ボックスが再開するか止まると削除されます。保険として最長 10 日の上限もありますが、通常の使い方ではそこまで残りません。
  • 正確に言うと、これは「暗号化されたディスク上のファイル削除」で、全ブロックの上書きではありません。

何が残り、どのくらい保存され、削除できる？

削除したいものは AI に頼んでください（たとえば「このボックスのスクリーンショットを消して」「ビルドキャッシュを消して」）。AI が表の REST を呼びます。

データ 場所 保存期間 削除方法
ボックスの /work（コード、コンテナ、データベース） ホスト上のボックスのディスク ボックス停止時に削除。最後に使ってから 24 時間（設定すれば最長 7 日）で自動停止 sandbox_stop、またはアプリの「片付ける」
sandbox_get・sandbox_pull で取り出したファイル AWS 上のストレージ 約 1 日 自動で削除
スクリーンショットと録画 AWS 上のストレージ 7 日間 DELETE /v1/boxes/{id}/media。ボックスごと
凍結時のポスター、レビューカードの画像 AWS 上のストレージ ボックスごとに最新の 1 枚のみ 同上
ビルドキャッシュ（sandbox_build） AWS 上のストレージ アカウントごとに最大 20 GB、古いものから削除 DELETE /v1/build-cache。アカウント全体をまとめて
バージョンとして公開したイメージ アカウントのイメージレジストリ 期限なし DELETE /v1/versions/{id}。同じイメージを使うバージョンがほかになければイメージも削除
ログとソースマップ ログサービス ログプロジェクトを削除するまで DELETE /v1/projects/{id}（log.parallelsandbox.com）
シークレット コントロールプレーンのデータベース、暗号化 削除するまで アプリの設定のシークレット、または DELETE /v1/secrets/{name}
環境のサービス設定（環境変数） コントロールプレーンのデータベース、暗号化 削除するまで DELETE /v1/environments/{env}/services/{name}
アプリ内のメッセージとアクティビティ記録 コントロールプレーンのデータベース 7 日間 自動で削除

アカウントを削除すると、実行中のボックスは停止し、上記はすべて遅くとも 30 日以内に削除されます。REST の詳細は REST をご覧ください。

ボックスの URL は誰が開ける？ ログインや IP 制限は追加できる？

  • ボックスの URL は https://<id>-<key>.box.parallelsandbox.com の形です。key はランダムで、違っていれば存在しないボックスと同じく 404 になります。完全な URL を知っている人は開けるので、共有リンクとして扱ってください。
  • 開ける場所を制限するには、アカウントに IP 許可リストを設定します。AI に「ボックスの URL は会社の 203.0.113.0/24 からだけ開けるようにして」と頼めば、PUT /v1/box-access を呼びます。約 3 秒で、アカウントのすべてのボックス URL がリスト内の IP からのアクセスだけを受け付け、それ以外は 403 になり、凍結したボックスも起こしません。リストはアカウントに 1 つ、最大 50 件で、今は IPv4 だけを照合します。オフにするには空のリストを頼んでください。
  • 社内 VPN やオフィスの固定 IP があるチーム向けです。同僚がレビューの URL を開くときや、スマートフォンのモバイル回線でテストするときも、リスト内の IP から（たとえば先に VPN につないで）アクセスしてください。
  • ログインは追加していません：レビュー用の URL は、ParallelSandbox のアカウントを持たない同僚にもそのまま試してもらえる必要があるためです。
  • 引き継ぎページとアプリは URL の key に頼りません。引き継ぎリンクはコントロールプレーンが発行する使い捨てで期限付きのトークンで、アプリはあなたのサインインを使います。

データベースとテストデータ

ボックスは毎回まっさらな環境？

はい。どのボックスも同じクリーンなスナップショットから起動し、ボックス内で動かしたデータベースはボックスが止まるまでしか残りません。同じボックスなら凍結中も保持されます（ボックスはいつまで残る？を参照）が、Kubernetes の PVC のようにボックスをまたいで共有する永続ディスクはありません。

サービスの環境変数（DATABASE_URL など）はどうやってボックスに入る？

環境の「サービス設定」として保存します。AWS ECS から取り込む（参照している SSM パラメータと Secrets Manager の値も一緒に）か、.env をアップロードします。その環境でボックスを開くと /work/.sbx/env/<サービス>.env ができ、変更したサービスはそれを使って dev と同じ設定で起動します。設定は暗号化して保存され、API が返すのは変数名だけです。設定を変えると、その後に開いたボックスにだけ反映されます。

dev のデータベースに直接つないでもいい？

いいです。環境＋コネクタに、前の質問のサービス設定を組み合わせます。注意点：変更したサービスを dev の設定で起動すると、その migration と書き込みは実際に dev のデータベースに入ります。

テストデータ一式を、毎回 migration や seed をせずに使い続けたい

そのデータベースをあなた自身のネットワーク（たとえば dev にあるテスト専用の Postgres）に置き、環境のコネクタ経由でボックスから接続してください。データも migration の状態もあなたの手元に残り、どのボックスも前回の続きから使えます。今のところ、ずっと残す方法はこれだけです。ParallelSandbox はボックス内のデータベースを保存しません。

毎回まっさらなデータベースから始めたい

ボックス内で psbx-testdb up <名前> を実行すると、新しい Postgres 16（--mysql なら MySQL 8.0）が起動し、DATABASE_URL が /work/.sbx/testdb/<名前>.env に書かれます。psbx-testdb reset <名前> でまた空に戻せ、psbx-testdb gotest ./... は Go のパッケージごとに専用のデータベースを用意します。ほかのデータベースはいつもの docker compose で起動してください。

ひとことで言うと、何が残って何が残らない？

  • 残らない：ボックスの中のすべて（コード、コンテナ、データベース、/work）。ボックスを止めると消えます。
  • 残る：あなたのネットワーク内のもの（コネクタ経由で接続するデータベース）、レジストリに公開したイメージ、ビルドキャッシュ、上の表にある保存ファイル。それぞれ期限があります。

シークレット

シークレットはどこに保存され、どうやってボックスに入る？

  • アカウント全体で 1 つのリストを、コントロールプレーンに暗号化して保存します。ボックスごとにあるわけではありません。
  • 既定では何もボックスに入りません。AI がボックスを開くときに必要なものを指定すると、ボックスが割り当てられた瞬間に渡され、すべてのコマンドの環境変数になります。ボックスが止まると一緒に消えます。
  • 保存した値は読み出せません。ツールの結果、sandbox_status、プラットフォームのログには名前しか出ません。
  • ボックスの中では環境変数です。コマンドが値を出力しても、あなたの AI に返る内容では **** に隠されます（8 文字以上の値）。環境がボックスに入れる、シークレットらしい dev の設定も同じです。ただしボックス内のファイル（プログラムが書くログなど）には本当の値が残るので、含まれていそうなファイルは AI に取り出させないでください。
  • ParallelSandbox 自身の API キーはシークレットに保存しないでください。ボックスには不要です。

設定画面はある？

あります。app.parallelsandbox.com の右上の歯車 → 設定 → Secrets で、追加、値の置き換え、削除ができます。名前と最終更新日時が一覧され、値は決して表示されません。アプリで入力した値は AI との会話を通らないので、AI プロバイダーにも届きません。トークンが手元にあるときはこちらをおすすめします。AI に REST で保存させることもできます（シークレット）。

プログラムが AWS（S3、SQS）の権限を必要とする場合は？

長期のキーは保存しないでください。環境に AWS ロールを指定すると、ボックスは OIDC で 1 時間で期限切れになる一時的な認証情報を受け取ります。GitHub Actions が AWS につなぐのと同じ方法です（ボックス内の AWS 権限）。ParallelSandbox は、あなたの AWS アカウントに入れる長期の権限を一切持ちません。

料金

  • ボックスは ready になった時点から分単位でクレジットを消費し、凍結中は消費しません。10 分操作がなければ凍結されるので、止め忘れても消費し続けることはありません。
  • 外向きの通信、ログ、保存ファイルは別に計量されます。環境とコネクタは無料です。料金はクレジットをご覧ください。

サンプルリポジトリ

リポジトリ 何を示すか
example-compose-app Node API と Go worker を compose でつなぎ、Playwright がボックスの画面上の本物のブラウザで e2e を実行。録画、スクリーンショット、引き渡しまで
example-web-with-logs Web ページにログ SDK を組み込み、エラーのスタックをソースマップで復元。write key はシークレットでボックスに持ち込む

各ツール呼び出しはサンプルリポジトリのページにあります。複数のサービス、AWS とオフィスの 2 つのネットワークに分かれた dev、コネクタ、別のボックスから変更したサービスを使う、という一通りの例はチームのセットアップにあります。