> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreweave.com/llms.txt
> Use this file to discover all available pages before exploring further.

# GPU 샌드박스 실행하기

> 가상 머신에서 실행되는 서버리스 샌드박스용 GPU를 요청합니다.

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.

CPU 전용 샌드박스에 대해서는 [시작하기](/ko/products/sandboxes/serverless/get-started)를 참조하세요.

<Note>
  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](mailto:forge-support@coreweave.com). Until your organization is allowlisted, requests to create GPU sandboxes fail with `CWSANDBOX_GPU_NOT_ALLOWED`.
</Note>

For concurrent sandbox quotas and resource limits, see [Limits and quotas](reference/limits-and-quotas).

## Before you begin

You need the following:

* 조직에 GPU 샌드박스가 활성화되어 있어야 합니다.
* [W\&B API 키](https://forge.coreweave.com/settings#apikeys)가 필요합니다.
* `wandb` extra를 포함한 Python 클라이언트 `cwsandbox` 1.14.2 이상이 필요합니다.

  ```bash theme={"system"}
  uv pip install 'cwsandbox[wandb]>=1.14.2'
  ```

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

<h2 id="how-gpu-requests-work">
  GPU 요청의 작동 방식
</h2>

GPU 요청에는 다음 규칙이 적용됩니다.

* **GPU 요청은 GPU만 예약합니다.** CPU와 메모리는 GPU와 함께 실행할 작업에 맞게 명시적으로 설정하세요. CPU와 메모리 값을 생략하면 정책의 `defaultCpu` 및 `defaultMemory`가 사용될 수 있지만, 최종 결정된 할당량은 정책의 리소스 요구 사항을 충족해야 합니다.
* **샌드박스는 GPU를 통째로 할당받습니다.** GPU는 샌드박스 간에 공유, 분할 또는 시분할되지 않습니다.
* **샌드박스에는 정확히 1개의 GPU가 할당됩니다.** 서버리스 용량에서는 GPU 1개짜리 샌드박스만 지원합니다.
* **GPU 유형은 선택 메뉴가 아니라 필터입니다.** 선택 항목인 `type` 키는 러너가 제공하는 GPU 유형 중 하나와 대소문자까지 정확히 일치해야 합니다. 러너에 있는 GPU라면 무엇이든 허용하려면 이 키를 생략하세요.

<h2 id="run-a-gpu-sandbox-on-serverless-capacity">
  서버리스 용량에서 GPU 샌드박스 실행하기
</h2>

서버리스 배치를 사용하면 러너나 정책을 직접 마련할 필요가 없습니다. 정책과 하드웨어는 CoreWeave가 소유합니다. GPU 샌드박스는 가상 머신에서 실행되므로 신뢰할 수 없는 코드를 실행하기에 적합합니다.

<h3 id="available-gpus">
  사용 가능한 GPU
</h3>

서버리스 용량에서는 NVIDIA RTX PRO 6000 Blackwell Server Edition 한 가지 GPU 모델만 제공됩니다. 또한 서버리스 용량에서는 GPU 1개로 구성된 샌드박스만 지원됩니다.

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

Two instance types carry it: [High Memory](/platform/instances/gpu/rtxp6000-8x) and [Standard Memory](/platform/instances/gpu/rtxp6000-8x-v2). 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:

```python theme={"system"}
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

`WANDB_API_KEY`를 W\&B API 키로 설정한 다음 아래 예제를 실행하세요. 이 예제는 GPU 1개, CPU 2개, 메모리 8GiB로 샌드박스를 생성한 뒤 `nvidia-smi`가 보고하는 GPU 정보를 출력합니다.

<Tabs>
  <Tab title="Python">
    이 예제는 W\&B API 키로 인증하기 위해 `AuthStrategy.WANDB`를 사용합니다.

    ```python theme={"system"}
    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)
    ```

    평면 구조의 `resources` dict를 사용하면 requests와 limits가 같은 값으로 설정됩니다. `"gpu": 1`은 `"gpu": {"count": 1}`의 축약형입니다. 서버리스에서는 샌드박스당 GPU를 1개만 지원하므로 개수는 `1`로 유지하세요.

    `resource_gpu` 속성은 플랫폼이 확정한 GPU 할당(예: `{'count': 1}`)을 반환합니다.
  </Tab>

  <Tab title="TypeScript">
    `@coreweave/cwsandbox` 패키지는 아직 GPU 리소스를 지원하지 않습니다. 이 패키지의 `resources` 옵션은 CPU와 메모리만 지원하며 `gpu` 키는 무시되므로, 샌드박스가 GPU 없이 시작됩니다. GPU 샌드박스를 생성하려면 Python 클라이언트를 사용하세요.
  </Tab>
</Tabs>

Sample output:

```text theme={"system"}
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:

```python theme={"system"}
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:

```text theme={"system"}
(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

| 오류 | 원인 | 조치 방법 |
| - | - | - |
| `CWSANDBOX_GPU_NOT_ALLOWED` | 조직이 GPU 샌드박스 허용 목록에 등록되어 있지 않습니다. | 액세스를 요청하려면 담당 계정 팀 또는 [forge-support@coreweave.com](mailto:forge-support@coreweave.com)으로 문의하세요. |
| `SandboxResourceExhaustedError` (`runner capacity exhausted`) | 현재 요청을 처리할 만큼 GPU, CPU 또는 메모리 여유가 있는 노드가 없습니다. | 잠시 후 다시 시도하세요. |
| `CWSANDBOX_RUNNER_UNAVAILABLE` (`no eligible runner is available`) | 요청에 맞는 용량이 없습니다. 서버리스 용량에서 제공하지 않는 GPU `type`을 지정한 경우가 한 가지 원인이며, 대소문자를 잘못 입력한 유형도 여기에 해당합니다. 현재 연결된 용량이 없을 때도 같은 코드가 표시됩니다. | `type`을 제거하세요. 요청에 문제가 없다면 다시 시도하세요. |
| `nvidia-smi: not found` | 샌드박스에 GPU가 없거나, 이미지에서 NVIDIA 도구를 제공하지 않습니다. | 먼저 `sandbox.resource_gpu`를 확인하세요. 값이 0보다 크면 GPU는 할당된 상태이므로 이미지를 변경해야 합니다. |

## Next steps

* [샌드박스 설정](/ko/products/sandboxes/serverless/client/guides/sandbox-configuration)에서는 모든 `ResourceOptions` 필드, QoS 클래스, timeout을 설명합니다.
* [시작하기](/ko/products/sandboxes/serverless/get-started)에서는 CPU 전용 서버리스 샌드박스와 자격 증명을 설명합니다.