Volumes - CoreWeave Docs

A volume is storage that a sandbox mounts at a path you choose. CoreWeave Sandbox offers two kinds. Scratch volumes belong to a single sandbox and disappear with it. Registered Volumes are volumes your organization registers once, and any number of sandboxes can then mount them. This page is for developers who need a sandbox to write more than its container filesystem holds, or who want several sandboxes to read the same dataset. By the end, you can attach both kinds of volume and manage the registered Volume lifecycle.

CoreWeave sandboxes are in public preview. For access, contact your CoreWeave account team, CoreWeave Support, or email support@coreweave.com.

Choose a volume type

	Scratch volume	Registered Volume
Declared by	`ScratchVolumeOptions` at sandbox create	`Volume.create()`, then `RegisteredVolumeOptions` at sandbox create
Lifetime	The sandbox’s	Independent of any sandbox
Shared between sandboxes	No	Yes
Backing store	Local disk or memory	An existing PersistentVolumeClaim (PVC) in your cluster
Survives sandbox deletion	Only through a file system snapshot	Yes

Use a scratch volume for working space inside one run. Use a registered Volume for data that outlives a sandbox or that several sandboxes read at once, such as a shared dataset or model weights.

Scratch volumes

A scratch volume is created with the sandbox and destroyed with it. Declare one with ScratchVolumeOptions in the volumes list.

from cwsandbox import Sandbox, ScratchVolumeOptions

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

ScratchVolumeOptions accepts the following fields:

Field	Description
`name`	Volume name within the sandbox. Mounts and snapshots reference this name. Required.
`mount_path`	Absolute path to mount on the primary container. Omit it to declare the volume without mounting it.
`size`	Volume size, such as `"10Gi"`. Omit it to use the platform default.
`medium`	Backing store: `StorageMedium.DISK` (the default) or `StorageMedium.MEMORY`.
`sub_path`	Relative path inside the volume to mount instead of its root.
`read_only`	Mount the volume read-only. Defaults to `False`.
`restore_from_snapshot_id`	Restore a file system snapshot into the volume at create time.

Choose a storage medium

StorageMedium.DISK backs the volume with local disk. StorageMedium.MEMORY backs it with tmpfs, which is faster but counts against the mounting container’s memory request and against the policy’s memory ceiling. Because an unbounded RAM-backed volume could exhaust the node, a MEMORY volume must declare a size. It may do so as an absolute quantity, or as an integer percentage of the sandbox’s resolved memory request, such as "50%". The percentage form is valid only for MEMORY. A DISK volume must use an absolute size.

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,
        )
    ],
) as sandbox:
    sandbox.exec(["sh", "-c", "df -h /cache"]).result()

Mount a scratch volume on several containers

mount_path is a convenience that mounts the volume on the primary container. In a multi-container sandbox, omit mount_path and declare the mounts on each container instead, so that more than one container can reach the same volume.

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")],
        ),
        Container(
            name="sidecar",
            image="ubuntu:22.04",
            volume_mounts=[VolumeMount(volume="shared", mount_path="/data", read_only=True)],
        ),
    ],
) as sandbox:
    sandbox.exec(["sh", "-c", "echo shared > /data/note.txt"]).result()

Registered Volumes

A registered Volume points at a PersistentVolumeClaim (PVC) that already exists in one of your clusters. Registering it makes the claim mountable by sandboxes without granting them access to the cluster itself. The Volume is a metadata pointer: CoreWeave never copies the data, and deleting the Volume never touches the claim. Every attach is a live view of the same claim, so a write from one sandbox is visible to every other sandbox mounting it.

Register a Volume

Volume.create() returns immediately with the Volume in the VALIDATING state, then the control plane checks that the claim exists and is usable. Poll with wait_until_ready() before you mount it.

from cwsandbox import PvcVolumeSource, Volume

volume = Volume.create(
    "team-data",
    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)

You choose the volume ID yourself. It must be unique within your organization, and it is immutable after creation.

The source and the read_only flag are also immutable after creation. Only description can change later.

PvcVolumeSource takes these fields:

Field	Description
`runner_id`	The runner whose cluster holds the claim. This also pins where sandboxes mounting the Volume are scheduled. Required.
`namespace`	Kubernetes namespace of the claim. Required.
`claim_name`	Name of the PersistentVolumeClaim. Required.
`sub_path`	Optional path inside the claim to treat as the Volume’s root.

Set read_only=True on Volume.create() to make read-only a property of the Volume itself. That setting is a floor, not a default: a mount can be read-only on a writable Volume, but no mount can write to a read-only Volume.

Mount a registered Volume

Mount the Volume by ID with RegisteredVolumeOptions. The Volume must be READY at start, or the sandbox fails with CWSANDBOX_VOLUME_NOT_READY.

from cwsandbox import RegisteredVolumeOptions, Sandbox

with Sandbox.run(
    container_image="ubuntu:22.04",
    volumes=[
        RegisteredVolumeOptions(
            name="data",
            volume_id="team-data",
            mount_path="/data",
            read_only=True,
        )
    ],
) as sandbox:
    listing = sandbox.exec(["ls", "/data"]).result()
    print(listing.stdout)
    print(sandbox.attached_volume_ids)

RegisteredVolumeOptions requires name, volume_id, and an absolute mount_path other than /. It also accepts sub_path, which combines with any sub_path set at registration, and read_only. A sandbox echoes the Volumes it mounted in attached_volume_ids.

Locality and placement

A Volume’s locality reports whether it constrains placement:

cluster_local: the Volume lives in one cluster, so sandboxes mounting it are scheduled onto that cluster’s runner. PVC-backed Volumes are cluster-local.
global: the Volume is reachable from any cluster and does not constrain placement.

Mounting two cluster-local Volumes from different clusters in one sandbox is unsatisfiable, and the start fails with CWSANDBOX_VOLUME_PLACEMENT_CONFLICT.

Manage registered Volumes

Use the following operations to list, inspect, update, and deregister the Volumes in your organization.

from cwsandbox import Volume, VolumeState

# List the organization's Volumes, optionally filtered.
volumes = Volume.list(states=[VolumeState.READY]).result()

# Fetch one Volume.
volume = Volume.get("team-data").result()
print(volume.state, volume.attached_sandbox_count)

# Update the description. It is the only mutable field.
volume.update(description="Shared training data, 2026 refresh").result()

# Re-check the backing claim on demand.
volume.validate().result()

# Deregister the Volume. The backing PVC is untouched.
volume.delete(allow_missing=True).result()

Volume.list() paginates automatically and accepts states and runner_ids filters. delete() accepts allow_missing=True, which makes deleting an already-deleted Volume succeed instead of raising. Deleting a Volume that non-terminal sandboxes still mount fails with CWSANDBOX_VOLUME_IN_USE, which the Python client raises as VolumeInUseError. Stop the attached sandboxes first.

Volume states

A registered Volume moves through the following states over its lifecycle:

State	Meaning
`VALIDATING`	The Volume was accepted and the control plane is checking the backing claim.
`READY`	Validation succeeded. The Volume can be mounted.
`ERROR`	Validation failed. Read `state_reason` for the cause.
`DELETING`	The Volume is being deregistered and can no longer be mounted.

wait_until_ready() polls until READY. It raises VolumeError if the Volume reaches ERROR or DELETING, and VolumeWaitTimeoutError if the timeout elapses first.

Failure reasons

Use this table to interpret the failure reasons that sandbox and Volume operations can return.

Reason	What it means	What to do
`CWSANDBOX_VOLUME_NOT_FOUND`	No Volume with that ID exists in your organization.	Check the ID and the organization.
`CWSANDBOX_VOLUME_NOT_READY`	A sandbox start referenced a Volume that is not `READY`.	Poll until the Volume is `READY`, then retry the start.
`CWSANDBOX_VOLUME_IN_USE`	A delete was blocked because sandboxes are still attached.	Stop the attached sandboxes, then delete the Volume.
`CWSANDBOX_VOLUME_BACKEND_NOT_FOUND`	The backing claim is missing or no longer readable.	Confirm the claim still exists in the namespace, then call `validate()`.
`CWSANDBOX_VOLUME_PLACEMENT_CONFLICT`	The attached Volumes pin incompatible runners.	Mount Volumes that live in the same cluster.
`CWSANDBOX_VOLUME_QUOTA_EXCEEDED`	The organization hit its Volume limit.	Delete unused Volumes, or request a quota increase.

For more on related sandbox features, see the following resources:

File system snapshots: persist and restore a sandbox’s filesystem.
Grant sandboxes access to AI Object Storage: read and write buckets from inside a sandbox.
Sandbox configuration: the rest of the sandbox create options
Distributed File Storage: create the PersistentVolumeClaims that registered Volumes point at.

​Choose a volume type

​Scratch volumes

​Choose a storage medium

​Mount a scratch volume on several containers

​Registered Volumes

​Register a Volume

​Mount a registered Volume

​Locality and placement

​Manage registered Volumes

​Volume states

​Failure reasons

​Related resources

Choose a volume type

Scratch volumes

Choose a storage medium

Mount a scratch volume on several containers

Registered Volumes

Register a Volume

Mount a registered Volume

Locality and placement

Manage registered Volumes

Volume states

Failure reasons

Related resources