vercel-sandbox

Overview

What is vercel-sandbox?

vercel-sandbox là một skill tự động hóa trình duyệt chạy agent-browser + headless Chrome bên trong Vercel Sandbox microVMs dạng ephemeral. Mỗi request sẽ khởi tạo một máy ảo Linux nhẹ, chạy các lệnh điều khiển trình duyệt của bạn, rồi hủy VM sau khi xong việc.

Vì chạy hoàn toàn bên trong Vercel Sandbox, skill này được thiết kế cho các ứng dụng triển khai trên Vercel (Next.js, SvelteKit, Nuxt, Remix, Astro và các framework khác) cần tự động hóa trình duyệt thật trực tiếp từ môi trường serverless hoặc edge.

What problems does it solve?

Các runtime serverless truyền thống không phù hợp để chạy full Chrome:

• Giới hạn kích thước binary và cold start khiến khó bundle headless Chrome.
• Thư viện hệ thống mà Chromium cần thường bị thiếu.
• Các phiên trình duyệt chạy lâu hoặc có trạng thái khó quản lý.

vercel-sandbox giải quyết các vấn đề này bằng cách:

• Khởi tạo một microVM riêng cho mỗi job trình duyệt.
• Cài đặt Chromium system dependencies bên trong VM.
• Chạy agent-browser để điều khiển Chrome cho điều hướng, click, form, screenshot và nhiều thao tác khác.
• Hỗ trợ giữ phiên trình duyệt liên tục qua nhiều lệnh trong cùng vòng đời sandbox.
• Giữ mỗi lần chạy cô lập và dạng ephemeral, tăng độ an toàn và giảm rò rỉ giữa các request.

Who is vercel-sandbox for?

Skill này phù hợp nếu bạn:

• Triển khai lên Vercel và cần tự động hóa trình duyệt thực từ bên trong app hoặc API routes.
• Muốn chạy headless Chrome mà không phải lo giới hạn kích thước bundle.
• Cần tích hợp UI testing, scraping hoặc luồng tương tác vào ứng dụng chạy trên Vercel.
• Cần môi trường trình duyệt sống ngắn, cô lập cho các tác vụ theo người dùng.

Đặc biệt hữu ích cho:

• Ứng dụng Next.js, SvelteKit, Nuxt, Remix và Astro trên Vercel.
• Team frontend bổ sung end-to-end checks, visual regression test hoặc smoke test.
• API endpoint cần tải trang bên thứ ba trong một trình duyệt thực (ví dụ luồng đăng nhập hoặc app client-side phức tạp).

When is it not a good fit?

vercel-sandbox có thể không phù hợp khi:

• Bạn không triển khai trên Vercel hoặc không thể dùng Vercel Sandbox.
• Bạn chỉ cần các request HTTP đơn giản và không cần trình duyệt thực (hãy dùng HTTP client thông thường).
• Bạn cần process trình duyệt chạy liên tục, luôn bật trong nhiều phút hoặc nhiều giờ; skill này được thiết kế cho microVM dạng ephemeral.

Nếu bạn chủ yếu cần các tiện ích frontend chung hoặc tooling ở build-time, một skill đơn giản hơn, không phụ thuộc Sandbox có thể phù hợp hơn.

How to Use

1. Prerequisites and dependencies

Để dùng vercel-sandbox, bạn cần:

• Một Vercel project có thể sử dụng Vercel Sandbox microVMs.
• Codebase JavaScript/TypeScript (ví dụ Next.js API routes hoặc server actions) nơi bạn có thể gọi sandbox.
• Cài @vercel/sandbox trong project của bạn:

pnpm add @vercel/sandbox

Bên trong sandbox VM, Chromium cần một số thư viện hệ thống (cho môi trường Amazon Linux / dnf). Pattern cốt lõi trong repository định nghĩa một mảng CHROMIUM_SYSTEM_DEPS thể hiện các yêu cầu này và cài đặt chúng vào VM trước khi khởi chạy Chrome.

2. Core execution pattern

Pattern lõi khi dùng vercel-sandbox là:

1. Import Sandbox từ @vercel/sandbox.
2. Cấu hình sandbox để cài Chromium system deps và agent-browser.
3. Khởi chạy sandbox, chạy các lệnh tự động hóa trình duyệt, sau đó để microVM tắt đi.

Phần wiring cho skill được hệ thống agent xử lý; app Vercel của bạn gọi các hành động trên trình duyệt thông qua skill này, và skill đảm bảo chúng chạy trong microVM với Chrome đã sẵn sàng.

3. Installing vercel-sandbox as a skill

Nếu bạn dùng một môi trường agent dạng skills-based, bạn có thể thêm skill này qua repository:

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

Lệnh này lấy định nghĩa skill vercel-sandbox từ vercel-labs/agent-browser và đưa nó vào agent hoặc framework tự động hóa của bạn. Skill sau đó sẽ:

• Khởi động một Vercel Sandbox microVM.
• Đảm bảo Chrome và các system dependencies được cài đặt.
• Gọi agent-browser để điều khiển phiên trình duyệt.

4. Typical workflows

Khi đã cài và kết nối với agent, vercel-sandbox có thể xử lý nhiều tác vụ tự động hóa trình duyệt trong ứng dụng Vercel của bạn, chẳng hạn:

a. Automating end-to-end user flows

Dùng skill để tái hiện hành trình người dùng:

• Điều hướng tới URL ứng dụng của bạn trong trình duyệt bên trong microVM.
• Đăng nhập, điền form, click qua các bước.
• Chụp screenshot hoặc snapshot HTML ở từng bước.

Điều này hữu ích cho smoke test chạy theo mỗi lần deploy hoặc theo lịch.

b. Capturing screenshots and visual checks

Chạy headless Chrome để:

• Chụp screenshot toàn trang hoặc theo vùng viewport.
• Xác nhận layout và các thành phần UI quan trọng.
• So sánh screenshot giữa các phiên bản (khi kết hợp với logic so sánh của bạn).

c. Interacting with third-party sites

Một số tích hợp yêu cầu trang dùng nhiều JavaScript hoặc luồng xác thực phức tạp không thể xử lý bằng HTTP thuần:

• Mở dashboard bên ngoài hoặc trang đối tác.
• Thực hiện các tương tác có kiểm soát (click, chờ, evaluate script).
• Trích xuất dữ liệu liên quan bằng các lệnh của agent-browser.

Do mọi thứ chạy trong một VM sandbox cô lập, mỗi request được tách biệt với request khác.

5. Performance and snapshots

Repository lưu ý rằng bạn có thể dùng sandbox snapshots để pre-install Chromium và agent-browser nhằm đạt thời gian khởi động dưới 1 giây. Thực tế nghĩa là:

• Bạn tạo một snapshot image của VM nơi Chrome và dependencies đã được cài.
• Các job trình duyệt sau đó khởi chạy từ snapshot này thay vì cài lại từ đầu.

Nhờ vậy vercel-sandbox đủ nhanh để phục vụ các tác vụ tự động hóa on-demand trong ứng dụng Vercel của bạn.

6. Operational tips

• Nhóm công việc theo VM: Gom các lệnh trình duyệt liên quan vào một lần chạy sandbox khi có thể để giảm overhead khởi tạo VM.
• Xử lý timeout: Thiết kế luồng với timeout và retry rõ ràng, vì microVM vốn ngắn hạn theo thiết kế.
• Theo dõi tài nguyên: Tự động hóa trình duyệt nặng hơn HTTP đơn giản; hãy giữ script hiệu quả và tránh mở tab/trang không cần thiết.

FAQ

What does vercel-sandbox actually run inside the microVM?

vercel-sandbox chạy agent-browser cùng với headless Chrome bên trong một Vercel Sandbox microVM. VM sẽ cài các Chromium system dependencies, khởi chạy trình duyệt và expose các lệnh để điều hướng, tương tác và chụp dữ liệu.

Can I use vercel-sandbox with any Vercel framework?

Có. Skill này không phụ thuộc framework và được thiết kế để hoạt động với bất kỳ framework nào triển khai trên Vercel, gồm Next.js, SvelteKit, Nuxt, Remix, Astro và các framework khác, miễn là bạn có thể chạy server-side code nói chuyện với sandbox.

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

Chạy Chrome trực tiếp trong serverless function bị giới hạn bởi kích thước bundle, thiếu thư viện hệ thống và nhiều ràng buộc runtime. vercel-sandbox thay vào đó dùng một microVM riêng cho mỗi job, trong đó bạn có thể:

• Cài mọi thư viện hệ thống mà Chromium cần.
• Chạy agent-browser mà không bị giới hạn kích thước binary.
• Giữ trạng thái trình duyệt trong suốt phiên sandbox.

Does vercel-sandbox support persistent sessions?

Trong một vòng đời sandbox, có. Mô tả cho biết bạn có thể có phiên trình duyệt persistent qua nhiều lệnh trong khi VM đang chạy. Mỗi microVM vẫn dạng ephemeral tổng thể: khi sandbox kết thúc, toàn bộ trạng thái bị loại bỏ.

Is vercel-sandbox safe to run with untrusted tasks?

Mỗi lần chạy trình duyệt diễn ra trong một Vercel Sandbox microVM cô lập, cung cấp ranh giới tách biệt mạnh giữa các tác vụ. Bạn vẫn nên áp dụng các biện pháp bảo mật thông thường (validate input, rate limiting, monitoring), nhưng lớp cô lập VM giúp khoanh vùng từng job.

Do I have to manage Chromium system dependencies myself?

Pattern cốt lõi trong repository định nghĩa sẵn một tập Chromium system dependencies cho môi trường Amazon Linux / dnf. Skill vercel-sandbox dùng pattern này để các thư viện cần thiết được cài bên trong sandbox VM, chứ không nằm trong bundle app chính. Bạn vẫn có thể cần giữ danh sách dependencies này đồng bộ với phiên bản Chromium bạn dùng.

When should I not use vercel-sandbox?

Hạn chế dùng vercel-sandbox khi:

• Bạn không chạy trên Vercel hoặc không bật được Vercel Sandbox.
• Một HTTP client hoặc API integration đơn giản là đủ.
• Bạn cần worker tự động hóa chạy lâu, luôn bật thay vì các lần chạy sandbox ngắn hạn, on-demand.

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

Dùng lệnh sau để thêm skill từ repository vercel-labs/agent-browser:

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

Sau khi cài, cấu hình agent của bạn để route các yêu cầu tự động hóa trình duyệt (chẳng hạn "Vercel Sandbox browser", "microVM Chrome" hoặc "browser automation on Vercel") tới skill vercel-sandbox.

Where can I learn more about the implementation details?

Tài liệu tham chiếu chính nằm trong repository vercel-labs/agent-browser dưới thư mục skills/vercel-sandbox. Bắt đầu từ file SKILL.md ở đó để xem:

• Pattern thiết lập sandbox.
• Danh sách Chromium system dependencies.
• Cách agent-browser được kỳ vọng chạy bên trong microVM.

Hãy dùng đó làm hướng dẫn nếu bạn muốn tùy biến hoặc mở rộng hành vi vercel-sandbox trong project của riêng mình.