vercel-sandbox

Overview

What is vercel-sandbox?

vercel-sandbox는 agent-browser + headless Chrome을 ephemeral Vercel Sandbox microVM 안에서 실행하는 브라우저 자동화 스킬입니다. 각 요청마다 경량 Linux 가상 머신을 하나 띄우고, 브라우저 명령을 실행한 뒤, 작업이 끝나면 VM을 정리합니다.

모든 작업이 Vercel Sandbox 안에서 이루어지기 때문에, 이 스킬은 서버리스 또는 엣지 스타일 환경에서 실제 브라우저 자동화가 필요한 Vercel 배포 앱(Next.js, SvelteKit, Nuxt, Remix, Astro 및 기타 프레임워크)에 맞게 설계되었습니다.

What problems does it solve?

기존 서버리스 런타임은 전체 Chrome을 실행하기에 적합하지 않습니다.

• 바이너리 크기 제한과 콜드 스타트 때문에 headless Chrome 번들이 어렵습니다.
• Chromium이 필요로 하는 시스템 라이브러리가 자주 빠져 있습니다.
• 오래 실행되거나 상태를 유지하는 브라우저 세션을 관리하기가 까다롭습니다.

vercel-sandbox는 다음과 같이 이 문제를 해결합니다.

• 각 브라우저 작업마다 전용 microVM을 띄웁니다.
• VM 내부에 Chromium 시스템 의존성을 설치합니다.
• agent-browser로 Chrome을 제어해 탐색, 클릭, 폼 입력, 스크린샷 캡처 등을 수행합니다.
• 같은 sandbox 라이프사이클 안에서 여러 명령에 걸친 persistent browser session을 지원합니다.
• 각 실행을 격리되고 ephemeral하게 유지해, 안전성을 높이고 요청 간 상태 누출을 줄입니다.

Who is vercel-sandbox for?

다음과 같은 경우 이 스킬이 잘 맞습니다.

• Vercel에 배포하고 있으며, 앱 또는 API route 안에서 실제 브라우저 자동화가 필요할 때
• 번들 크기 제한을 신경 쓰지 않고 headless Chrome을 실행하고 싶을 때
• Vercel에 호스팅된 애플리케이션에 UI 테스트, 스크래핑, 상호작용 플로우를 통합하고 싶을 때
• 사용자별 작업을 위한 단명(short-lived), 격리된 브라우저 환경이 필요할 때

특히 다음과 같은 상황에 유용합니다.

• Vercel에 배포된 Next.js, SvelteKit, Nuxt, Remix, Astro 앱
• 엔드투엔드 체크, 비주얼 리그레션, 스모크 테스트를 추가하는 프론트엔드 팀
• 실제 브라우저에서 서드파티 사이트를 로드해야 하는 API 엔드포인트(예: 로그인 플로우나 복잡한 클라이언트 사이드 앱)

When is it not a good fit?

다음과 같은 경우 vercel-sandbox는 가장 적합한 선택이 아닐 수 있습니다.

• Vercel에 배포하지 않거나 Vercel Sandbox를 사용할 수 없을 때
• 단순한 HTTP 요청만 필요하고 실제 브라우저가 필요하지 않을 때(일반 HTTP 클라이언트를 사용하는 편이 낫습니다.)
• 수분~수시간 동안 돌아가는 장기 실행, 상시 가동 브라우저 프로세스가 필요할 때. 이 스킬은 본질적으로 ephemeral microVM을 전제로 설계되었습니다.

주요 목적이 일반적인 프론트엔드 유틸리티나 빌드 타임 도구라면, Sandbox 의존성이 없는 더 단순한 스킬이 더 적합할 수 있습니다.

How to Use

1. Prerequisites and dependencies

vercel-sandbox를 사용하려면 다음이 필요합니다.

• Vercel Sandbox microVM을 사용할 수 있는 Vercel 프로젝트
• sandbox를 호출할 수 있는 JavaScript/TypeScript 코드베이스(예: Next.js API routes 또는 server actions)
• 프로젝트에 설치된 @vercel/sandbox:

pnpm add @vercel/sandbox

sandbox VM 내부에서 Chromium은 (Amazon Linux / dnf 기반 환경 기준) 여러 시스템 라이브러리를 필요로 합니다. 레포지토리의 기본 패턴에서는 이러한 요구사항을 나타내기 위해 CHROMIUM_SYSTEM_DEPS 배열을 정의하고, Chrome을 실행하기 전에 VM 안에 해당 패키지들을 설치합니다.

2. Core execution pattern

vercel-sandbox의 기본 실행 패턴은 다음과 같습니다.

1. @vercel/sandbox에서 Sandbox를 import 합니다.
2. sandbox를 설정해 Chromium system deps와 agent-browser를 설치합니다.
3. sandbox를 시작하고 브라우저 자동화 명령을 실행한 뒤, microVM이 종료되도록 합니다.

스킬과 관련된 세부 연결은 에이전트 시스템이 처리합니다. Vercel 앱은 이 스킬을 통해 브라우저 액션을 트리거하고, 스킬은 microVM 내부에서 Chrome을 사용할 수 있도록 보장합니다.

3. Installing vercel-sandbox as a skill

skills 기반 에이전트 환경을 사용 중이라면 레포지토리를 통해 이 스킬을 추가할 수 있습니다.

npx skills add https://github.com/vercel-labs/agent-browser --skill vercel-sandbox

이 명령은 vercel-labs/agent-browser에서 vercel-sandbox 스킬 정의를 가져와, 에이전트나 자동화 프레임워크에서 사용할 수 있게 합니다. 이후 스킬은 다음을 수행하는 방법을 알게 됩니다.

• Vercel Sandbox microVM을 시작
• Chrome과 시스템 의존성이 설치되었는지 확인
• agent-browser를 호출하여 브라우저 세션을 제어

4. Typical workflows

스킬을 설치하고 에이전트에 연결하면, vercel-sandbox는 Vercel 앱에서 다양한 브라우저 자동화 작업에 활용될 수 있습니다.

a. Automating end-to-end user flows

사용자 여정을 재현하는 용도로 스킬을 사용할 수 있습니다.

• microVM 내부 브라우저에서 앱 URL로 이동
• 로그인, 폼 입력, 플로우별 클릭 수행
• 각 단계에서 스크린샷이나 HTML 스냅샷 캡처

이는 배포 시점 또는 스케줄에 맞춰 실행하는 스모크 테스트에 유용합니다.

b. Capturing screenshots and visual checks

headless Chrome을 사용해 다음과 같은 작업을 수행할 수 있습니다.

• 전체 페이지 또는 특정 뷰포트 영역의 스크린샷 캡처
• 레이아웃 및 핵심 UI 요소 검증
• (직접 구현한 비교 로직과 결합해) 릴리스 간 스크린샷 비교

c. Interacting with third-party sites

일부 연동은 단순 HTTP 요청만으로 처리할 수 없는, JavaScript가 무겁거나 인증 플로우가 복잡한 페이지를 필요로 합니다.

• 외부 대시보드나 파트너 사이트 열기
• 클릭, 대기, 평가 등 제어된 상호작용 수행
• agent-browser 명령을 통해 필요한 데이터 추출

모든 작업이 sandboxed VM 안에서 실행되므로, 각 요청은 다른 요청과 격리됩니다.

5. Performance and snapshots

레포지토리에서는 sandbox snapshots를 사용해 Chromium과 agent-browser를 미리 설치해 두고 sub-second startup을 구현할 수 있다고 안내합니다. 실제로는 다음을 의미합니다.

• Chrome과 의존성이 이미 설치된 VM의 스냅샷 이미지를 만듭니다.
• 이후 브라우저 작업은 매번 새로 설치하는 대신 해당 스냅샷에서 시작합니다.

이를 통해 vercel-sandbox는 Vercel 앱 안에서 온디맨드 자동화를 수행하기에 충분한 응답성을 유지할 수 있습니다.

6. Operational tips

• VM 단위로 작업 범위를 정리하세요: 가능한 경우 관련 브라우저 명령을 한 번의 sandbox 실행에 묶어 VM 기동 오버헤드를 줄이세요.
• 타임아웃을 명확히 처리하세요: microVM은 설계상 수명이 짧으므로, 플로우를 설계할 때 명확한 타임아웃과 재시도 정책을 두는 것이 좋습니다.
• 리소스 사용량을 모니터링하세요: 브라우저 자동화는 단순 HTTP보다 무겁습니다. 스크립트를 효율적으로 유지하고, 불필요한 페이지나 탭 생성은 피하세요.

FAQ

What does vercel-sandbox actually run inside the microVM?

vercel-sandbox는 Vercel Sandbox microVM 안에서 headless Chrome과 agent-browser를 함께 실행합니다. VM은 Chromium 시스템 의존성을 설치한 뒤 브라우저를 구동하고, 탐색, 상호작용, 캡처를 위한 명령 인터페이스를 제공합니다.

Can I use vercel-sandbox with any Vercel framework?

가능합니다. 이 스킬은 특정 프레임워크에 종속되지 않으며, Next.js, SvelteKit, Nuxt, Remix, Astro 등 어떤 Vercel 배포 프레임워크와도 함께 사용하도록 설계되었습니다. 단, sandbox와 통신하는 서버 사이드 코드를 실행할 수 있어야 합니다.

How is this different from running Chrome directly in a serverless function?

서버리스 함수에서 Chrome을 직접 실행하면 번들 크기 제한, 누락된 시스템 라이브러리, 런타임 제약 등에 부딪히기 쉽습니다. vercel-sandbox는 대신 작업당 전용 microVM을 사용해 다음을 가능하게 합니다.

• Chromium에 필요한 모든 시스템 라이브러리 설치
• 바이너리 크기 제한 없이 agent-browser 실행
• sandbox 세션이 유지되는 동안 브라우저 상태를 그대로 유지

Does vercel-sandbox support persistent sessions?

단일 sandbox 라이프사이클 안에서는 지원됩니다. 설명에서 언급하듯, VM이 살아 있는 동안에는 여러 명령에 걸쳐 persistent browser session을 유지할 수 있습니다. 다만 각 microVM 자체는 여전히 ephemeral하며, sandbox가 종료되면 상태는 폐기됩니다.

Is vercel-sandbox safe to run with untrusted tasks?

각 브라우저 실행은 격리된 Vercel Sandbox microVM에서 이루어져, 작업 간에 강한 분리 경계를 제공합니다. 그럼에도 불구하고 입력 검증, rate limiting, 모니터링 등 일반적인 보안 모범사례는 그대로 적용해야 합니다. VM 격리는 각 작업을 개별적으로 차단하는 데 도움을 줄 뿐입니다.

Do I have to manage Chromium system dependencies myself?

레포지토리의 기본 패턴은 Amazon Linux / dnf 환경을 기준으로 한 Chromium system dependencies 세트를 정의합니다. vercel-sandbox 스킬은 이 패턴을 활용해, 필요한 라이브러리를 메인 앱 번들이 아니라 sandbox VM 내부에 설치합니다. 다만 사용하는 Chromium 버전에 맞게 의존성 목록을 주기적으로 맞춰 줄 필요는 있을 수 있습니다.

When should I not use vercel-sandbox?

다음과 같은 경우 vercel-sandbox 사용을 피하는 것이 좋습니다.

• Vercel 환경이 아니거나 Vercel Sandbox를 활성화할 수 없을 때
• 단순 HTTP 클라이언트나 API 연동만으로 충분할 때
• 온디맨드, 단명 sandbox 실행이 아니라 장기간 동작하는 상시 자동화 워커가 필요할 때

How do I install vercel-sandbox as part of my agent setup?

vercel-labs/agent-browser 레포지토리에서 제공하는 명령으로 스킬을 추가하면 됩니다.

npx skills add https://github.com/vercel-labs/agent-browser --skill vercel-sandbox

설치 후에는 에이전트가 브라우저 자동화 요청(예: "Vercel Sandbox browser", "microVM Chrome", "browser automation on Vercel"와 같은 질의)을 vercel-sandbox 스킬로 라우팅하도록 설정하세요.

Where can I learn more about the implementation details?

주요 참고 자료는 vercel-labs/agent-browser 레포지토리의 skills/vercel-sandbox 디렉터리에 있습니다. 먼저 SKILL.md를 확인하면 다음 내용을 볼 수 있습니다.

• sandbox 설정 패턴
• Chromium 시스템 의존성 목록
• agent-browser가 microVM 내부에서 어떻게 실행되어야 하는지

이를 기반으로, 프로젝트에 맞게 vercel-sandbox 동작을 커스터마이즈하거나 확장할 때 참고할 수 있습니다.