Exécuter une sandbox GPU - CoreWeave Docs

This guide shows how to create a sandbox with one or more GPUs, confirm the GPU is visible from inside the sandbox, and set the CPU and memory requests that go with it. GPU sandboxes run in either placement mode: on serverless capacity that CoreWeave operates, or on a CoreWeave Kubernetes Service (CKS) cluster you own. The two modes differ in how the sandbox is isolated, which GPUs you can get, and who sets the limits, so this page covers them in separate sections. Pour les sandboxes CPU uniquement, consultez Premiers pas.

GPU sandboxes are in private preview and require your organization to be allowlisted, even if it already has access to CPU-only sandboxes in public preview. To request access, contact your account team or email forge-support@coreweave.com. Until your organization is allowlisted, requests to create GPU sandboxes fail with CWSANDBOX_GPU_NOT_ALLOWED.

For concurrent sandbox quotas and resource limits, see Limits and quotas.

Before you begin

You need the following:

Des sandboxes GPU activées pour votre organisation.
Une clé API W&B.
Le client Python cwsandbox en version 1.14.2 ou ultérieure, avec l’extra wandb :
uv pip install 'cwsandbox[wandb]>=1.14.2'

The TypeScript client doesn’t expose GPU resources yet. Use the Python client for GPU sandboxes.

Fonctionnement des requêtes de GPU

Les requêtes de GPU obéissent aux règles suivantes :

Une requête de GPU réserve des GPU, et rien d’autre. Définissez explicitement le CPU et la mémoire, en les dimensionnant en fonction du travail que vous exécuterez en parallèle du GPU. Si vous omettez les valeurs de CPU et de mémoire, les valeurs defaultCpu et defaultMemory de la politique peuvent s’appliquer, mais l’allocation résultante doit tout de même respecter les exigences de ressources de la politique.
Les sandboxes reçoivent des GPU entiers. Les GPU ne sont ni partagés, ni partitionnés, ni répartis par tranches de temps entre les sandboxes.
Une sandbox reçoit exactement 1 GPU. La capacité serverless ne prend en charge que les sandboxes à 1 GPU.
Le type de GPU est un filtre, pas un menu. La clé facultative type doit correspondre exactement, casse comprise, à l’un des types de GPU annoncés par le runner. Omettez-la pour accepter n’importe quel GPU dont dispose le runner.

Exécuter un sandbox GPU sur une capacité serverless

Le placement serverless ne nécessite ni runner ni politique de votre part. CoreWeave fournit la politique et le matériel. Les sandboxes GPU s’exécutent dans une machine virtuelle et se prêtent donc à l’exécution de code non fiable.

GPU disponibles

La capacité serverless repose sur un seul modèle de GPU : le NVIDIA RTX PRO 6000 Blackwell Server Edition. Sur la capacité serverless, seules les sandboxes à 1 GPU sont prises en charge.

GPU	GPU memory	GPUs per sandbox
NVIDIA RTX PRO 6000 Blackwell Server Edition	96 GB	1

Two instance types carry it: High Memory and Standard Memory. They differ in host RAM, not in the GPU, and both present the same GPU type to a sandbox, so which one a sandbox lands on isn’t something you select. Leave the type key out of the GPU request so the platform assigns a GPU from CoreWeave-managed compute. The field is still accepted here, but it filters rather than selects: a type that matches no runner fails with CWSANDBOX_RUNNER_UNAVAILABLE. A runner that receives an unsupported type rejects it with CWSANDBOX_PLACEMENT_CONSTRAINT_UNSATISFIED. Use resources to choose CPU and memory alongside the GPU count, as shown in the following example. Disk is requested separately from CPU, memory, and GPU rather than alongside them: ResourceOptions has no disk field. The container’s root filesystem is Node-local ephemeral storage that the sandbox doesn’t reserve a share of, so df inside the sandbox reports the Node’s filesystem rather than a per-sandbox quota. For a dedicated writable path, declare a scratch volume:

from cwsandbox import AuthStrategy, Sandbox, ScratchVolumeOptions

with Sandbox.run(
    auth=AuthStrategy.WANDB,
    resources={"cpu": "2", "memory": "8Gi", "gpu": 1},
    volumes=[ScratchVolumeOptions(name="work", mount_path="/work", size="20Gi")],
    max_lifetime_seconds=3600,
) as sandbox:
    result = sandbox.exec(["df", "-h", "/work"]).result()
    print(result.stdout)

A disk-backed volume, the default, draws on the same Node-local storage as the root filesystem. Set medium="memory" for a tmpfs instead: a memory-backed volume must declare a size, and the memory-backed volumes on one container can’t total more than 80% of its memory request. Leave runtime_class unset too. A GPU request selects the GPU virtual machine runtime class on its own, and a runtime class you pin is used exactly as given, so pinning the CPU class alongside a GPU request produces a sandbox that can’t reach the GPU.

Create the sandbox

Définissez WANDB_API_KEY sur votre clé API W&B, puis exécutez l’exemple suivant. Il crée une sandbox dotée d’un GPU, de 2 CPU et de 8 Gio de mémoire, puis affiche le GPU détecté par nvidia-smi.

Python
TypeScript

Cet exemple utilise AuthStrategy.WANDB pour une clé API W&B.

from cwsandbox import AuthStrategy, Sandbox

with Sandbox.run(
    auth=AuthStrategy.WANDB,
    resources={"cpu": "2", "memory": "8Gi", "gpu": 1},
    max_lifetime_seconds=3600,
) as sandbox:
    result = sandbox.exec(
        ["nvidia-smi", "--query-gpu=name,memory.total", "--format=csv"]
    ).result()
    print(result.stdout)
    print(sandbox.resource_gpu)

Le dict resources à plat attribue les mêmes valeurs aux requests et aux limites. "gpu": 1 est un raccourci pour "gpu": {"count": 1}. Le mode serverless ne prend en charge qu’un seul GPU par sandbox ; conservez donc la valeur 1.La propriété resource_gpu renvoie l’allocation de GPU confirmée par la plateforme, par exemple {'count': 1}.

Le package @coreweave/cwsandbox n’accepte pas encore les ressources GPU. Son option resources ne couvre que le CPU et la mémoire, et toute clé gpu est ignorée : la sandbox démarre donc sans GPU. Utilisez le client Python pour créer des sandboxes GPU.

Sample output:

name, memory.total [MiB]
NVIDIA RTX PRO 6000 Blackwell Server Edition, 97887 MiB

{'count': 1}

GPU sandboxes take longer to start than CPU-only sandboxes because the platform attaches the GPUs to the sandbox’s virtual machine. Allow several minutes if you set a request timeout.

Container images

The platform provides the NVIDIA driver and the nvidia-smi tool inside a GPU sandbox, so the default image can already see the GPU. To run CUDA applications, use an image that ships the CUDA runtime and libraries your code needs, such as a pytorch/pytorch or nvidia/cuda image. Match the image to the GPU. The RTX PRO 6000 Blackwell Server Edition is compute capability 12.0 (sm_120), which needs CUDA 12.8 or later, and PyTorch 2.7 was the first release built for it. An older image still reports the GPU’s name correctly, because that reads device metadata through the driver, then fails at the first kernel launch with CUDA error: no kernel image is available for execution on the device. Check that your framework lists sm_120 rather than trusting the device name:

from cwsandbox import AuthStrategy, Sandbox

CHECK_GPU = """
import torch

print(torch.cuda.get_device_capability(0))
print(torch.cuda.get_arch_list())

x = torch.ones(32, device="cuda")
print((x + x).sum().item())
torch.cuda.synchronize()
"""

with Sandbox.run(
    auth=AuthStrategy.WANDB,
    container_image="pytorch/pytorch:2.8.0-cuda12.8-cudnn9-runtime",
    resources={"cpu": "2", "memory": "8Gi", "gpu": 1},
) as sandbox:
    result = sandbox.exec(["python", "-c", CHECK_GPU]).result()
    print(result.stdout)

Sample output:

(12, 0)
['sm_70', 'sm_75', 'sm_80', 'sm_86', 'sm_90', 'sm_100', 'sm_120']
64.0

A large framework image takes longer to pull than the default image, so allow a few minutes for the sandbox to become ready.

Common errors

Erreur	Cause	Solution
`CWSANDBOX_GPU_NOT_ALLOWED`	Votre organisation ne figure pas sur la liste d’autorisation des sandboxes GPU.	Contactez votre équipe de compte ou forge-support@coreweave.com pour demander l’accès.
`SandboxResourceExhaustedError` (`runner capacity exhausted`)	Aucun nœud ne dispose actuellement de suffisamment de GPU, de CPU ou de mémoire libres pour satisfaire la requête.	Patientez quelques instants, puis réessayez.
`CWSANDBOX_RUNNER_UNAVAILABLE` (`no eligible runner is available`)	Aucune capacité ne correspond à la requête. Cela peut notamment provenir d’un `type` de GPU que la capacité serverless ne propose pas, y compris un type saisi avec une casse incorrecte. Le même code apparaît aussi lorsqu’aucune capacité n’est connectée pour le moment.	Supprimez `type`. Si la requête est déjà correcte, réessayez.
`nvidia-smi: not found`	La sandbox ne dispose d’aucun GPU, ou son image n’expose pas les outils NVIDIA.	Vérifiez d’abord `sandbox.resource_gpu`. S’il indique un nombre positif, les GPU sont bien alloués et c’est l’image qu’il faut modifier.

Next steps

Configuration de la sandbox décrit chaque champ de ResourceOptions, les classes QoS et les délais d’expiration.
Premiers pas présente les sandboxes serverless CPU uniquement et les identifiants d’authentification.

​Before you begin

​Fonctionnement des requêtes de GPU

​Exécuter un sandbox GPU sur une capacité serverless

​GPU disponibles

​Create the sandbox

​Container images

​Common errors

​Next steps

Before you begin

Fonctionnement des requêtes de GPU

Exécuter un sandbox GPU sur une capacité serverless

GPU disponibles

Create the sandbox

Container images

Common errors

Next steps