Sandbox SDK — @next (1.0 프리뷰)
Cloudflare Containers 위의 격리된 Linux 환경으로, Workers에서 구동됩니다.
프리뷰 문서와 설치된 @next 타입을 메모리보다 우선시하세요. API는 변경됩니다. 이 스킬은 게이트, 계약, 그리고 검색 맵입니다—전체 매뉴얼이 아닙니다.
새 프로젝트는 이 라인을 권장합니다. 기본 패키지를 사용하는 앱은 sandbox-stable 을 사용하세요. sandbox-migrate-to-next 를 통해 요청 시에만 포팅하세요.
1. 게이트 — 패키지 라인 확인
코드를 작성하기 전에 앱을 검사하세요:
| 확인 | 일치해야 하는 값 |
|---|---|
| npm 의존성 | @cloudflare/sandbox@next (또는 다른 프리뷰 태그) |
| 컨테이너 이미지 | 동일한 라인 (예: cloudflare/sandbox:next, next-python) |
| 찾은 내용… | 조치 |
|---|---|
기본 @cloudflare/sandbox (@next 없음) | 중지. sandbox-stable 을 로드하세요. 이 스킬의 API를 적용하지 마세요. |
사용자가 안정 → @next로 포팅하려 함 | 중지. sandbox-migrate-to-next 를 로드하세요. |
| 자체 배포 브리지 만 | 브리지는 아직 1.0 프리뷰 라인에 없습니다. 브리지는 안정 패키지 + 이미지를 유지하세요. 브리지(안정) |
@next Worker 패키지와 안정 컨테이너 이미지를 절대 혼용하지 마세요. (또는 그 반대)
스킬 설치: 에이전트 설정 · cloudflare/skills
2. 계약 — 절대 타협하지 않는 사항
sandbox.exec(argv)는 argv 리스트를 받아 프로세스가 시작되면 resolve됩니다. 완료된 명령 결과가 아닌 핸들을 반환합니다.- 핸들 메서드로 결과를 수집:
output(),logs(),waitForExit(),waitForPort(),waitForLog(),kill(signal?). - 암시적 셸 없음. 셸 구문은 명시적 셸이 필요합니다. 예:
["/bin/bash", "-lc", script]. - 각 실행은 독립적입니다. 한
exec에서의cd/export는 다음 실행에 영향을 주지 않습니다. 실행마다cwd와env를 전달하거나, 하나의 셸 스크립트를 사용하세요. - 프로세스 핸들에는 표준 입력(stdin)이 없습니다. 대화형 사용 → 터미널 (
createTerminal+connect). - 로컬 대기
timeout/AbortSignal은 대기만 취소합니다. 프로세스를 종료하지는 않습니다.kill또는exec의 원격timeout을 사용하세요. getProcess/listProcesses/getTerminal/listTerminals는 컨테이너를 시작하지 않으며, 실행 중인 것이 없으면null/[]을 반환합니다.- 프로세스 및 터미널 ID는 현재 컨테이너에 속하며, 샌드박스 ID에 영구적으로 속하지 않습니다. 교체에도 유지되어야 하는 작업의 경우 ID만 저장하지 말고 전체 작업(argv, cwd, env, 앱 상태)을 저장하세요.
setEnvVars/ 실행env에는 비밀 아닌 구성만 포함하세요. 실시간 자격 증명은 Worker에 유지하고, 샌드박스가 외부 API를 호출할 때는 아웃바운드 핸들러를 사용하세요.- 제거된 안정 API를 발명하지 마세요 (
gitCheckout코어, 문자열exec완료, 세션 실행,sandbox.terminal(request)). - 모든 오류에 하나의 재시도 루프를 사용하지 마세요 (Errors 문서 참조).
최소 형태:
import { getSandbox, proxyToSandbox, Sandbox } from "@cloudflare/sandbox";
export { Sandbox };
const sandbox = getSandbox(env.Sandbox, "user-123");
const process = await sandbox.exec(["python3", "-c", "print(2 + 2)"]);
const result = await process.output({ encoding: "utf8" });
// result.stdout, result.exitCode
작업별 API 문서: references/api-quick-ref.md
예제 인덱스 (next 브랜치): references/examples.md
3. 검색 — 작업에 대한 문서 열기
구현하기 전에 페이지를 가져오세요. 설치된 @next 타입이 추측보다 우선합니다.
| 필요한 작업… | 열기 |
|---|---|
| 방향 설정 / 프리뷰 선택 | 1.0 프리뷰 개요 |
| 첫 Worker, wrangler, Dockerfile | 시작하기 |
exec, 핸들, 준비 상태, 내구성 | 프로세스 실행 |
| 프로세스 API 시그니처 | 프로세스 API |
| 샌드박스 ID vs 컨테이너 vs 절전/파괴 | 수명주기 |
cwd / env / setEnvVars | 환경 |
| 대화형 PTY / 브라우저 터미널 | 터미널 · 터미널 API |
| Python/JS 코드 인터프리터 | 인터프리터 · 인터프리터 API |
| 확장 모델 | 확장 |
| 오류 클래스 및 복구 | 오류 · 오류 API |
| 일반적인 실패 | 문제 해결 |
| API 허브 | API 참조 |
파일, 마운트, 백업, 포트, 터널, proxyToSandbox | 공유 표면에 대한 기본 문서 (안정 전용 세션/전송/sandbox.terminal 무시): 파일 · 스토리지 / 마운트 · 포트 · 터널 · 백업 · 아웃바운드 트래픽 · 서비스 노출 · 프로덕션 |
| 예제 앱 | next의 예제 |
| 여전히 안정 패키지 사용 중 | sandbox-stable · 주요 Sandbox 문서 |
| 기존 안정 앱 포팅 | sandbox-migrate-to-next · 마이그레이션 |
4. 배송 전 확인
- 잠금 파일과 Dockerfile이 동일한
@next라인에 있어야 함 - 설치된
@next타입에 대해 타입 검사 수행 - 샌드박스 환경에 실시간 비밀 정보 없음
- 프로덕션 프리뷰 호스트네임은 해당 URL 패턴을 사용할 때 사용자 정의 도메인에 와일드카드 DNS가 필요함