Deploy and manage a runner

관리형 러너는 CKS 클러스터 내에서 샌드박스를 실행하는 CoreWeave 관리 컴포넌트입니다. 이 페이지에서는 러너 배포, 정상 작동 확인, 요구 사항 변화에 따른 설정 조정, 더 이상 필요하지 않을 때 제거하기까지 전체 라이프사이클을 다룹니다. 샌드박스 아키텍처에서 러너의 위치와 게이트웨이가 러너에 요청을 중개하는 방식은 샌드박스 아키텍처를 참조하세요. 러너 활성화부터 첫 샌드박스 실행까지의 과정을 단계별로 살펴보려면 자체 컴퓨팅 사용하기를 참조하세요.

시작하기 전에

이 페이지의 CLI 및 curl 예시는 모두 CoreWeave API 액세스 토큰으로 인증합니다. Cloud Console의 Tokens 페이지에서 토큰을 생성하고 Token Secret 값을 복사하세요. 토큰에 대한 자세한 내용은 API 액세스 토큰 관리를 참조하세요. CLI: CoreWeave Intelligent CLI(cwic)를 설치한 다음 cwic auth login을 실행하고, 메시지가 표시되면 토큰을 붙여넣으세요. 토큰은 로컬 cwic 설정에 저장되며, 이후 명령어를 실행할 때 자동으로 사용됩니다. 별도로 환경 변수를 설정할 필요는 없습니다.

cwic auth login

curl: 이 페이지의 예시에서 토큰을 사용할 수 있도록 셸에서 토큰을 export하세요. [API-ACCESS-TOKEN]을 CoreWeave API 액세스 토큰으로 바꾸세요.

export TOKEN="[API-ACCESS-TOKEN]"

러너 명령어

cwic sandbox runner 그룹은 러너를 관리합니다. 다음 table은 각 라이프사이클 작업과 이를 수행하는 명령어를 연결합니다. 이후 섹션에서는 실제 사용 맥락에서 이러한 명령어를 설명합니다.

목표	명령어
러너 배포(마법사)	`cwic sandbox runner create [RUNNER-ID]`
파일에서 러너 배포	`cwic sandbox runner create [RUNNER-ID] -f runner.yaml`
러너 목록 조회	`cwic sandbox runner get` (별칭 `ls`)
러너 하나 확인	`cwic sandbox runner get [RUNNER-ID]`
상세 뷰	`cwic sandbox runner describe [RUNNER-ID]`
러너 편집	`cwic sandbox runner edit [RUNNER-ID]`
사용 가능한 업데이트 적용	`cwic sandbox runner upgrade [RUNNER-ID]`
러너 삭제	`cwic sandbox runner delete [RUNNER-ID]`
러너 정책 조회	`cwic sandbox runner policy get [RUNNER-ID]`
러너 정책 편집	`cwic sandbox runner policy edit [RUNNER-ID]`

모든 입력은 YAML 또는 JSON을 허용합니다.

러너 배포

조직 내에서 각 CKS 클러스터는 최대 하나의 관리형 러너를 호스팅합니다. 배포하려면 다음을 제공하세요:

러너 ID: 클라이언트가 할당한 사람이 읽을 수 있는 ID로, 조직 내에서 고유합니다.
영역: 클러스터가 속한 지리적 영역.
Cluster ID (또는 cluster name): 러너가 실행되는 CKS 클러스터. Cloud Console의 Clusters 페이지에서 둘 다 찾을 수 있습니다.
Policy: 클러스터의 샌드박스에 대해 러너가 강제 적용하는 규칙. 샌드박스를 실행하려면 정책이 있어야 합니다. 정책을 생략하면 러너가 연결될 때 CoreWeave가 기본 정책을 제공합니다. 정책에서 기본 샌드박스 수명을 지정할 수 있으며, 최대 수명인 30일은 플랫폼이 강제 적용합니다. 샌드박스 정책 설정 참조.

CLI
curl

마법사가 클러스터, 릴리스 채널 및 유지 관리 창을 대화식으로 수집한 다음 제출하기 전에 미리 채워진 사양으로 편집기를 엽니다:

cwic sandbox runner create prod-us-east-1

파일 모드는 YAML 또는 JSON을 허용하므로 반복 가능한 설정에 선호되는 경로이며, 대신 러너 사양을 생성하는 Claude Code 또는 Codex와 같은 에이전트에 적합합니다. CLI는 -f -로 표준 입력에서도 읽습니다. 러너를 배포할 CKS 클러스터 이름으로 [CLUSTER-NAME]을 교체하세요:

runner.yaml

identity:
  zone: us-east-1
  cluster_name: [CLUSTER-NAME]
spec:
  release_channel: RELEASE_CHANNEL_STABLE
  maintenance_policy:
    windows:
      - cron: "0 9 * * SAT"
        duration_seconds: 14400
policy:
  display_name: default
  constraints:
    resources:
      default_cpu: "1"
      default_memory: "2Gi"
      max_cpu: "4"
      max_memory: "8Gi"
      require_limits: true
    lifecycle:
      default_lifetime_seconds: 3600

사양을 제출하세요:

cwic sandbox runner create prod-us-east-1 -f runner.yaml

러너를 배포할 CKS 클러스터 ID로 [CLUSTER-ID]를 교체하세요:

Deploy a managed runner

curl -X POST https://api.coreweave.com/v1/sandbox/managedRunners \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Production runner (US East)",
    "identity": {
      "runnerId": "prod-us-east-1",
      "zone": "us-east-1",
      "clusterId": "[CLUSTER-ID]"
    },
    "spec": {
      "releaseChannel": "RELEASE_CHANNEL_STABLE",
      "maintenancePolicy": {
        "windows": [
          { "cron": "0 9 * * SAT", "durationSeconds": 14400 }
        ]
      }
    },
    "policy": {
      "displayName": "default",
      "constraints": {
        "resources": {
          "defaultCpu": "1",
          "defaultMemory": "2Gi",
          "maxCpu": "4",
          "maxMemory": "8Gi",
          "requireLimits": true
        },
        "lifecycle": { "defaultLifetimeSeconds": 3600 }
      }
    }
  }'

다음 동작에 유의하세요:

maintenance_policy.windows는 선택 사항입니다. 설정하면 자동 업데이트가 지정된 cron 창 동안에만 적용됩니다.
runner_group_id는 선택 사항입니다. 동일한 영역에 여러 러너가 있을 때 스케줄링 어피니티에 사용하세요.

일반적인 검증 오류

오류	해결 방법
`runner.identity.zone is required`	영역을 지정하세요. Cloud Console의 Clusters 페이지에서 또는 `cwic cluster get`을 실행하여 CKS 클러스터가 있는 영역(따라서 러너 할당량이 있는 영역)을 찾으세요.
`runner.identity.cluster_id or cluster_name is required`	둘 중 하나를 지정하세요. Cloud Console의 Clusters 페이지에서 또는 `cwic cluster get`을 실행하여 두 값을 모두 확인할 수 있습니다.
`policy exceeds 256 KiB limit`	정책 문서의 크기를 줄이세요. 인코딩된 문서의 크기는 256 KiB로 제한됩니다.
`a managed runner already exists for this cluster`	클러스터는 관리형 러너를 최대 하나만 호스팅할 수 있습니다. 기존 러너를 업데이트하거나 먼저 삭제하세요.

러너 상태 확인

생성 후 러너의 상태를 확인하여 성공적으로 배포되었는지 확인하고, 그렇지 않은 경우 문제를 진단하세요.

CLI
curl

cwic sandbox runner describe prod-us-east-1

간단한 요약을 표 형식으로 보려면 별칭 get을 사용하세요:

cwic sandbox runner get prod-us-east-1

두 명령 모두 생성 시 지정한 러너 ID(prod-us-east-1) 또는 서버에서 부여한 UUID를 입력으로 받습니다.

러너 조회

curl -H "Authorization: Bearer $TOKEN" \
  https://api.coreweave.com/v1/sandbox/managedRunners/prod-us-east-1

생성 시 지정한 러너 ID 또는 서버에서 부여한 UUID를 전달할 수 있습니다.

응답에는 추적할 상태 필드가 두 개 포함됩니다:

installStatus: 클러스터에 러너를 배포하는 진행 상태(PENDING, PROVISIONING, READY 또는 FAILED).
connectionStatus: 실시간 연결 상태(CONNECTED 또는 DISCONNECTED). 러너의 하트비트가 이 값을 업데이트합니다. 최대 30초의 지연이 발생할 수 있습니다.

installStatus == FAILED인 경우 응답에 구조화된 installError가 포함됩니다:

{
  "installError": {
    "reason": "...",
    "message": "...",
    "remediationHints": ["Add toleration for taint 'workload=gpu:NoSchedule'"],
    "occurredAt": "2026-04-24T12:03:11Z"
  }
}

remediationHints는 수행해야 할 조치입니다. diagnosticDetail에는 지원 요청을 제출할 때 첨부하면 유용한 내부 로그도 포함되어 있습니다.

러너 업데이트

러너 편집 명령은 대화형 마법사와 파일 기반 패치를 모두 지원합니다. 내부적으로 업데이트는 필드 마스크를 사용하여 변경한 필드만 적용합니다. installStatus, connectionStatus, 타임스탬프, 최종 배포 사양을 포함한 나머지 모든 항목은 읽기 전용입니다. 다음 경로는 수정할 수 있습니다.

identity.zone
identity.runner_group_id
spec (전체 객체)
spec.release_channel
spec.maintenance_policy
spec.overrides
spec.enforce_resource_limits
policy (전체 문서)

REST API에서 PATCH 본문은 요청 래퍼 없이 관리형 러너 자체이며, 필드 마스크는 updateMask 쿼리 매개변수로 전달됩니다. 마스크가 없거나 updateMask=*인 경우 수정 가능한 리소스 전체를 대체합니다. 다음 두 경로는 기존 v1beta2 API에서만 허용되며 v1 관리형 러너 쓰기 작업에서는 거부됩니다. profile_bindings (대신 policy를 설정하세요) 및 spec.allow_privileged_profile_annotations.

일반적인 러너 업데이트

다음 예시는 러너에 가장 자주 적용하는 변경 사항을 보여줍니다. 릴리스 채널 전환, 러너에 적용된 정책 교체, 클러스터 내 러너 파드 배치 위치 조정, 기존 프로필 템플릿에 특권 보안 설정 허용이 포함됩니다.

예시: 릴리스 채널 전환

CLI
curl

표준 입력에서 한 줄 패치를 적용하세요:

echo 'spec: {release_channel: RELEASE_CHANNEL_RAPID}' \
  | cwic sandbox runner edit prod-us-east-1 -f -

또는 패치를 파일에 작성한 후 제출하세요:

patch.yaml

spec:
  release_channel: RELEASE_CHANNEL_RAPID

cwic sandbox runner edit prod-us-east-1 -f patch.yaml

RAPID 채널로 러너 이동

curl -X PATCH "https://api.coreweave.com/v1/sandbox/managedRunners/prod-us-east-1?updateMask=spec.releaseChannel" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "identity": { "runnerId": "prod-us-east-1" },
    "spec": { "releaseChannel": "RELEASE_CHANNEL_RAPID" }
  }'

예시: 정책 교체

정책은 전체 문서로 교체됩니다. 현재 정책을 조회하고 필요한 부분을 변경한 후 다시 전송하세요. policy 내부에는 필드 수준 마스크가 없으므로, 부분 본문을 전송하면 생략한 그룹이 모두 지워집니다. 정책 업데이트에는 etag도 포함되며, 이는 러너를 조회할 때 러너가 반환하는 불투명한 리비전 토큰입니다. 더 최신 값이 아니라, 편집할 때 기준으로 삼은 조회에서 받은 값을 전송하세요. 오래된 토큰은 FAILED_PRECONDITION 오류와 함께 실패하며 아무것도 변경되지 않습니다. 따라서 동시 편집이 발생하면 조용히 덮어써지지 않고 오류로 보고됩니다.

CLI
curl

cwic sandbox runner get prod-us-east-1 -o json > runner.json
jq '.[0].policy' runner.json > policy.json

policy.json을 편집한 후, 같은 조회에서 받은 etag로 고정하여 제출하세요:

cwic sandbox runner policy edit prod-us-east-1 -f policy.json \
  --etag "$(jq -r '.[0].etag' runner.json)"

policy get은 etag 없이 정책을 내보내고, --etag 없이 실행한 policy edit -f는 제출하는 시점에 러너의 현재 리비전을 조회합니다. 따라서 둘 다 파일을 가져온 리비전을 고정하지 않습니다. 내보낸 후 policy describe 등으로 토큰을 따로 조회해도 같은 문제가 생깁니다. 문서보다 새로운 토큰은 검사를 통과하므로 그 사이에 이루어진 변경 사항을 덮어쓰게 됩니다. cwic sandbox runner edit 템플릿을 사용하면 이런 추가 단계가 필요 없습니다. --print-template은 변경 가능한 설정, 정책, etag를 한꺼번에 내보내고, -f는 파일에 있는 값을 사용합니다.

러너를 조회하여 현재 정책과 etag를 모두 캡처합니다:

curl -H "Authorization: Bearer $TOKEN" \
  https://api.coreweave.com/v1/sandbox/managedRunners/prod-us-east-1 \
  | jq '{policy, etag}' > policy-and-etag.json

해당 파일에서 policy 객체를 편집한 후, 함께 제공된 etag와 함께 다시 전송합니다:

Replace a runner's policy

curl -X PATCH "https://api.coreweave.com/v1/sandbox/managedRunners/prod-us-east-1?updateMask=policy" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @policy-and-etag.json

모든 제약 그룹과 예시는 샌드박스 정책 설정을 참조하세요.

예시: 배포 오버라이드로 노드 배치 고정하기

spec.overrides 필드는 샌드박스 파드가 아니라 러너 자체의 파드를 조정합니다. 러너 파드를 올바른 노드에 배치하는 데 특정 toleration, 노드 셀렉터 또는 런타임 클래스가 필요한 경우에 사용하세요. 흔히 사용하는 방식은 러너 파드를 SUNK Pod Scheduler로 라우팅하여 SUNK 클러스터에서 Slurm 작업과 함께 실행하는 것입니다. 러너 오버라이드에 스케줄러 이름과 SUNK 어노테이션을 설정하세요. 사용 가능한 어노테이션과 필요한 설정은 SUNK Pod Scheduler 인테그레이션을 참조하세요.

CLI
curl

overrides.yaml

spec:
  overrides:
    node_selector:
      node-pool: system
    tolerations:
      - key: dedicated
        operator: Equal
        value: system
        effect: NoSchedule

cwic sandbox runner edit prod-us-east-1 -f overrides.yaml

러너를 특정 Node Pool에 고정하기

curl -X PATCH "https://api.coreweave.com/v1/sandbox/managedRunners/prod-us-east-1?updateMask=spec.overrides" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "identity": { "runnerId": "prod-us-east-1" },
    "spec": {
      "overrides": {
        "nodeSelector": { "node-pool": "system" },
        "tolerations":  [ { "key": "dedicated", "operator": "Equal", "value": "system", "effect": "NoSchedule" } ]
      }
    }
  }'

예시: 특권 프로필 보안 설정 허용

allow_privileged_profile_annotations는 러너에 바인딩된 기존 프로필 템플릿에 특권 보안 설정을 허용할지 제어합니다. 정책 대신 프로필 바인딩을 여전히 사용하는 러너에 적용되므로 요청은 v1beta2 API로 전송됩니다. 기본값은 false이며, 이 플래그가 설정되지 않은 러너에서는 특권 보안 설정을 포함한 템플릿이 거부됩니다. 이름과 달리 이 플래그는 두 가지 유형의 콘텐츠를 제어합니다.

권한 있는 파드 어노테이션으로, 런타임 및 스케줄러 접두사를 의미합니다.
serviceAccountName, 호스트 namespace, hostPath 볼륨, 권한 있는 컨테이너 또는 권한 상승이 가능한 컨테이너와 같은 권한 있는 구조화된 파드 사양 필드.

러너가 거부하는 템플릿은 permission_denied를 반환하고 문제가 되는 필드를 명시합니다. 예를 들어, securityContext.appArmorProfile과 securityContext.seccompProfile을 설정하는 템플릿은 다음과 같이 실패합니다.

Example output

Error: updating runner: permission_denied: profile_bindings[7]: template
"[TEMPLATE-ID]" contains privileged pod-spec fields
[securityContext.appArmorProfile securityContext.seccompProfile];
runner does not have allow_privileged_profile_annotations=true

템플릿을 거부한 러너에 플래그를 설정하세요. 이 플래그는 하나의 러너에만 적용되므로, 특권 보안 설정이 필요한 각 러너에 대해 이 작업을 반복하세요.

CLI
curl

echo 'managed_spec: {allow_privileged_profile_annotations: true}' \
  | cwic sandbox runner edit prod-us-east-1 -f -

Allow a privileged profile posture on one runner

curl -X PATCH https://api.coreweave.com/v1beta2/sandbox/managed-runners/prod-us-east-1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "runner": {
      "id": "prod-us-east-1",
      "managedSpec": { "allowPrivilegedProfileAnnotations": true }
    },
    "updateMask": "managedSpec.allowPrivilegedProfileAnnotations"
  }'

업데이트가 성공하면 거부된 프로필 템플릿을 다시 적용하세요.

이 플래그를 설정하면 호스트 리소스 접근을 포함하여 러너의 샌드박스가 수행할 수 있는 작업 범위가 확대됩니다. 특권 보안 설정이 필요한 러너에만 설정하세요.

필요 시 러너 업데이트 트리거

러너의 updateAvailable이 true이면 다음 유지 관리 창까지 기다리지 않고 업데이트를 즉시 적용할 수 있습니다:

CLI
curl

cwic sandbox runner upgrade prod-us-east-1

사용 가능한 업데이트 즉시 적용

curl -X POST https://api.coreweave.com/v1/sandbox/managedRunners/prod-us-east-1:applyAvailableUpdate \
  -H "Authorization: Bearer $TOKEN"

컨트롤 플레인은 러너의 릴리스 채널에서 최신 버전을 확인하고 target_revision을 갱신합니다. 클러스터 내 컨트롤러가 이를 배포합니다.

러너 목록 조회

조직의 모든 러너를 확인하거나 특정 존, 클러스터 또는 연결 상태로 범위를 좁혀 보려면 다음 목록 명령어를 사용하세요.

CLI
curl

cwic sandbox runner get

존, 클러스터 또는 연결 상태로 필터링하세요.

cwic sandbox runner get --zone us-east-1
cwic sandbox runner get --connection-status CONNECTED

관리형 러너 목록 조회

curl -H "Authorization: Bearer $TOKEN" \
  'https://api.coreweave.com/v1/sandbox/managedRunners?pageSize=50&zone=us-east-1'

지원되는 쿼리 매개변수: zone, clusterId, connectionStatus, runnerId, managementMode, pageSize(기본값 50, 최대 100), pageToken. 페이지 매김은 커서 기반입니다.

러너 삭제

클러스터에서 더 이상 샌드박스 용량이 필요하지 않거나 같은 클러스터에 새 러너를 다시 배포하기 전에 러너를 제거하세요.

CLI
curl

cwic sandbox runner delete prod-us-east-1

CLI에서 확인을 요청합니다. 스크립트에서 사용할 때 확인 요청을 건너뛰려면 --yes를 전달하세요:

cwic sandbox runner delete prod-us-east-1 --yes

Decommission a runner

curl -X DELETE https://api.coreweave.com/v1/sandbox/managedRunners/prod-us-east-1 \
  -H "Authorization: Bearer $TOKEN"

러너를 삭제하면 클러스터에서 러너 배포가 제거됩니다. 해당 러너에서 실행 중인 모든 샌드박스가 중지됩니다. 정책은 러너의 일부이므로 함께 삭제됩니다. 클러스터를 다시 배포할 계획이라면 정책 문서를 버전 관리 시스템에 보관하세요.

삭제는 영구적입니다. 트래픽을 일시 중지하기만 하려면 이 러너를 삭제하기 전에 샌드박스를 다른 러너로 이동하세요.

참고 항목

노드 할당 예산 설정: Node Pool 또는 노드 그룹별로 샌드박스의 CPU 및 메모리 요청량을 제한합니다.
샌드박스 아키텍처: 리소스 모델, 컨트롤 플레인과 데이터 플레인 비교, 다중 클러스터 토폴로지를 설명합니다.
정책 개요: 샌드박스에 정책이 적용되는 방식을 설명합니다.
샌드박스 정책 설정: 모든 제약 조건 그룹을 구체적인 예시와 함께 설명합니다.
컨트롤 플레인 API 개요: 인증, 필드 마스크, 모든 엔드포인트의 요청 및 응답 구조를 설명합니다.
정책 레퍼런스: 정책에서 설정할 수 있는 모든 필드를 설명합니다.

샌드박스

샌드박스 사용하기

샌드박스 관리

레퍼런스

Deploy and manage a runner

시작하기 전에

러너 명령어

러너 배포

일반적인 검증 오류

러너 상태 확인

러너 업데이트

일반적인 러너 업데이트

예시: 릴리스 채널 전환

예시: 정책 교체

예시: 배포 오버라이드로 노드 배치 고정하기

예시: 특권 프로필 보안 설정 허용

필요 시 러너 업데이트 트리거

러너 목록 조회

러너 삭제

참고 항목

​시작하기 전에

​러너 명령어

​러너 배포

​일반적인 검증 오류

​러너 상태 확인

​러너 업데이트

​일반적인 러너 업데이트

​예시: 릴리스 채널 전환

​예시: 정책 교체

​예시: 배포 오버라이드로 노드 배치 고정하기

​예시: 특권 프로필 보안 설정 허용

​필요 시 러너 업데이트 트리거

​러너 목록 조회

​러너 삭제

​참고 항목

시작하기 전에

러너 명령어

러너 배포

일반적인 검증 오류

러너 상태 확인

러너 업데이트

일반적인 러너 업데이트

예시: 릴리스 채널 전환

예시: 정책 교체

예시: 배포 오버라이드로 노드 배치 고정하기

예시: 특권 프로필 보안 설정 허용

필요 시 러너 업데이트 트리거

러너 목록 조회

러너 삭제

참고 항목