Volumes

A volume is storage that a sandbox mounts at a path you choose. Sandboxes support 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.

Choose authentication

These examples run on serverless capacity unless a section specifies CoreWeave Kubernetes Service (CKS). Choose the credential for the account that owns your sandboxes. See Choose and get credentials to obtain a key or token. Save the configuration for your language beside the scripts you run from this page. Python examples import AUTH from sandbox_auth.py. TypeScript examples import client from sandbox-client.mts. These files select authentication without storing your credential. For Python, use an active virtual environment. For TypeScript, first install the client with npm install @coreweave/cwsandbox.

Forge API key
CoreWeave API access token

Use your Forge API key with the SDK’s wandb integration. Replace [WANDB-API-KEY] with your API key:

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

Use the token for your CoreWeave organization. Replace [API-ACCESS-TOKEN] with your 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();

For CKS placement, choose the CoreWeave token, enable a runner, and set placement_mode="cks" on sandbox creation or in SandboxDefaults. In TypeScript, choose the CoreWeave token and set a nonempty runnerIds array to select CKS. Creating a Python session with auth=AUTH also authenticates the sandboxes it owns. Keep the same credential when reconnecting, listing, or cleaning up sandboxes.

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.

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

The TypeScript example uses the client from your selected credential configuration.

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 scratch volumes accept name, mountPath, size, and restoreFromSnapshotId. The TypeScript client doesn’t support medium, sub_path, read_only, or per-container mounts. Use the Python client for those options.

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

Registered Volumes

The PVC-backed registered Volumes in this guide require a CoreWeave API access token and registered Volumes enabled for your organization. The Forge API key tab in Choose authentication applies to scratch volumes. The following examples use a PVC in your CKS cluster and a CoreWeave API access token in CWSANDBOX_API_KEY. Complete Use your own compute before registering or mounting a PVC-backed Volume. 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. The TypeScript client doesn’t support registered Volumes. Use the Python client to register, mount, and manage them.

Register a Volume

Registering, updating, or deleting a Volume requires Sandbox Admin. Sandbox User can list, read, validate, and mount registered Volumes. Sandbox Admin includes Sandbox User permissions. See Sandbox roles. 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 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)

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 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 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 AuthStrategy, Volume, VolumeState

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

# Fetch one Volume.
volume = Volume.get("team-data", auth=AuthStrategy.COREWEAVE_API_KEY).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.

Sandboxes

Use sandboxes

Manage sandboxes

Reference

Choose authentication

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

​Choose authentication

​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 authentication

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