Skip to main content
TypeScript クライアントは、スナップショットのマウント、リストア、実行中のスナップショット、スナップショットの管理をサポートしていますが、停止時のスナップショット には対応していません。
ファイルシステムスナップショット (FSS) を使用すると、サンドボックスでローカルの作業ディレクトリに書き込み、そのディレクトリを不変のスナップショットとしてオブジェクトストレージに取得し、後で新しいサンドボックスにリストアできます。FSS を使用して、run 間でサンドボックスのファイルシステムを一時停止・再開したり、1 つのスナップショットから複数のサンドボックスにフォークし、それぞれを独立して変更したりできます。

認証を選択する

これらの例は、セクション内で CoreWeave Kubernetes Service (CKS) が指定されていない限り、サーバーレスキャパシティ上で実行されます。サンドボックスを所有するアカウントの認証情報を選択してください。キーまたはトークンの取得方法については、認証情報の選択と取得を参照してください。 使用する言語に対応する設定を、このページから実行するスクリプトと同じ場所に保存してください。Python の例では sandbox_auth.py から AUTH をインポートします。TypeScript の例では sandbox-client.mts から client をインポートします。これらのファイルは、認証情報そのものを保存せずに認証方法を選択します。Python の場合は、有効化した仮想環境を使用してください。TypeScript の場合は、まず npm install @coreweave/cwsandbox@1.0.0 でクライアントをインストールしてください。
SDK の wandb インテグレーションで Forge APIキーを使用します。[WANDB-API-KEY] をお使いの APIキーに置き換えてください。
sandbox_auth.py
CKS に配置する場合は、CoreWeave トークンを選択し、ランナーを有効化したうえで、サンドボックスの作成時または SandboxDefaults で placement_mode="cks" を設定してください。TypeScript で CKS を選択するには、CoreWeave トークンを選択し、空でない runnerIds 配列を設定します。auth=AUTH を指定して Python のセッションを作成すると、そのセッションが所有するサンドボックスも認証されます。サンドボックスへの再接続、一覧表示、クリーンアップの際も、同じ認証情報を使用してください。 HTTP API の例では、選択した認証情報タブの Bash コマンドを、リクエストを送信するのと同じシェルで実行してください。選択した認証ヘッダーは sandbox_headers 配列によって渡されます。HTTP による作成例では、サーバーレス配置を使用します。

仕組み

FSS を使用したサンドボックスは、選択したパスに書き込み可能なスクラッチファイルシステムをマウントします。ランナーはこのマウントを直接のオブジェクトストレージマウントではなく EmptyDir でバックアップします。スナップショットとリストアの操作では、そのローカルファイルシステムと組織スコープのオブジェクトストレージバケットの間で tarball をコピーします。 各スナップショットは、サーバーによって割り当てられた fileSystemSnapshotId で識別される FileSystemSnapshot リソースです。スナップショットには 3 つの特性があります。
  • 不変: スナップショットを作成すると 1 つのアーカイブが書き込まれます。スナップショットをリストアしてもソースのスナップショットは変更されないため、後でリストアしても常に元のバイトが表示されます。
  • 組織スコープ: ご自身の組織で作成されたスナップショットのみをリストアできます。同じ組織内でサンドボックスへのアクセス権を持つチームメンバーは、自身の認証情報を使用してあなたのスナップショットをリストアできます。他の組織のスナップショット ID は見つからないものとして扱われます。
  • 独立したライフサイクル: スナップショットはサンドボックスとは別に管理されます。サンドボックスを削除してもそのスナップショットは削除されず、スナップショットを削除してもそれから実行中のサンドボックスには影響しません。
デフォルトでは、CoreWeave がスナップショットを保持するオブジェクトストレージバケットをプロビジョニングおよび管理します。代わりにご自身で所有および管理するバケットにスナップショットを保存する場合は、CoreWeave アカウントとバケットの前提条件について Bring your own bucket を使用する を参照してください。

スナップショットマウントでサンドボックスを起動する

サンドボックスは、2 つのファイルシステムソースのいずれかから起動できます。新しく空のスクラッチファイルシステム、または既存のスナップショットのリストアです。

新規スクラッチ

新規スクラッチのファイルシステムは空の状態で開始され、後からスナップショットを作成できます。run の実行中に書き込み可能なローカル状態が必要なワークフローで使用してください。

スナップショットからリストアする

リストアでは、既存のスナップショットからファイルシステムを起動します。マウントのスナップショットソースにスナップショット ID を設定します。
スナップショットをリストアするには、ステータスが READY である必要があります。まだ CREATING のスナップショットをリストアすると失敗します。スナップショットのステータスと失敗を参照してください。

リストア時間を見込む

スナップショットのリストアでは、サンドボックスでアプリケーションを実行できるようになる前に、アーカイブのコピーと展開が行われます。大規模なモデルのスナップショットでは、リストアに数分かかることがあります。起動時間は次の要素に左右されます。
  • アーカイブのサイズ
  • ファイル数
  • 利用可能な CPU
  • ローカルストレージ
  • ネットワークのスループット
  • イメージの起動処理
リクエストしたマウントのキャパシティだけでは、リストア時間を予測できません。 起動の期限を決める際は、実際に使用するイメージ、スナップショット、リソースリクエストでコールドスタートの時間を計測してください。CREATING だけでは、スケジューリング待ちなのかファイルをリストア中なのかを区別できません。起動に時間がかかっているサンドボックスを削除する前に、status_reason を確認し、サポートへの問い合わせに備えて ID を控えておいてください。固定の期限を設ければ待機時間に上限を設けられますが、経過時間だけではリストアが失敗したと判断することはできません。

スナップショットを撮る

サンドボックスを停止したとき (on stop) と、実行中のサンドボックスから (mid-life) の2つの方法でスナップショットを取得することができます。

停止時のスナップショット

シャットダウン時にサンドボックスのファイルシステムを保持するには、停止時のスナップショットを有効にしてサンドボックスを停止します。一時停止と再開は、このパターンで実現します。スナップショットを取得してサンドボックスを停止し、後でそのスナップショットをリストアする新しいサンドボックスを起動します。

実行中のスナップショット

実行中のスナップショットは、サンドボックスを停止せずにその状態を取得します。サンドボックスは取得中も取得後も実行を継続します。取得処理では稼働中のファイルシステムをスキャンしますが、この処理はアトミックではありません。そのため、取得中に行われた書き込みは一貫した状態で取得されない可能性があります。一貫した状態が必要な場合は、取得中にアプリケーションの書き込みを一時停止するか、取得前にアプリケーションのチェックポイントを作成してください。
snapshot() はデフォルトでスナップショットが READY になるまで待機し、スナップショット ID を返します。

スナップショットをフォークする

同じスナップショットを複数のサンドボックスにリストアできます。各スナップショットは不変であるため、リストアされたサンドボックスは同一のバイト列から開始し、書き込みに伴ってそれぞれ異なる状態になります。
  1. 停止時のスナップショット、または実行中のスナップショットを使用して、READY 状態のスナップショットを作成します。
  2. fileSystemSnapshotId にそのスナップショットを設定して、サンドボックス A を起動します。
  3. 同じ fileSystemSnapshotId を使用して、サンドボックス B を起動します。
  4. サンドボックス A とサンドボックス B への書き込みは、それぞれ独立して状態を変化させます。ソースのスナップショットは変更されないため、後から同じ ID を使用してリストアしても、どちらのフォークへの書き込みも反映されず、元のスナップショットが使用されます。

スナップショットを管理する

スナップショットは、作成元のサンドボックスとは独立して一覧表示、取得、削除できます。
list_snapshots()、get_snapshot()、delete_snapshot() では、auth 引数で AuthHeaders オブジェクトを渡すこともできます。

スナップショットのステータスと失敗

スナップショットは非同期で作成されます。スナップショットリクエストが成功して fileSystemSnapshotId が返された時点でも、アーカイブの書き込みがまだ続いていることがあり、その後にスナップショットが失敗する場合があります。これは主に、waitForReady が false の場合や、ランナーのアーカイブ処理中にクライアント側でタイムアウトが発生した場合に起こります。 HTTP API で進捗を確認するには、スナップショットを取得して次のフィールドを確認します。
  • status: ライフサイクル状態。終了状態の値は FILE_SYSTEM_SNAPSHOT_STATUS_READY と FILE_SYSTEM_SNAPSHOT_STATUS_FAILED です。
  • statusReason: status が FILE_SYSTEM_SNAPSHOT_STATUS_FAILED の場合に設定され、失敗の理由を示します。
TypeScript では、スナップショットレコードから state と stateReason を読み取ります。対応する状態の値は "ready" と "failed" です。 スナップショットをリストアする前に、GetFileSystemSnapshot をポーリングして、スナップショットが準備完了になるまで待機してください。Python クライアントの snapshot() と get_snapshot() では、結果を待機する場合にこのポーリングが自動で行われます。TypeScript クライアントの snapshot() は、state が "ready" になるまで待機し、スナップショットが失敗した場合は例外をスローします。

失敗したスナップショットリクエストから復旧する

実行中のスナップショットの失敗から復旧する間は、ソースサンドボックスを実行したままにしてください。スナップショットのリモートプロシージャコール (RPC) が失敗しても、それ自体が原因でサンドボックスやそのマウントが削除されることはありません。ただし、Python のサンドボックスのコンテキストマネージャーを抜けたり、終了処理のコードを実行したりすると、サンドボックスが停止する可能性があります。準備完了のスナップショットに保存されていないデータは破棄されることがあります。こうしたクリーンアップが実行される前に、失敗に対処してください。 初回使用時のバケットのプロビジョニングでは、CWSANDBOX_FSS_BUCKET_PROVISIONING が返されることがあります。Python クライアントは、一時的なスナップショット RPC の失敗を、一定の予算の範囲内で再試行します。プロビジョニングがその予算を超えても完了しない場合は、ソースサンドボックスを保持したまま、バックオフを設けて再試行してください。結果が不明確な転送エラーの後に同じリクエストを再試行する場合は、サーバーが重複を排除できるように、明示的に指定した request_id を再利用してください。タイムアウト後にスナップショット ID を取得できている場合は、別のアーカイブをリクエストする前にそのスナップショットの状態を確認してください。FAILED になったスナップショットのデータを再度取得するには、新しいリクエストが必要です。 Python クライアント 1.19.6 では、一時的なスナップショットの失敗では SandboxUnavailableError が発生する場合があり、その他のスナップショットの失敗では SandboxSnapshotError が発生します。ビルドを保持する場合は、両方の例外を処理し、エラーの reason に基づいて再試行すべきかどうかを判断してください。クォータや設定に起因する失敗は、原因に対処せずに再試行しないでください。 次の表は、主な失敗理由とそれぞれの対処法を示しています。 ランナーがアーカイブのアップロードを完了したものの結果を記録できなかった場合、バケット内にオブジェクトが存在していても、スナップショットの行が FAILED になることがあります。この場合は、スナップショットの作成を再試行してください。 非同期で失敗した場合、プラットフォームは sandbox.file_system_snapshot.async_fail イベントも発行します。これにより、下流の通知システムは、元の呼び出しが返った後に失敗したスナップショットに対応できます。

制限事項

FSS バージョン 1 は、スナップショットを基盤とするローカルのスクラッチストレージを提供します。これは共有ファイルシステムではなく、複数の書き込み元による同時ライブマウントには対応していません。実行中のサンドボックスが互いのファイルシステムを読み書きすることはありません。サンドボックス間で状態を共有するには、スナップショットの作成とリストアを行う必要があります。

SDK のサンプル

サンドボックスを起動し、実行中のスナップショットを取得してフォークし、停止時にスナップショットを取得し、スナップショットを管理する、実行可能な完全な Python サンプルについては、cwsandbox-client リポジトリの file_system_snapshots.py を参照してください。TypeScript については、cwsandbox-js リポジトリの file-system-snapshots.ts に、実行中のスナップショットを取得してリストアし、スナップショットを管理するサンプルがあります。
最終更新日 2026年11月4日