Volumes - CoreWeave Docs

The examples on this page omit auth. To authenticate with your W&B API key, install cwsandbox[wandb] and pass auth=AuthStrategy.WANDB to Sandbox.run(), Sandbox(), or Sandbox.session(). See Get started.

A volume is storage that a sandbox mounts at a path you choose. Scratch volumes belong to a single sandbox and disappear with it. This page is for developers who need a sandbox to write more than its container filesystem holds. By the end, you can attach a scratch volume.

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()

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

Sandbox configuration: the rest of the sandbox create options

​Scratch volumes

​Choose a storage medium

​Mount a scratch volume on several containers

​Related resources

Scratch volumes

Choose a storage medium

Mount a scratch volume on several containers

Related resources