> ## 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.

# 사용 가능한 러너 검색

> 조직의 러너 목록을 조회하고, 러너가 제공하는 하드웨어 정보와 여유 용량을 확인하세요.

검색 API를 사용하면 조직에 등록된 러너 목록을 조회하고, 각 러너가 제공하는
하드웨어 정보를 확인하고, 샌드박스를 배치하기 전에 러너의 실시간 용량을
확인할 수 있습니다.

러너는 CKS 클러스터에 배포된 구성 요소입니다. 러너는 CoreWeave의 관리형
컨트롤 플레인에 등록되어 클러스터의 컴퓨팅을 샌드박스 플랫폼에 연결합니다. 따라서
러너의 기능은 해당 러너가 속한 클러스터의 하드웨어에 따라 결정됩니다.

검색은 CKS 배치에만 해당합니다. 서버리스 샌드박스는 사용자가 소유한 러너에서 실행되지 않으므로
검색할 대상이 없습니다. 필요한 샌드박스 사양을 지정하면 플랫폼이 알아서
배치합니다. [샌드박스 배치](/ko/products/sandboxes/placement)를 참조하세요.

검색 결과는 러너가 지원하는 기능을 보여 줄 뿐, 러너가 허용하는 범위를 보여 주지는 않습니다. 개별
샌드박스가 요청할 수 있는 범위는 러너에 적용된 정책에 따라 제한되며, 이 정책은
Admin이 작성합니다. [정책 개요](/ko/products/sandboxes/profiles/profiles)를 참조하세요.

<Note>
  **프로필을 사용하다가 전환하시나요?** 클라이언트는 더 이상 `Profile`,
  `list_profiles()`, `get_profile()`, `ProfileNotFoundError`를 내보내지 않습니다. `profile_names`와
  `profile_ids`는 `Sandbox`, `Session` 및 각각의 `list()`
  메서드에 매개변수 이름으로 남아 있지만, 값을 전달하면 `TypeError`가 발생합니다. 대신 `runner_ids`로
  러너를 지정하세요. 거버넌스 모델은 프로필에서 정책으로 대체되었으며, 정책은 사용자가 직접 선택하지
  않습니다. [정책 개요](/ko/products/sandboxes/profiles/profiles)를 참조하세요.
</Note>

<h2 id="list-runners">
  러너 목록 조회
</h2>

`list_runners()`는 현재 사용자 인증 정보로 조회할 수 있는 모든 러너를 반환합니다.

```python theme={"system"}
from cwsandbox import AuthStrategy, Runner, list_runners

runners: list[Runner] = list_runners(auth=AuthStrategy.COREWEAVE_API_KEY)

for runner in runners:
    print(runner)
```

`Runner`에는 기본 제공 표현 형식이 있어 러너 ID, 소유 조직, health, 사람이 읽기 쉬운 단위로 나타낸 CPU 및 메모리, GPU 수, 그리고
러너가 강제 적용할 수 있는 서비스 공개 범위를 출력합니다.

출력 예시:

```text theme={"system"}
Runner(runner_id='prod-us-east-1', organization_id='1a2b3c4d', healthy=True, cpu=512.0 vCPU, memory=4.0 TiB, gpus=64, visibilities=['public', 'private'])
```

<h2 id="read-runner-capabilities">
  러너 기능 조회
</h2>

각 러너는 자신의 노드에 탑재된 하드웨어 정보를 제공합니다. 이 속성을 조회하여 생성하려는
샌드박스를 실행할 수 있는 러너를 찾으세요.

```python theme={"system"}
from cwsandbox import AuthStrategy, list_runners

for runner in list_runners(auth=AuthStrategy.COREWEAVE_API_KEY):
    print(runner.runner_id)
    print(f"  gpu types:     {', '.join(runner.supported_gpu_types) or 'none'}")
    print(f"  max gpus:      {runner.max_gpu_count}")
    print(f"  architectures: {', '.join(runner.supported_architectures)}")
    print(f"  storage:       {', '.join(runner.available_storage_classes)}")
```

`supported_gpu_types`에는 GPU
요청의 `type` 키에 전달할 정확한 문자열이 들어 있습니다. 대소문자를 구분하므로 `B200`과 `b200`은 서로 다른 유형으로 처리됩니다.
[GPU 샌드박스 실행](/ko/products/sandboxes/gpu-sandboxes)을 참조하세요.

`max_gpu_count`는 러너가 보고하는 전체 GPU 용량이며, 샌드박스별 한도가 아닙니다. 샌드박스 하나가 요청할 수 있는
GPU 수는 러너 정책의 `maxGpuCount`와
단일 노드에서 사용 가능한 GPU 수에 따라 제한됩니다.

<h3 id="runner-attributes">
  러너 속성
</h3>

`Runner`에는 다음 속성이 있습니다.

| 속성 | 유형 | 설명 |
| - | - | - |
| `runner_id` | `str` | 조직 내에서 러너를 식별하는 ID입니다. 전역적으로 고유하지는 않습니다. |
| `organization_id` | `str` | 러너를 소유한 조직입니다. |
| `runner_group_id` | `str` | 러너가 속한 그룹입니다. |
| `tags` | `tuple[str, ...]` | 러너에 지정된 태그입니다. |
| `healthy` | `bool` | 러너가 현재 정상 상태인지 여부입니다. |
| `is_shared` | `bool` | 러너가 공유 조직에 속한 경우 `True`입니다. |
| `connected_at` | `datetime` | 러너가 연결된 시각으로, UTC 시간대 정보가 포함된 datetime입니다. |
| `max_cpu_millicores` | `int` | 보고된 총 CPU 용량(밀리코어 단위)입니다. |
| `max_memory_bytes` | `int` | 보고된 총 메모리 용량(바이트 단위)입니다. |
| `max_gpu_count` | `int` | 보고된 총 GPU 용량입니다. |
| `supported_gpu_types` | `tuple[str, ...]` | 러너의 노드에 탑재된 GPU 유형입니다. |
| `supported_architectures` | `tuple[str, ...]` | 러너가 지원하는 CPU 아키텍처입니다(예: `amd64`). |
| `supports_privileged` | `bool` | 권한 있는 컨테이너의 허용 여부입니다. |
| `available_storage_classes` | `tuple[str, ...]` | 클러스터에서 사용 가능한 Kubernetes 스토리지 클래스입니다. |
| `supported_service_visibilities` | `tuple[str, ...]` | 러너가 강제 적용할 수 있는 서비스 공개 범위로, `public`, `private`, `custom`이 있습니다. [`ServiceVisibility`](/ko/products/sandboxes/client/ref/networking/services#servicevisibility)를 참조하세요. |
| `resources` | `RunnerResources \| None` | 실시간 리소스 가용량입니다. 러너가 이를 보고하지 않으면 `None`입니다. |

`max_*` 값이 `0`이라고 해서 러너에 리소스가 없다는 뜻은 아닙니다. 러너가 해당 용량을 공개하거나 보고하지 않는다는 의미일 수 있습니다.
공유 러너는 용량 정보가 공개되지 않으므로 `0`을 반환합니다. 또한
CPU 및 메모리 값에서는 예약 용량이 제외될 수 있습니다.

<h2 id="check-live-capacity">
  실시간 용량 확인
</h2>

기본적으로 `list_runners()`는 지원 기능(capability) 데이터만 반환합니다.
`include_resources=True`를 전달하면 `Runner.resources`에 실시간 가용성 정보가 채워집니다.
`format_bytes()`와 `format_cpu()`를 사용해 값을 사람이 읽기 쉬운 단위로 출력하세요:

```python theme={"system"}
from cwsandbox import AuthStrategy, format_bytes, format_cpu, list_runners

runners = list_runners(
    auth=AuthStrategy.COREWEAVE_API_KEY,
    include_resources=True,
)

for r in runners:
    print(f"{r.runner_id}  healthy={r.healthy}")
    print(f"  max: {format_cpu(r.max_cpu_millicores)}, {format_bytes(r.max_memory_bytes)}")
    if r.resources:
        free_cpu = format_cpu(r.resources.available_cpu_millicores)
        free_mem = format_bytes(r.resources.available_memory_bytes)
        print(f"  free:  {free_cpu}, {free_mem}, {r.resources.available_gpu_count} GPUs")
        print(f"  running sandboxes: {r.resources.running_sandboxes}")
```

러너가 가용성을 보고하지 않으면 `resources`는 `None`이 되므로, 값을 읽기 전에
`None`인지 먼저 확인하세요.

<h3 id="runnerresources-attributes">
  RunnerResources 속성
</h3>

`RunnerResources` 객체에는 다음 속성이 있습니다.

| 속성 | 유형 | 설명 |
| - | - | - |
| `available_cpu_millicores` | `int` | 예약되지 않은 CPU(밀리코어 단위)입니다. |
| `available_memory_bytes` | `int` | 예약되지 않은 메모리(바이트 단위)입니다. |
| `available_gpu_count` | `int` | 예약되지 않은 GPU 수입니다. |
| `running_sandboxes` | `int` | 현재 러너에서 실행 중인 샌드박스 수입니다. |

<h2 id="filter-the-list">
  목록 필터링
</h2>

필터를 조합하면 워크로드를 처리할 수 있는 러너만 남도록 목록을 좁힐 수 있습니다. 다음
호출은 지정한 GPU 유형을 갖추고 있고 사용 가능한 GPU가 두 개 이상인 정상 상태의 러너를 반환합니다. `[GPU-TYPE]`을 `supported_gpu_types`의 값으로 바꾸세요.

```python theme={"system"}
from cwsandbox import AuthStrategy, list_runners

runners = list_runners(
    auth=AuthStrategy.COREWEAVE_API_KEY,
    gpu_type="[GPU-TYPE]",
    healthy_only=True,
    min_available_gpu_count=2,
)

for r in runners:
    print(f"{r.runner_id}: {r.resources.available_gpu_count} GPUs free")
```

검색 서비스는 `runner_group_id`, `gpu_type`, `architecture`,
`healthy_only`, `service_visibility`를 적용합니다. 세 가지
`min_available_*` 필터는 결과를 받은 후 클라이언트에서 적용됩니다. 이 세 필터를 사용하면
`include_resources`가 자동으로 활성화되고, 리소스 데이터를 보고하지 않는 러너는 제외되므로
이 필터가 반환하는 결과에는 항상 `resources`가 채워져 있습니다.

<h3 id="parameters">
  매개변수
</h3>

`list_runners()`에서 사용할 수 있는 매개변수는 다음과 같습니다. 모든 매개변수는 키워드 전용입니다.

| 매개변수 | 유형 | 설명 |
| - | - | - |
| `auth` | `AuthConfig \| None` | 이 요청에 사용할 인증 전략, 확인된 헤더 또는 공급자입니다. |
| `runner_group_id` | `str \| None` | 지정한 러너 그룹의 결과만 반환합니다. |
| `gpu_type` | `str \| None` | 지정한 GPU 유형을 지원하는 러너만 반환합니다. |
| `architecture` | `str \| None` | 지정한 CPU 아키텍처를 지원하는 러너만 반환합니다. |
| `healthy_only` | `bool` | 정상 상태인 러너만 반환합니다. 기본값은 `False`입니다. |
| `include_resources` | `bool` | 각 러너의 실시간 리소스 가용량을 함께 반환합니다. 기본값은 `False`입니다. |
| `min_available_cpu_millicores` | `int \| None` | 예약되지 않은 CPU 밀리코어의 최솟값입니다. 설정하면 `include_resources`가 자동으로 활성화됩니다. |
| `min_available_memory_bytes` | `int \| None` | 예약되지 않은 메모리의 최솟값(바이트)입니다. 설정하면 `include_resources`가 자동으로 활성화됩니다. |
| `min_available_gpu_count` | `int \| None` | 예약되지 않은 GPU 개수의 최솟값입니다. 설정하면 `include_resources`가 자동으로 활성화됩니다. |
| `service_visibility` | `str \| None` | 지정한 서비스 공개 범위(`public`, `private` 또는 `custom`)를 강제 적용할 수 있는 러너만 반환합니다. |

<h2 id="get-a-single-runner">
  단일 러너 조회
</h2>

`get_runner()`는 러너 ID와 해당 러너를 소유한 조직을 인수로 받습니다. 러너 ID는
전역이 아니라 조직 내에서만 고유하므로 두 값을 모두 지정해야 합니다. 이 호출은
항상 전체 세부 정보를 반환하지만, 리소스 가용량은 사용자의 조직이 소유한 러너에 대해서만
포함됩니다. `[RUNNER-ID]`와 `[ORGANIZATION-ID]`를 조회할 러너 및
해당 러너를 소유한 조직의 값으로 바꾸세요:

```python theme={"system"}
from cwsandbox import AuthStrategy, RunnerNotFoundError, get_runner

try:
    runner = get_runner(
        "[RUNNER-ID]",
        organization_id="[ORGANIZATION-ID]",
        auth=AuthStrategy.COREWEAVE_API_KEY,
    )
    print(f"{runner.runner_id}  healthy={runner.healthy}")
    if runner.resources:
        print(f"  running sandboxes: {runner.resources.running_sandboxes}")
except RunnerNotFoundError as e:
    print(f"Runner not found: {e.runner_id}")
```

목록으로 조회한 러너에는 각각 고유한 `organization_id`가 있으므로, 이전 결과에서 찾은 러너를 조회할 때는
`runner.organization_id`를 전달하세요.

<h2 id="create-a-sandbox-on-a-discovered-runner">
  검색된 러너에서 샌드박스 생성
</h2>

`placement_mode="cks"`로 설정하고 선택한 러너를 `runner_ids`에 전달하세요.
`[GPU-TYPE]`은 `supported_gpu_types`에 있는 값으로 바꾸세요.

```python theme={"system"}
from cwsandbox import AuthStrategy, ResourceOptions, Sandbox, list_runners

runners = list_runners(
    auth=AuthStrategy.COREWEAVE_API_KEY,
    gpu_type="[GPU-TYPE]",
    min_available_gpu_count=1,
)

if runners:
    with Sandbox.run(
        auth=AuthStrategy.COREWEAVE_API_KEY,
        placement_mode="cks",
        runner_ids=[runners[0].runner_id],
        resources=ResourceOptions(
            requests={"cpu": "2", "memory": "8Gi"},
            limits={"cpu": "2", "memory": "8Gi"},
            gpu={"count": 1, "type": "[GPU-TYPE]"},
        ),
        max_lifetime_seconds=3600,
    ) as sandbox:
        print(sandbox.exec(["nvidia-smi", "-L"]).result().stdout)
```

`runner_ids`를 지정하지 않으면 CKS 배치 시 조직 내에서 조건을 충족하는 모든 러너가 사용될 수 있습니다.
`runner_ids`는 서버리스 배치 또는
`placement_spillover="serverless_then_cks"`와 함께 사용할 수 없습니다.

<h3 id="apply-a-runner-to-every-sandbox-in-a-session">
  세션의 모든 샌드박스에 러너 적용하기
</h3>

세션의 모든 샌드박스를 동일한 러너로 보내려면 `SandboxDefaults`를 사용하세요.

```python theme={"system"}
from cwsandbox import AuthStrategy, SandboxDefaults, Session, list_runners

runners = list_runners(auth=AuthStrategy.COREWEAVE_API_KEY, healthy_only=True)

if runners:
    defaults = SandboxDefaults(
        auth=AuthStrategy.COREWEAVE_API_KEY,
        placement_mode="cks",
        runner_ids=(runners[0].runner_id,),
    )

    with Session(defaults) as session:
        sb = session.sandbox()
        print(sb.exec(["echo", "running on a discovered runner"]).result().stdout)
```

나머지 샌드박스 옵션은
[샌드박스 구성 가이드](/ko/products/sandboxes/client/guides/sandbox-configuration)를 참조하세요.

<h2 id="error-reference">
  오류 레퍼런스
</h2>

검색 호출은 다음 예외를 발생시킬 수 있습니다.

| Exception | Cause |
| - | - |
| `RunnerNotFoundError` | 지정한 `runner_id` 및 `organization_id`와 일치하는 러너가 없습니다. |
| `DiscoveryValidationError` | 검색 요청이 필드 수준 유효성 검사를 통과하지 못했습니다. |
| `DiscoveryError` | 검색 오퍼레이션 중 네트워크 또는 서비스 오류입니다. 위 두 예외의 기본 클래스입니다. |
| `CWSandboxAuthenticationError` | 잘못되었거나 누락된 사용자 인증 정보입니다. |

`runner_id` 또는 `organization_id`가 비어 있으면 `get_runner()`는 요청을 보내기 전에
`ValueError`를 발생시킵니다.

전체 예외 계층 구조는
[예외 레퍼런스](/ko/products/sandboxes/client/ref/exceptions/exceptions)를 참조하세요.
일반적인 문제 해결 단계는
[Sandboxes 지원 아티클](/ko/support/sandboxes)을 참조하세요.