ボリューム

ボリュームとは、サンドボックスが選択したパスにマウントするストレージです。サンドボックスでは 2 種類のボリュームをサポートしています。スクラッチボリューム は単一のサンドボックスに属し、サンドボックスとともに消滅します。登録済み Volume は組織が一度登録するボリュームで、その後任意の数のサンドボックスがマウントできます。このページは、コンテナーファイルシステムの容量を超えて書き込みを行うサンドボックスが必要な開発者、または複数のサンドボックスで同じデータセットを読み取りたい開発者向けです。終了時には、両方の種類のボリュームをアタッチし、登録済み Volume のライフサイクルを管理できるようになります。

認証方法を選択する

以下の例は、セクション内で CoreWeave Kubernetes Service (CKS) を指定している場合を除き、サーバーレスキャパシティ上で実行されます。サンドボックスを所有するアカウントの認証情報を選択してください。キーまたはトークンの取得方法については、認証情報の選択と取得を参照してください。使用する言語に対応した設定ファイルを、このページのスクリプトを実行する場所と同じディレクトリに保存してください。Python の例では sandbox_auth.py から AUTH をインポートします。TypeScript の例では sandbox-client.mts から client をインポートします。これらのファイルは認証情報そのものを保存せず、認証方法の選択のみを行います。Python の場合は、有効化した仮想環境を使用してください。TypeScript の場合は、まず npm install @coreweave/cwsandbox@1.0.0 でクライアントをインストールしてください。

Forge APIキー
CoreWeave API アクセストークン

SDK の wandb インテグレーションで Forge API キーを使用します。[WANDB-API-KEY] をご自身の APIキーに置き換えてください。

export WANDB_API_KEY="[WANDB-API-KEY]"

Python
TypeScript

uv pip install 'cwsandbox[wandb]>=1.14.2'

sandbox_auth.py

from cwsandbox import AuthStrategy

AUTH = AuthStrategy.WANDB

sandbox-client.mts

import { createSandboxClientFromEnv } from "@coreweave/cwsandbox/wandb";

export const client = createSandboxClientFromEnv();

CoreWeave 組織のトークンを使用します。[API-ACCESS-TOKEN] をご自身のトークンに置き換えてください。

export CWSANDBOX_API_KEY="[API-ACCESS-TOKEN]"

Python
TypeScript

uv pip install 'cwsandbox>=1.14.2'

sandbox_auth.py

from cwsandbox import AuthStrategy

AUTH = AuthStrategy.COREWEAVE_API_KEY

sandbox-client.mts

import { createSandboxClientFromEnv } from "@coreweave/cwsandbox/node";

export const client = createSandboxClientFromEnv();

CKS に配置する場合は、CoreWeave トークンを選択し、ランナーを有効化したうえで、サンドボックスの作成時または SandboxDefaults で placement_mode="cks" を設定します。TypeScript で CKS を選択するには、CoreWeave トークンを選択し、空でない runnerIds 配列を設定します。auth=AUTH を指定して Python のセッションを作成すると、そのセッションが所有するサンドボックスも認証されます。サンドボックスへの再接続、一覧表示、クリーンアップを行う際も、同じ認証情報を使用してください。

ボリュームタイプを選択する

	スクラッチボリューム	登録済み Volume
宣言元	サンドボックス作成時の `ScratchVolumeOptions`	`Volume.create()`、その後サンドボックス作成時の `RegisteredVolumeOptions`
有効期間	サンドボックスの	任意のサンドボックスとは独立
サンドボックス間での共有	いいえ	はい
バッキングストア	ローカルディスクまたはメモリ	クラスター内の既存の PersistentVolumeClaim (PVC)
サンドボックス削除後の存続	ファイルシステムスナップショットのみを通じて	はい

1 つの run 内の作業スペースにはスクラッチボリュームを使用します。サンドボックスを越えて存続するデータや、複数のサンドボックスが同時に読み取るデータ (共有データセットやモデルの重みなど) には登録済み Volume を使用します。

スクラッチボリューム

スクラッチボリュームはサンドボックスとともに作成され、サンドボックスとともに破棄されます。volumes リスト内で ScratchVolumeOptions を使用して宣言します。

Python
TypeScript

from sandbox_auth import AUTH
from cwsandbox import Sandbox, ScratchVolumeOptions

with Sandbox.run(
    container_image="ubuntu:22.04",
    volumes=[ScratchVolumeOptions(name="workspace", mount_path="/workspace", size="10Gi")],
    resources={"cpu": "1", "memory": "1Gi"},
    auth=AUTH,
) as sandbox:
    sandbox.exec(["sh", "-c", "echo hello > /workspace/data.txt"]).result()

TypeScript の例では、選択した認証情報の設定で作成したクライアントを使用します。

import { client } from "./sandbox-client.mts";

await client.withSandbox(
  (sandbox) => sandbox.commands.run(["sh", "-c", "echo hello > /workspace/data.txt"], { check: true }),
  {
    containerImage: "ubuntu:22.04",
    volumes: [{ name: "workspace", mountPath: "/workspace", size: "10Gi" }],
  },
);

TypeScript のスクラッチボリュームは name、mountPath、size、restoreFromSnapshotId を受け入れます。TypeScript クライアントは medium、sub_path、read_only、およびコンテナーごとのマウントの直接設定をサポートしていません。これらのオプションが必要な場合は、Python クライアントを使用してください。

ScratchVolumeOptions は以下のフィールドを受け入れます：

Field	説明
`name`	サンドボックス内のボリューム名。マウントとスナップショットはこの名を参照します。必須。
`mount_path`	プライマリコンテナーにマウントする絶対パス。マウントせずにボリュームを宣言する場合は省略します。
`size`	ボリュームサイズ (例: `"10Gi"`) 。プラットフォームのデフォルトを使用する場合は省略します。
`medium`	バッキングストア: `StorageMedium.DISK` (デフォルト) または `StorageMedium.MEMORY`。
`sub_path`	ルートではなくボリューム内の相対パスをマウントします。
`read_only`	ボリュームを読み取り専用でマウントします。デフォルトは `False` です。
`restore_from_snapshot_id`	作成時にファイルシステムスナップショットをボリュームにリストアします。

ストレージ媒体を選択する

StorageMedium.DISK はボリュームをローカルディスクでバックアップします。StorageMedium.MEMORY は tmpfs でバックアップします。これは高速ですが、マウントするコンテナーのメモリリクエストとポリシーのメモリ上限にカウントされます。無制限の RAM バックアップボリュームはノードを枯渇させる可能性があるため、MEMORY ボリュームは size を宣言する必要があります。絶対量として、またはサンドボックスの解決済みメモリリクエストの整数パーセンテージ (例: "50%") として指定できます。パーセンテージ形式は MEMORY の場合のみ有効です。DISK ボリュームは絶対サイズを使用する必要があります。

from sandbox_auth import AUTH
from cwsandbox import Sandbox, ScratchVolumeOptions, StorageMedium

with Sandbox.run(
    container_image="ubuntu:22.04",
    volumes=[
        ScratchVolumeOptions(
            name="fast-cache",
            mount_path="/cache",
            size="50%",
            medium=StorageMedium.MEMORY,
        )
    ],
    resources={"cpu": "1", "memory": "1Gi"},
    auth=AUTH,
) as sandbox:
    sandbox.exec(["sh", "-c", "df -h /cache"]).result()

複数のコンテナーにスクラッチボリュームをマウントする

mount_path は、ボリュームをプライマリコンテナーにマウントするための便利な機能です。マルチコンテナーのサンドボックスでは、mount_path を省略し、代わりに各コンテナーでマウントを宣言してください。これにより、複数のコンテナーが同じボリュームにアクセスできるようになります。

from sandbox_auth import AUTH
from cwsandbox import Container, Sandbox, ScratchVolumeOptions, VolumeMount

with Sandbox.run(
    volumes=[ScratchVolumeOptions(name="shared", size="5Gi")],
    containers=[
        Container(
            name="app",
            image="ubuntu:22.04",
            primary=True,
            volume_mounts=[VolumeMount(volume="shared", mount_path="/data")],
            resources={"cpu": "1", "memory": "1Gi"},
        ),
        Container(
            name="sidecar",
            image="ubuntu:22.04",
            volume_mounts=[VolumeMount(volume="shared", mount_path="/data", read_only=True)],
            resources={"cpu": "1", "memory": "1Gi"},
        ),
    ],
    auth=AUTH,
) as sandbox:
    sandbox.exec(["sh", "-c", "echo shared > /data/note.txt"]).result()

登録済みボリューム

このガイドで扱う PVC-backed の登録済みボリュームを使用するには、CoreWeave API アクセストークンと、組織で登録済みボリュームが有効になっていることが必要です。認証方法を選択するの Forge API キー タブの内容は、スクラッチボリュームに適用されます。以下の例では、CKS クラスター内の PVC と、CWSANDBOX_API_KEY に設定した CoreWeave API アクセストークンを使用します。PVC-backed ボリュームを登録またはマウントする前に、独自のコンピュートを使用するの手順を完了してください。登録済みボリュームは、いずれかのクラスターに既に存在する PersistentVolumeClaim (PVC) を参照します。登録すると、サンドボックスにクラスター自体へのアクセス権を付与せずに、そのクレームをマウントできるようになります。ボリュームはメタデータ上の参照です。CoreWeave がデータをコピーすることはなく、ボリュームを削除してもクレームには影響しません。どのマウントも同じクレームを直接参照するため、あるサンドボックスから書き込んだ内容は、それをマウントしている他のすべてのサンドボックスから確認できます。 TypeScript クライアントには、ボリュームの登録や管理を行う API はなく、create() や run() で登録済みボリュームのマウントオプションを指定することもできません。これらの操作には Python クライアントを使用してください。 TypeScript クライアントのバージョン 1.0.0 では、runFromTemplate() を使用して、サンドボックステンプレートから登録済みボリュームとそのマウントを継承できます。テンプレートのコンテナーとマウントをそのまま使用するには、containerImage を省略します。containerImage を設定すると、コンテナーが置き換えられ、それらのマウントも破棄されます。マウントのない登録済みボリュームが残る場合、リクエストは拒否されます。

Volume を登録

Volume の登録、更新、削除には Sandbox Admin が必要です。Sandbox User は、登録済み Volume の一覧表示、読み取り、検証、マウントを実行できます。Sandbox Admin には Sandbox User の権限が含まれます。Sandbox ロールを参照してください。 Volume.create() は、Volume を VALIDATING 状態で即座に返します。その後、コントロールプレーンがクレームが存在し、使用可能であることを確認します。マウントする前に wait_until_ready() でポーリングしてください。

from cwsandbox import AuthStrategy, PvcVolumeSource, Volume

volume = Volume.create(
    "team-data",
    auth=AuthStrategy.COREWEAVE_API_KEY,
    pvc=PvcVolumeSource(
        runner_id="[RUNNER-ID]",
        namespace="[NAMESPACE]",
        claim_name="[PVC-NAME]",
    ),
    description="Shared training data",
).result()

volume.wait_until_ready(timeout=120).result()
print(volume.state, volume.capacity, volume.access_modes)

Volume ID はご自身で選択します。組織内で一意である必要があり、作成後は不変です。

ソースと read_only フラグも作成後は不変です。description のみ後で変更できます。

PvcVolumeSource は以下のフィールドを取ります。

フィールド	説明
`runner_id`	クレームを保持するクラスターを持つランナーです。また、Volume をマウントするサンドボックスがスケジュールされる場所を固定します。必須。
`namespace`	クレームの Kubernetes namespace。必須。
`claim_name`	PersistentVolumeClaim の名前。必須。
`sub_path`	クレーム内のオプションパスで、Volume のルートとして扱います。

Volume.create() で read_only=True を設定すると、Volume 自体のプロパティとして読み取り専用になります。この設定は下限であり、デフォルトではありません。書き込み可能な Volume ではマウントを読み取り専用にできますが、読み取り専用の Volume に書き込むマウントはできません。

登録済み Volume をマウントする

ID で RegisteredVolumeOptions を使用して Volume をマウントします。開始時に Volume が READY でない場合、サンドボックスは CWSANDBOX_VOLUME_NOT_READY で失敗します。

from cwsandbox import AuthStrategy, RegisteredVolumeOptions, Sandbox

with Sandbox.run(
    auth=AuthStrategy.COREWEAVE_API_KEY,
    placement_mode="cks",
    container_image="ubuntu:22.04",
    volumes=[
        RegisteredVolumeOptions(
            name="data",
            volume_id="team-data",
            mount_path="/data",
            read_only=True,
        )
    ],
    resources={"cpu": "1", "memory": "1Gi"},
) as sandbox:
    listing = sandbox.exec(["ls", "/data"]).result()
    print(listing.stdout)
    print(sandbox.attached_volume_ids)

RegisteredVolumeOptions には name、volume_id、および / 以外の絶対 mount_path が必要です。また、sub_path を受け入れ、登録時に設定された sub_path と組み合わせることができ、read_only も指定できます。サンドボックスは、マウントした Volumes を attached_volume_ids に反映します。

ローカリティと配置

Volume の locality は配置を制約するかどうかを report します:

cluster_local: Volume は 1 つのクラスターに存在するため、それをマウントするサンドボックスはそのクラスターのランナーにスケジュールされます。PVC-backed の Volume は cluster-local です。
global: Volume は任意のクラスターから到達可能で、配置を制約しません。

1 つのサンドボックスで異なるクラスターからの 2 つの cluster-local Volume をマウントすることは不可能であり、開始は CWSANDBOX_VOLUME_PLACEMENT_CONFLICT で失敗します。

登録済み Volume の管理

組織内の Volume を一覧表示、検査、更新、登録解除するには、以下のオペレーションを使用します。

from cwsandbox import AuthStrategy, Volume, VolumeState

# 組織の Volume をリストし、必要に応じてフィルターを適用します。
volumes = Volume.list(auth=AuthStrategy.COREWEAVE_API_KEY, states=[VolumeState.READY]).result()

# 1 つの Volume を取得します。
volume = Volume.get("team-data", auth=AuthStrategy.COREWEAVE_API_KEY).result()
print(volume.state, volume.attached_sandbox_count)

# 説明を更新します。これは唯一の変更可能なフィールドです。
volume.update(description="Shared training data, 2026 refresh").result()

# 必要に応じて、基盤となるクレームを再確認します。
volume.validate().result()

# Volume を登録解除します。バックの PVC は変更されません。
volume.delete(allow_missing=True).result()

Volume.list() は自動的にページネーションを行い、states と runner_ids のフィルターを受け入れます。delete() は allow_missing=True を受け入れ、これによりすでに削除された Volume の削除が成功し、例外を送出する代わりに成功します。非ターミナル状態のサンドボックスがまだマウントしている Volume を削除しようとすると CWSANDBOX_VOLUME_IN_USE で失敗し、Python クライアントはこれを VolumeInUseError として送出します。まず関連付けたサンドボックスを停止してください。

Volume の状態

登録済み Volume は、そのライフサイクルを通じて次の状態に遷移します。

状態	意味
`VALIDATING`	Volume が受け付けられ、コントロールプレーンが基盤となるクレームを確認しています。
`READY`	検証が成功しました。Volume をマウントできます。
`ERROR`	検証が失敗しました。原因は `state_reason` で確認してください。
`DELETING`	Volume の登録解除が進行中で、マウントできなくなっています。

wait_until_ready() は READY になるまで繰り返し確認します。Volume が ERROR または DELETING に達した場合は VolumeError、先にタイムアウトした場合は VolumeWaitTimeoutError が送出されます。

失敗の理由

この表を使用して、サンドボックスとVolumeの操作が返す可能性のある失敗の理由を解釈してください。

理由	意味	対処方法
`CWSANDBOX_VOLUME_NOT_FOUND`	そのIDのVolumeが組織に存在しません。	IDと組織を確認してください。
`CWSANDBOX_VOLUME_NOT_READY`	サンドボックスの開始で参照されたVolumeが`READY`ではありません。	Volumeが`READY`になるまでポーリングし、その後開始を再試行してください。
`CWSANDBOX_VOLUME_IN_USE`	サンドボックスがまだ関連付けられているため、削除がブロックされました。	関連付けられているサンドボックスを停止し、その後Volumeを削除してください。
`CWSANDBOX_VOLUME_BACKEND_NOT_FOUND`	バッキングクレームが存在しないか、読み取り不能です。	クレームが namespace にまだ存在することを確認し、`validate()`を呼び出してください。
`CWSANDBOX_VOLUME_PLACEMENT_CONFLICT`	関連付けられたVolumeが互換性のないランナーを固定しています。	同じクラスター内にあるVolumeをマウントしてください。
`CWSANDBOX_VOLUME_QUOTA_EXCEEDED`	組織がVolumeの上限に達しました。	未使用のVolumeを削除するか、クォータの引き上げをリクエストしてください。

サンドボックスの関連機能の詳細については、以下のリソースを参照してください：

ファイルシステムスナップショット: サンドボックスのファイルシステムを永続化および復元します。
Grant sandboxes access to AI Object Storage: サンドボックス内からバケットの読み書きを行います。
Sandbox configuration: その他のサンドボックス作成オプション
Distributed File Storage: 登録済み Volume が指す PersistentVolumeClaims を作成します。

サンドボックス

サンドボックスを使用する

サンドボックスの管理

リファレンス

認証方法を選択する

ボリュームタイプを選択する

スクラッチボリューム

ストレージ媒体を選択する

複数のコンテナーにスクラッチボリュームをマウントする

登録済みボリューム

Volume を登録

登録済み Volume をマウントする

ローカリティと配置

登録済み Volume の管理

Volume の状態

失敗の理由

​認証方法を選択する

​ボリュームタイプを選択する

​スクラッチボリューム

​ストレージ媒体を選択する

​複数のコンテナーにスクラッチボリュームをマウントする

​登録済み ボリューム

​Volume を登録

​登録済み Volume をマウントする

​ローカリティと配置

​登録済み Volume の管理

​Volume の状態

​失敗の理由

​関連リソース

認証方法を選択する

ボリュームタイプを選択する

スクラッチボリューム

ストレージ媒体を選択する

複数のコンテナーにスクラッチボリュームをマウントする

登録済みボリューム

Volume を登録

登録済み Volume をマウントする

ローカリティと配置

登録済み Volume の管理

Volume の状態

失敗の理由

関連リソース