샌드박스 이해하기(Vercel)

https://vercel.com/docs/sandbox/concepts

Vercel 샌드박스는 신뢰할 수 없는 코드를 실행하고, 애플리케이션을 테스트하고, AI가 생성한 스크립트를 실행하는 등의 용도로 필요할 때 바로 쓸 수 있는 격리된 컴퓨팅 환경을 제공합니다. 샌드박스는 기본적으로 상태를 유지합니다. 샌드박스가 멈추면 SDK가 파일 시스템을 자동으로 스냅샷으로 남기고 샌드박스 설정도 세션 사이에 보존하므로, 다음에 다시 시작할 때 둘 다 복원됩니다.

샌드박스란 무엇인가

샌드박스는 SDK나 CLI로 프로그래밍 방식으로 만드는 격리된 리눅스 환경입니다. 다음과 같은 보안 가상 머신이라고 생각하면 됩니다.

Vercel 관리형 이미지나 직접 만든 VCR 이미지, 또는 저장해 둔 스냅샷에서 부팅합니다.
Ubuntu와 Arch Linux, 그 밖에 필요한 어떤 리눅스 배포판이든 씁니다.
패키지를 설치하고 API를 호출할 수 있는 네트워크 접근이 가능합니다.
설정할 수 있는 타임아웃이 지나면 자동으로 멈춥니다.
어떤 패키지나 바이너리든 설치할 수 있는 전체 root 권한을 제공합니다.

샌드박스마다 다음과 같이 설정할 수 있는 격리가 포함됩니다.

파일 시스템 접근: 전용 개인 파일 시스템을 갖습니다. 영속성이 켜져 있으면(기본값) 샌드박스가 멈출 때 파일 시스템이 자동으로 스냅샷으로 저장되고 다시 시작할 때 복원됩니다. 샌드박스 설정은 세션 사이에 보존되어 다시 시작할 때 그대로 적용됩니다.
프로세스 격리: 커널 수준 격리를 통해 코드가 다른 샌드박스의 프로세스를 보거나 접근할 수 없게 합니다.
네트워크 격리: 샌드박스마다 자체 네트워크 네임스페이스를 갖고, 아웃바운드 접근이 통제됩니다.

샌드박스와 컨테이너의 차이

도커 컨테이너와 달리 샌드박스는 각각 전용 커널을 가진 자체 Firecracker 마이크로VM에서 돌아갑니다. 컨테이너 기반 방식보다 격리가 강하기 때문에, 신뢰할 수 없는 코드를 실행하는 데 샌드박스가 알맞습니다.

항목	도커 컨테이너	Vercel 샌드박스
격리	호스트 커널을 공유하며 네임스페이스와 cgroups에 의존	샌드박스마다 전용 커널을 두는 완전한 VM 격리
보안	신뢰할 수 있는 코드에 적합하며 컨테이너 탈출이 일어날 수 있음	신뢰할 수 없는 코드를 위해 설계되었고 마이크로VM 경계가 탈출을 막음
시작 시간	1초 미만	밀리초 단위(빠른 부팅에 최적화된 Firecracker)
용도	애플리케이션을 패키징하고 배포	임의의 신뢰할 수 없는 코드를 안전하게 실행

이미 도커 이미지로 환경을 정의하고 있다면, 그 이미지를 Vercel Container Registry(VCR)에 저장하고 커스텀 이미지로 샌드박스를 만드세요. 이미지 문서를 참고하면 됩니다. 시스템 패키지 관리자로 패키지를 설치할 수도 있고, 도커 이미지가 필요하지 않다면 설정을 마친 뒤 스냅샷을 남기는 방법도 있습니다.

샌드박스의 동작 방식

Sandbox.create()를 호출하면 Vercel이 자체 인프라에 Firecracker 마이크로VM을 프로비저닝합니다. 이 마이크로VM은 Ubuntu 26.04 이미지나 VCR에 있는 커스텀 이미지, 또는 저장해 둔 스냅샷으로 부팅합니다.

샌드박스는 Vercel 인프라에서 돌아가므로 서버를 관리하거나 용량을 확장하거나 가용성을 걱정할 필요가 없습니다. 샌드박스는 기본적으로 iad1 리전에 프로비저닝됩니다. 샌드박스마다 다른 리전을 고르거나 프로젝트 기본값을 설정할 수 있습니다. 리전을 참고하세요.

수명 주기 동안 일어나는 일은 다음과 같습니다.

프로비저닝: Vercel이 컴퓨팅 리소스를 할당하고 마이크로VM을 부팅합니다. 스냅샷에서 다시 시작하는 것은 새 샌드박스를 시작하는 것보다도 빠릅니다.
실행: 코드가 세션 안에서 실행됩니다. 세션은 샌드박스 안에서 돌아가는 하나의 VM 인스턴스입니다. 명령을 실행하고, 패키지를 설치하고, 서버를 띄우고, 파일 시스템을 다룰 수 있습니다.
정지: 타임아웃이 끝나거나 stop()을 호출하면 세션이 종료됩니다. 영속 샌드박스(기본값)라면 SDK가 파일 시스템을 자동으로 스냅샷으로 남겨 다음 세션이 같은 상태에서 이어집니다. 영속이 아닌 샌드박스라면 파일 시스템은 버려집니다.
재시작: 멈춰 있는 영속 샌드박스에 runCommand나 writeFiles 같은 SDK 호출이 들어오면 가장 최근 스냅샷에서 새 세션이 시작됩니다. 직접 재시작할 필요는 없습니다.

파일 시스템에 두기에 적절하지 않은 데이터를 오래 보관해야 한다면, 데이터베이스나 오브젝트 스토리지 같은 외부 서비스에 쓰세요.

샌드박스 수명 주기

샌드박스 만들기

샌드박스를 쓸 준비가 되면 처음부터 새로 만들 수도 있고, 전에 만들어 저장해 둔 스냅샷을 쓸 수도 있습니다. 스냅샷을 쓰면 의존성을 다시 설치하고 설정 단계를 반복하지 않아도 되므로 처음부터 만드는 것보다 훨씬 빠릅니다.

새로 설치한 운영체제를 부팅하는 것과 저장해 둔 상태에서 이어 시작하는 것의 차이라고 생각하면 됩니다. 새 샌드박스는 깨끗한 백지를 주고, 스냅샷은 설정이 끝나 바로 쓸 수 있는 환경을 줍니다.

샌드박스는 프로젝트 안에서 고유한 이름으로 식별됩니다. 이름을 주지 않으면 SDK가 대신 만들어 줍니다. 나중에 Sandbox.get()이나 Sandbox.getOrCreate()에 같은 이름을 넘겨서 그 샌드박스를 다시 시작하세요.

샌드박스를 만들 때는 CLI나 JS SDK, 파이썬 SDK를 쓸 수 있습니다.

# 임의의 이름으로 샌드박스 만들기
sandbox create

# 이름을 지정해서 만들기
sandbox create --name my-sandbox

명령 실행하기

샌드박스를 만든 뒤에는 그 안에서 명령을 실행할 수 있습니다. 명령은 완료를 기다리는 블로킹 모드로도, 곧바로 반환되는 분리 모드(detached)로도 실행할 수 있습니다.

# 이미 있는 샌드박스에서 이름으로 명령 실행
sandbox exec my-sandbox -- npm install

# 대화형으로 실행
sandbox exec --interactive --tty my-sandbox -- bash

# 환경 변수와 함께 실행
sandbox exec --env DEBUG=true my-sandbox -- npm test

샌드박스 멈추기

샌드박스는 타임아웃이 지나면 자동으로 멈춥니다. 기본 타임아웃은 5분이고, 최대값은 샌드박스 자체가 아니라 세션 하나하나에 적용됩니다. 샌드박스는 다시 시작한 횟수만큼 여러 세션에 걸쳐 존재합니다. 일주일 동안 하루에 한 번씩 다시 시작한 에이전트 작업 공간은 샌드박스 하나에 세션 일곱 개입니다.

직접 멈출 수도 있습니다. stop()은 VM이 완전히 멈춘 뒤에 완료되며 마지막 세션 상태를 반환합니다. 영속 샌드박스라면 반환값에 종료 중에 캡처한 스냅샷의 메타데이터도 함께 들어 있습니다.

sandbox stop my-sandbox

Vercel 대시보드에서 Observability > Sandboxes로 이동해 Stop Sandbox를 눌러 멈출 수도 있습니다.

스냅샷 남기기

스냅샷은 설치된 패키지와 파일을 포함해 샌드박스의 현재 상태를 저장합니다. 스냅샷을 쓰면 다음 실행에서 설정 시간을 건너뛰고, 오래 걸리는 작업에 체크포인트를 남기고, 팀원과 환경을 공유할 수 있습니다.

스냅샷을 만들고 가져오고 관리하는 방법에 대한 전체 문서는 스냅샷을 참고하세요.

주요 사용 사례

Vercel 샌드박스는 안전하면서 필요할 때 바로 쓸 수 있는 코드 실행이 필요한 기능에 알맞습니다.

패턴	왜 샌드박스를 쓰는가	예시
AI 코드 인터프리터	LLM이 생성한 코드는 예측하기 어렵습니다. 샌드박스는 그 코드가 격리된 채로 실행되게 합니다.	파이썬 스크립트를 작성해 실행하며 수학 문제를 푸는 AI 어시스턴트.
깨끗한 테스트 환경	테스트를 돌릴 때마다 새로 시작해서 "내 컴퓨터에서는 되는데" 문제를 피합니다.	커밋마다 깨끗한 운영체제에서 단위 테스트를 실행.
재현 가능한 인프라	똑같은 환경 스냅샷을 팀끼리 공유합니다.	고객 환경을 그대로 복제해 띄우는 QA 팀.
임시 디버깅	위험 없이 문제를 들여다볼 수 있는 일회용 환경을 띄웁니다.	환경을 복제해서 프로덕션 문제를 조사.

샌드박스를 쓰지 않아야 할 때

샌드박스는 계속 돌아가도록 설계된 것이 아닙니다. 다음 용도에는 적합하지 않습니다.

상시 호스팅: 하루 24시간 계속 떠 있는 서버가 필요하다면 전통적인 VM이나 Vercel Functions를 쓰세요.
대용량 데이터셋의 장기 저장: 영속 샌드박스의 파일 시스템은 세션 사이에 유지되지만, 데이터베이스나 오브젝트 스토어를 대신하지는 못합니다. 크거나 여러 곳에서 공유하는 데이터는 외부 서비스로 보내세요.

보안 모델

Vercel 샌드박스는 신뢰할 수 없는 코드를 안전하게 실행하도록 설계되었습니다.

격리 구조

샌드박스는 각각 전용 커널을 가진 자체 Firecracker 마이크로VM에서 돌아갑니다. 그래서 시스템 수준 권한이 필요한 프로세스를 다른 샌드박스나 호스트에 영향을 주지 않고 실행할 수 있습니다. 이런 워크로드는 sudo로 실행되며 마이크로VM 경계에 의해 해당 샌드박스 안으로 격리됩니다.

지원하는 워크로드는 다음과 같습니다.

컨테이너 런타임: 샌드박스 안에서 도커나 다른 컨테이너 엔진을 실행해 이미지를 빌드하거나 컨테이너 워크로드를 돌릴 수 있습니다.
VPN 클라이언트: VPN 제공자에 연결해 세션 동안 사설 네트워크에 접근할 수 있습니다.
FUSE 파일 시스템: FUSE(Filesystem in Userspace) 드라이버를 마운트해 오브젝트 스토리지나 네트워크 파일 시스템, 그 밖의 커스텀 마운트를 붙일 수 있습니다.

이 프로세스들은 상위 권한이 필요하므로 sudo로 실행하세요. 예를 들어 CLI에서 상위 권한으로 명령을 실행하려면 이렇게 합니다.

sandbox exec --sudo <name> -- <command>

이런 워크로드에서 나가는 아웃바운드 네트워크 접근도 샌드박스 방화벽의 네트워크 정책을 따릅니다. 신뢰할 수 없는 코드를 실행할 때는 네트워크 정책으로 접근할 수 있는 목적지를 제한하세요.

샌드박스 안에서 컨테이너를 실행하는 경우, 프록시 CA 인증서는 기본적으로 컨테이너 안에서 쓸 수 없습니다. 방화벽이 종료하는 HTTPS 트래픽이 TLS 검증을 통과하도록 컨테이너의 신뢰 저장소에 인증서를 설치하세요. 프록시 CA 인증서를 참고하세요.

리소스 제한

샌드박스마다 다음이 함께 제공됩니다.

전용 개인 파일 시스템
네트워크 네임스페이스 격리
커널 수준 프로세스 격리
엄격한 CPU와 메모리, 디스크 제한
통제를 벗어난 프로세스를 막는 자동 타임아웃

이런 제한은 리소스 고갈을 막고 모든 샌드박스가 자원을 공정하게 쓰도록 보장합니다.

네트워크 접근

샌드박스는 기본적으로 아웃바운드 HTTP 요청을 보낼 수 있으므로 npm이나 PyPI 같은 공개 레지스트리에서 패키지를 설치할 수 있습니다. 열어 둔 포트는 공개 URL로 접근할 수 있으니 어떤 서비스를 띄우는지 주의하세요.

샌드박스에서 나가는 인터넷 접근은 샌드박스 방화벽의 일부로 사용자가 정의하는 네트워크 정책을 통해 제한할 수 있습니다.

프록시 CA 인증서

Vercel 샌드박스는 샌드박스 프록시용으로 샌드박스마다 고유한 인증 기관(CA) 인증서를 다음 위치에 마운트합니다.

/etc/pki/ca-trust/source/anchors/vercel-proxy-ca.pem
/usr/local/share/ca-certificates/vercel-proxy-ca.pem

Vercel 샌드박스는 이 프록시 CA 인증서를 시스템 신뢰 번들에 자동으로 추가합니다. 시스템 신뢰 저장소를 쓰는 애플리케이션은 추가 설정이 필요하지 않습니다.

흔히 쓰는 도구와 런타임이 /etc/ssl/certs/ca-certificates.crt에 있는 시스템 CA 번들을 쓰도록 다음 환경 변수도 설정됩니다.

AWS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt
CARGO_HTTP_CAINFO=/etc/ssl/certs/ca-certificates.crt
CURL_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt
GIT_SSL_CAINFO=/etc/ssl/certs/ca-certificates.crt
GRPC_DEFAULT_SSL_ROOTS_FILE_PATH=/etc/ssl/certs/ca-certificates.crt
NODE_EXTRA_CA_CERTS=/etc/ssl/certs/ca-certificates.crt
NODE_USE_SYSTEM_CA=1
NPM_CONFIG_CAFILE=/etc/ssl/certs/ca-certificates.crt
PIP_CERT=/etc/ssl/certs/ca-certificates.crt
REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt
SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt

애플리케이션이 시스템 신뢰 저장소와 이 환경 변수를 쓰지 않는다면, 마운트된 vercel-proxy-ca.pem 파일 중 하나를 신뢰하도록 설정하세요. 샌드박스 방화벽이 변환 규칙을 적용하려고 종료하는 HTTPS 트래픽에는 이 설정이 필요합니다.

컨테이너는 프록시 CA를 물려받지 않습니다. 프록시 CA 인증서와 CA 환경 변수는 샌드박스 호스트에 설치됩니다. 샌드박스 안에서 실행하는 컨테이너는 자체 격리된 파일 시스템과 신뢰 저장소를 갖기 때문에 둘 중 어느 것도 물려받지 않습니다. 인증서가 없으면 샌드박스 방화벽이 변환 규칙을 적용하려고 종료하는 HTTPS 요청이 컨테이너 안에서 TLS 검증에 실패합니다.

컨테이너가 프록시를 신뢰하게 하려면 인증서를 컨테이너에 마운트하고 컨테이너 자체의 신뢰 저장소에 추가하세요. 예를 들어 도커에서는 이렇게 합니다.

# 호스트 인증서를 컨테이너에 마운트하고 빌드 시점이나 실행 시점에 신뢰하도록 등록합니다.
docker run --rm \
  -v /etc/pki/ca-trust/source/anchors/vercel-proxy-ca.pem:/usr/local/share/ca-certificates/vercel-proxy-ca.crt:ro \
  my-image \
  sh -c "update-ca-certificates && my-command"

정확한 경로와 명령은 컨테이너의 베이스 이미지에 따라 다릅니다. 그 이미지의 신뢰 저장소가 기대하는 위치에 인증서를 두고, 이미지에 맞는 신뢰 갱신 명령을 실행하세요. 예를 들어 Debian이나 Ubuntu에서는 update-ca-certificates, Amazon Linux나 Fedora, RHEL에서는 update-ca-trust입니다. 시스템 신뢰 저장소 대신 환경 변수에서 CA 번들을 읽는 애플리케이션이라면, 해당 변수(예: NODE_EXTRA_CA_CERTS)를 컨테이너 안에 마운트한 인증서 경로로 설정하세요.

데이터 프라이버시

샌드박스는 SOC 2 Type II 인증을 유지하는 Vercel의 보안 인프라에서 돌아갑니다. 샌드박스는 임시로 존재하기 때문에 데이터를 장기간 보관하지 않습니다. 데이터 저장 위치에 대한 구체적인 요구사항이 있다면 요금제 세부 내용을 확인하거나 컴플라이언스 팀에 문의하세요.

다음 단계

영속 샌드박스: 상태를 자동으로 저장하고 멈춘 지점에서 이어 시작하는 샌드박스입니다.
태그: 키-값 태그로 환경이나 팀, 그 밖의 기준에 따라 샌드박스를 분류합니다.
드라이브(베타): 영속 파일 시스템 스토리지를 샌드박스에 붙이고 여러 실행에 걸쳐 데이터를 재사용합니다.
리전: 샌드박스가 돌아갈 위치를 고르고 장애 조치 리전을 설정합니다.
퀵스타트: 첫 샌드박스를 실행해 봅니다.
Working with Sandbox: 자주 하는 작업별 가이드입니다.
인증: SDK 인증을 설정합니다.
스냅샷: 샌드박스 상태를 저장하고 복원합니다.
JS SDK 레퍼런스: 자바스크립트와 타입스크립트용 전체 API 문서입니다.
파이썬 SDK 레퍼런스: 파이썬용 전체 API 문서입니다.
CLI 레퍼런스: 터미널에서 샌드박스를 관리합니다.
예시: 실제 사용 사례와 코드 샘플입니다.