장기 실행 샌드박스 실행하기

CoreWeave 샌드박스는 서버리스 배치와 CoreWeave Kubernetes Service(CKS) 배치 모두에서 최대 30일(2,592,000초) 동안 실행할 수 있습니다. 에이전트, 개발 환경 또는 배치 워크로드가 작업을 마칠 수 있는 충분한 시간을 확보하려면 샌드박스를 생성할 때 수명을 설정하세요. 이 가이드에서는 개발자를 위해 더 긴 수명을 요청하는 방법을, 관리자를 위해 CKS 러너에서 실행되는 샌드박스의 기본 수명을 설정하는 방법을 설명합니다.

인증 선택

이 예시는 별도로 CKS를 지정한 섹션을 제외하고 서버리스 용량에서 실행됩니다. 샌드박스를 소유한 계정의 사용자 인증 정보를 선택하세요. 키 또는 토큰을 획득하는 방법은 사용자 인증 정보 선택 및 가져오기를 참조하세요. 사용하는 언어에 맞는 설정 파일을 이 페이지의 스크립트를 실행하는 위치에 함께 저장하세요. Python 예시는 sandbox_auth.py에서 AUTH를 임포트하고, TypeScript 예시는 sandbox-client.mts에서 client를 임포트합니다. 이 파일들은 사용자 인증 정보를 저장하지 않고 인증 방식만 선택합니다. Python에서는 활성화된 가상 환경을 사용하세요. TypeScript에서는 먼저 npm install @coreweave/cwsandbox@1.0.0로 클라이언트를 설치하세요.

Forge API 키
CoreWeave API 액세스 토큰

SDK의 wandb 인테그레이션으로 Forge API 키를 사용하세요. [WANDB-API-KEY]를 API 키로 바꾸세요.

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

CoreWeave 조직의 토큰을 사용하세요. [API-ACCESS-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();

CKS에 배치하려면 CoreWeave 토큰을 선택하고 러너를 활성화한 다음, 샌드박스를 생성할 때 또는 SandboxDefaults에서 placement_mode="cks"를 설정하세요. TypeScript에서는 CoreWeave 토큰을 선택하고 runnerIds 배열을 비어 있지 않게 설정하면 CKS가 선택됩니다. auth=AUTH로 Python 세션을 생성하면 해당 세션이 소유한 샌드박스도 함께 인증됩니다. 샌드박스에 다시 연결하거나 목록을 조회하거나 정리할 때도 동일한 사용자 인증 정보를 사용하세요.

수명 선택

수명은 샌드박스를 실행할 수 있는 최대 시간입니다. 수명이 만료되면 작업이 아직 진행 중이더라도 플랫폼이 샌드박스를 종료합니다. 워크로드가 완료되거나 사용자가 샌드박스를 중지하면 그보다 일찍 종료될 수 있습니다.

설정	서버리스	CKS
샌드박스별 수명	소프트웨어 개발 키트(SDK) 또는 샌드박스 생성 요청에서 설정합니다.	SDK 또는 샌드박스 생성 요청에서 설정합니다.
러너 정책 기본값	CoreWeave에서 관리합니다.	Admin이 러너 정책에서 `constraints.lifecycle.default_lifetime_seconds`를 설정할 수 있습니다.
최대 수명	30일	자체 클러스터에서도 30일

명시적으로 지정한 수명이 러너 정책 기본값보다 우선합니다. 수명을 생략하면 플랫폼은 적용되는 정책 기본값을 사용합니다. 수명을 지정하는 양수 기본값이 없으면 플랫폼은 10분(600초)을 사용합니다. 장시간 실행되는 작업에는 기본값에 의존하지 말고 수명을 명시적으로 설정하세요. 플랫폼은 30일을 초과하는 요청을 거부합니다. 값을 0으로 지정해도 실행 시간이 무제한이 되지는 않습니다. CKS 정책으로도 플랫폼 최댓값을 늘릴 수 없습니다. 샌드박스가 시작된 후에는 수명을 연장할 수 없습니다. 생성 시 충분한 시간을 지정하고, 기한 전에 작업을 저장할 수 있도록 미리 계획하세요.

샌드박스 생성 시 수명 설정하기

Python에서는 max_lifetime_seconds를, TypeScript에서는 maxLifetimeSeconds를 사용하세요. 다음 예시는 최대 기간인 30일 전체를 요청하고, 나중에 다시 연결할 수 있도록 샌드박스 ID를 출력합니다. 사용하는 배치 모드에 해당하는 탭을 선택하세요. CKS를 사용하려면 CoreWeave 사용자 인증 정보와 설정된 러너가 필요합니다. [RUNNER-ID]를 해당 러너의 ID로 바꾸세요.

서버리스
CKS

from sandbox_auth import AUTH
from cwsandbox import Sandbox

sandbox = Sandbox.run(
    "sleep", "infinity",
    auth=AUTH,
    placement_mode="serverless",
    container_image="python:3.11",
    resources={"cpu": "2", "memory": "4Gi"},
    max_lifetime_seconds=30 * 24 * 60 * 60,
)
sandbox.wait()
print(sandbox.sandbox_id)

import { client } from "./sandbox-client.mts";

const sandbox = await client.run(["sleep", "infinity"], {
  containerImage: "python:3.11",
  resources: { cpu: "2", memory: "4Gi" },
  maxLifetimeSeconds: 30 * 24 * 60 * 60,
});
console.log(sandbox.sandboxId);

from cwsandbox import AuthStrategy, Sandbox

sandbox = Sandbox.run(
    "sleep", "infinity",
    auth=AuthStrategy.COREWEAVE_API_KEY,
    placement_mode="cks",
    runner_ids=["[RUNNER-ID]"],
    container_image="python:3.11",
    resources={"cpu": "2", "memory": "4Gi"},
    max_lifetime_seconds=30 * 24 * 60 * 60,
)
sandbox.wait()
print(sandbox.sandbox_id)

import { createSandboxClientFromEnv } from "@coreweave/cwsandbox/node";

const client = createSandboxClientFromEnv();
const sandbox = await client.run(["sleep", "infinity"], {
  runnerIds: ["[RUNNER-ID]"],
  containerImage: "python:3.11",
  resources: { cpu: "2", memory: "4Gi" },
  maxLifetimeSeconds: 30 * 24 * 60 * 60,
});
console.log(sandbox.sandboxId);

스크립트가 샌드박스 ID를 출력합니다. 이 예시에서는 sleep infinity로 주 프로세스를 계속 실행 상태로 유지하므로, 스크립트가 종료된 후에도 샌드박스는 계속 실행됩니다. 샌드박스를 다 사용했으면 중지하세요. 다른 클라이언트 인터페이스에서도 동일하게 수명을 설정할 수 있습니다.

인터페이스	수명 설정
Python SDK	`Sandbox.run(max_lifetime_seconds=2592000, ...)`. 공유 클라이언트 기본값을 지정하려면 `SandboxDefaults(max_lifetime_seconds=2592000)`를 사용하세요. 인수를 명시적으로 전달하면 클라이언트 기본값이 재정의됩니다.
TypeScript SDK	`client.run()`의 옵션에 `maxLifetimeSeconds: 2592000`을 전달하세요.
REST API	`POST /v1/sandboxes`의 JSON 본문에서 `spec.maxLifetimeSeconds`를 `2592000`으로 설정하세요.
Compose 파일 임포트	`POST /v1/sandboxes:createFromFile`에서 최상위 요청 필드 `maxLifetimeSeconds`를 `2592000`으로 설정하세요. 수명은 Compose 서비스 속성이 아닌 요청 설정입니다.

전체 요청 형식은 API 참조 및 Compose 파일로 샌드박스 생성하기를 참조하세요. Python 클라이언트 기본값은 샌드박스 구성을 참조하세요.

CKS 러너의 기본값 설정

러너 정책 기본값은 수명을 직접 요청하지 않는 새 샌드박스에 적용됩니다. CKS 러너의 워크로드에 일반적으로 더 긴 수명을 부여해야 할 때 이 방법을 사용하세요. 정책을 편집하려면 sandbox_admin ID 및 액세스 관리(IAM) 액션이 필요합니다. 정책을 업데이트하면 정책 문서 전체가 대체됩니다. 아래 발췌본을 기존 정책 대신 그대로 제출하지 마세요. 그렇게 하면 기존 정책의 다른 제약 조건이 제거됩니다.

대화형 터미널에서 인증된 CoreWeave Intelligent CLI로 러너의 현재 정책을 여세요.
cwic sandbox runner policy edit [RUNNER-ID]
constraints.lifecycle.default_lifetime_seconds를 원하는 초 단위 값으로 설정하세요. 다음 YAML은 기본값을 30일로 설정한 발췌본입니다. 기존 정책의 나머지 부분은 그대로 유지하세요.
러너 정책 발췌본
constraints: lifecycle: default_lifetime_seconds: 2592000
저장하고 편집기를 닫으면 업데이트가 제출됩니다. 정책을 조회하여 값을 확인하세요.
cwic sandbox runner policy get [RUNNER-ID]

관리형 러너 REST API로도 정책을 업데이트할 수 있습니다. JSON에서는 해당 필드가 policy.constraints.lifecycle.defaultLifetimeSeconds입니다. 조회, 편집, 대체의 전체 절차는 정책 업데이트를 참조하세요. 기본값은 업데이트 이후에 생성된 샌드박스에만 적용되며, 이미 실행 중인 샌드박스의 수명은 연장되지 않습니다. 샌드박스는 최대 30일 이내에서 다른 수명을 명시적으로 요청할 수 있습니다. 정책에 max_lifetime_seconds를 추가하지 마세요. 이 필드는 서비스 종료되었으며, CoreWeave Intelligent CLI는 이 필드가 포함된 정책 문서를 거부합니다. 기본값은 정책이 제공하고, 최댓값은 플랫폼이 강제 적용합니다.

클라이언트 세션 간에 작업 이어가기

샌드박스를 실행한 Python script가 종료된 후에도 샌드박스를 유지해야 한다면, 앞의 예시처럼 독립형 샌드박스를 생성하세요. with Sandbox.run(...) 컨텍스트를 사용하면 수명이 30일로 설정되어 있더라도 블록을 벗어나는 즉시 샌드박스가 중지됩니다. Session 역시 자신이 소유한 샌드박스의 정리 작업을 관리합니다. 자세한 내용은 정리 패턴을 참조하세요. TypeScript에서는 client.run()으로 실행한 샌드박스는 계속 실행 상태로 유지되지만, client.withSandbox()를 사용하면 callback이 종료될 때 샌드박스가 중지됩니다. 다른 스크립트에서 다시 연결하려면 [SANDBOX-ID]를 생성 시 출력된 ID로 바꾸세요. 이때 샌드박스를 생성할 때와 동일한 사용자 인증 정보를 사용해야 합니다. sandbox_auth.py 또는 sandbox-client.mts 설정도 생성 시와 동일하게 유지하세요.

from sandbox_auth import AUTH
from cwsandbox import Sandbox

sandbox = Sandbox.from_id(
    "[SANDBOX-ID]",
    auth=AUTH,
).result()
result = sandbox.exec(["echo", "Connected"]).result()
print(result.stdout)

import { client } from "./sandbox-client.mts";

const sandbox = await client.fromId("[SANDBOX-ID]");
const result = await sandbox.commands.run(["echo", "Connected"]);
console.log(result.stdout);

이 명령어는 Connected를 출력합니다. 다시 연결해도 수명은 재설정되지 않습니다. 작업을 마치면 다음과 같이 샌드박스를 명시적으로 중지하세요.

from sandbox_auth import AUTH
from cwsandbox import Sandbox

sandbox = Sandbox.from_id(
    "[SANDBOX-ID]",
    auth=AUTH,
).result()
sandbox.stop().result()

import { client } from "./sandbox-client.mts";

const sandbox = await client.fromId("[SANDBOX-ID]");
await sandbox.stop();

만료에 대비하기

샌드박스 수명이 만료되기 전에 결과나 체크포인트를 샌드박스 외부에 저장하세요. 워크플로에 30일 넘게 걸린다면 대체 샌드박스를 생성한 후 저장된 상태에서 재개하세요. 지원되는 저장소 및 스냅샷 옵션은 샌드박스 볼륨 및 파일 시스템 스냅샷을 참조하세요. 샌드박스 수명은 명령어나 API 요청의 timeout과는 별개입니다. timeout_seconds 또는 request_timeout_seconds를 늘려도 샌드박스 수명은 연장되지 않습니다. 둘의 차이는 Timeouts를 참조하세요.

샌드박스

샌드박스 사용하기

샌드박스 관리

레퍼런스

장기 실행 샌드박스 실행하기

인증 선택

수명 선택

샌드박스 생성 시 수명 설정하기

CKS 러너의 기본값 설정

클라이언트 세션 간에 작업 이어가기

만료에 대비하기

​인증 선택

​수명 선택

​샌드박스 생성 시 수명 설정하기

​CKS 러너의 기본값 설정

​클라이언트 세션 간에 작업 이어가기

​만료에 대비하기

인증 선택

수명 선택

샌드박스 생성 시 수명 설정하기

CKS 러너의 기본값 설정

클라이언트 세션 간에 작업 이어가기

만료에 대비하기