Sandbox SDK — 안정 패키지
Cloudflare Containers에서 Worker를 통해 구동되는 격리된 Linux 환경입니다.
주요 Sandbox 문서와 설치된 안정 타입을 기억보다 우선하세요. 이 기술은 게이트, 계약, 검색 맵 역할을 할 뿐, 완전한 매뉴얼이 아닙니다.
이 라인은 현재 안정(stable) 기본 npm 패키지입니다. 주요 Sandbox 문서에서 설명합니다. 기존 앱은 여기에 머물며 계속 출시할 수 있습니다.
새 프로젝트는 @cloudflare/sandbox@next와 sandbox-next 를 권장합니다. 가능할 때 sandbox-migrate-to-next 로 이동 계획을 세워 1.0이 안정 릴리스가 될 때 준비하세요. 사용자가 요청하지 않는 한 포팅을 강제하지 마십시오.
1. 게이트 — 패키지 라인 확인
코드를 작성하기 전에 앱을 검사하세요.
| 확인 항목 | 일치 조건 |
|---|---|
| npm 의존성 | 기본 @cloudflare/sandbox (@next / preview 태그 아님) |
| 컨테이너 이미지 | 일치하는 안정 이미지 (cloudflare/sandbox:next 아님) |
| 발견한 경우… | 조치 |
|---|---|
@cloudflare/sandbox@next 또는 next 이미지 | 중단. sandbox-next 를 로드하세요. |
사용자가 1.0 / @next로 포팅하려 함 | 중단. sandbox-migrate-to-next 를 로드하세요. 안정 패키지에 미리보기 API를 반만 적용하지 마십시오. |
| 더 이상 사용되지 않는 안정 API만 정리 | 여기에 머물고 2026 지원 중단 가이드를 사용하세요. 이는 @next로의 이동이 아닙니다. |
안정 Worker 패키지와 @next 컨테이너 이미지를 절대 혼용하지 마십시오 (또는 그 반대).
기술 설치: Agent 설정 · cloudflare/skills
2. 계약 — 비협상 조건
await sandbox.exec(command)는 명령 문자열을 받고 명령이 완료될 때 해결되며, 버퍼링된stdout/stderr/exitCode(및 관련 필드)를 반환합니다.- 장기 실행 및 스트리밍 작업은 안정 명령 API(
startProcess,execStream및 관련 헬퍼)를 사용합니다.@next단일 핸들 모델을 사용하지 마십시오. 명령 문서를 열고 안정 버전에서@nextoutput()핸들을 발명하지 마십시오. - 세션은 명령 간에 작업 디렉터리와 환경을 보존할 수 있습니다 (기본 세션 /
enableDefaultSession,createSession). 상태가 호출 간에 전달되어야 하는 경우 세션 문서를 참조하세요. - 대화형 브라우저 터미널은 종종 안정 버전에서
sandbox.terminal(request)와 세션/xterm 헬퍼를 사용합니다. 패키지가@next가 아닌 이상 미리보기createTerminal을 사용하지 마십시오. - 터널 또는 대용량/바이너리 스트리밍을 사용할 때는 RPC 전송을 선호하세요. HTTP/WebSocket 전송은 지원이 중단되었습니다 (아래 정리 가이드 참조).
- 파일, 마운트, 포트, 터널, 백업, 라이프사이클, 인터프리터: 주요 문서에서 시그니처를 확인하고 설치된 안정 타입을 신뢰하세요.
- 비밀은 Sandbox 환경에 넣지 말고 Worker에 라이브 자격 증명을 두세요. 프로세스가 외부 API를 호출할 때는 아웃바운드 핸들러를 사용하세요.
- 프로덕션 미리보기 호스트 이름은 해당 URL 패턴을 사용할 때 사용자 정의 도메인에 와일드카드 DNS가 필요합니다.
- 의존성이 여전히 안정인 동안은
@nextargv/process.output()API를 적용하지 마십시오. - 자체 배포 브릿지는 안정 패키지와 이미지를 유지합니다. 브릿지
최소 형태:
import { getSandbox, proxyToSandbox, Sandbox } from "@cloudflare/sandbox";
export { Sandbox };
const sandbox = getSandbox(env.Sandbox, "user-123");
const result = await sandbox.exec('python3 -c "print(2 + 2)"');
// result.stdout, result.exitCode, result.success
3. 검색 — 작업에 맞는 문서 열기
구현하기 전에 페이지를 가져오세요. 설치된 안정 타입이 추측보다 우선합니다.
| 필요한 작업… | 열기 |
|---|---|
| 방향 설정 | Sandbox 개요 |
| 첫 Worker, 템플릿, Docker | 시작하기 |
exec, 스트리밍, 백그라운드 프로세스 | 명령 API · 명령 실행 · 백그라운드 프로세스 · 스트리밍 출력 |
| 명령 간 세션/쉘 상태 | 세션 개념 · 세션 API |
getSandbox 옵션, 절전, 삭제 | 라이프사이클 API · Sandbox 옵션 |
| 환경 변수 | 환경 변수 |
| 파일 | 파일 API · 파일 관리 · 파일 감시 |
| 버킷/마운트 | 스토리지 API · 버킷 마운트 |
| 백업 | 백업 API · 백업 및 복원 |
| 포트, 미리보기 URL, 노출 | 포트 API · 서비스 노출 |
| 터널 | 터널 API |
| 프록시/Worker 연결 | 프록시 요청 · Worker 연결 |
| 브라우저/PTY 터미널 | 터미널 API · 터미널 개념 · 브라우저 터미널 |
| 코드 인터프리터 | 인터프리터 API · 코드 실행 |
| Sandbox 내 Git | Git 워크플로우 |
| 비밀/이그레스 | 아웃바운드 트래픽 |
| WebSocket | WebSocket 연결 |
| Docker-in-Docker | Docker in Docker |
| 프로덕션 배포 | 프로덕션 배포 |
| 컨테이너 개념 | 컨테이너 |
| 방법 가이드 인덱스 | 가이드 |
| API 인덱스 | API 참조 |
| 안정 상태 유지하며 지원 중단된 API | 2026 지원 중단 가이드 |
| 자체 배포 브릿지 | 브릿지 · 브릿지 HTTP API |
예제 (stable/main) | GitHub의 예제 |
| 1.0 미리보기 새 작업 | sandbox-next · 1.0 미리보기 |
기존 앱을 @next로 포팅 | sandbox-migrate-to-next · 마이그레이션 |
지원 중단된 API 정리 (안정 상태 유지)
먼저 패키지와 일치하는 이미지를 업데이트한 다음 가이드를 따르세요. 일반적인 검색:
rg 'SANDBOX_TRANSPORT|transport:|exposePort\(|enableDefaultSession|execStream\(|readFileStream|writeFileStream'
이 경로는 @next로 전환하지 않습니다.
4. 출시 전 확인
- Worker 패키지와 컨테이너 이미지가 동일한 안정 라인에 있어야 함
- 설치된 안정 타입에 대해 타입 검사 수행
- Sandbox 환경에 라이브 비밀 없음
- 지원 중단된 전송/헬퍼를 사용하는 경우 2026 지원 중단 정리 완료 또는 추적
- 팀이 1.0에 준비되면
sandbox-migrate-to-next를 사용하세요. 요청 없이 강제 전환하지 마십시오.