vercel-sandbox

Overview

What is vercel-sandbox?

vercel-sandbox 是一個瀏覽器自動化 skill，會在 短暫存在的 Vercel Sandbox microVM 中執行 agent-browser + headless Chrome。每一次請求都會啟動一台輕量級的 Linux 虛擬機，執行你的瀏覽器指令，完成後再將該 VM 關閉清除。

因為它完全在 Vercel Sandbox 內執行，這個 skill 特別為 部署在 Vercel 上的應用程式 設計（例如 Next.js、SvelteKit、Nuxt、Remix、Astro 等框架），讓你能在 serverless 或 edge 類型的環境中，直接使用真正的瀏覽器自動化能力。

What problems does it solve?

傳統的 serverless 運行環境並不適合直接跑完整的 Chrome：

• 二進位檔大小限制與冷啟動問題，讓 headless Chrome 很難被一起打包部署。
• Chromium 所需的系統函式庫經常在環境中缺失。
• 難以管理長時間或具狀態的瀏覽器工作階段。

vercel-sandbox 透過以下方式解決這些問題：

• 為每個瀏覽器任務啟動一個 專用 microVM。
• 在 VM 內安裝 Chromium 所需的系統相依套件。
• 執行 agent-browser 來控制 Chrome 進行導覽、點擊、填表、截圖等操作。
• 在同一個 sandbox 生命週期中，支援 跨多個指令的持續瀏覽器工作階段。
• 讓每一次執行都 隔離且短暫存在，提升安全性並降低跨請求之間的狀態汙染。

Who is vercel-sandbox for?

如果你有以下需求，這個 skill 會相當適合：

• 部署在 Vercel，並且需要從應用程式或 API routes 內發起真實瀏覽器自動化。
• 想要使用 headless Chrome，但不想被 bundle size 限制綁住。
• 需要在 Vercel 托管的應用中導入 UI 測試、資料抓取或互動流程。
• 需要 壽命短、互相隔離的瀏覽器環境，用來處理與特定使用者相關的任務。

特別適用於：

• 部署在 Vercel 的 Next.js、SvelteKit、Nuxt、Remix、Astro 等應用。
• 需要加入端對端檢查、視覺回歸檢測或 smoke tests 的前端團隊。
• 需要在 API endpoints 中以真實瀏覽器載入第三方網站（例如登入流程或複雜的前端應用）。

When is it not a good fit?

以下情境可能不適合使用 vercel-sandbox：

• 你 不是部署在 Vercel 上，或無法使用 Vercel Sandbox。
• 你只需要簡單的 HTTP 請求，並不需要真實瀏覽器（這時改用一般 HTTP client 即可）。
• 你需要 長時間常駐的瀏覽器程序，運行時間以多分鐘甚至多小時計；這個 skill 的設計核心是短暫存在的 microVM。

如果你主要想要的是通用前端工具或建置階段的工具，一個不依賴 Sandbox 的較簡單 skill 可能會更合適。

How to Use

1. Prerequisites and dependencies

要使用 vercel-sandbox，你需要：

• 一個可以啟用 Vercel Sandbox microVM 的 Vercel 專案。
• 一個 JavaScript/TypeScript 程式碼庫（例如 Next.js API routes 或 server actions），可以在裡面呼叫 sandbox。
• 在專案中安裝 @vercel/sandbox：

pnpm add @vercel/sandbox

在 sandbox VM 內，Chromium 需要多個系統函式庫（以 Amazon Linux / dnf 環境為例）。在 repository 中，底層模式會定義一個 CHROMIUM_SYSTEM_DEPS 陣列來描述這些需求，並在啟動 Chrome 之前先在 VM 內安裝好相關套件。

2. Core execution pattern

vercel-sandbox 的核心使用模式是：

1. 從 @vercel/sandbox 匯入 Sandbox。
2. 設定 sandbox，使其會安裝 Chromium system deps 與 agent-browser。
3. 啟動 sandbox，執行你的瀏覽器自動化指令，然後讓 microVM 自行關閉。

skill 的接線由 agent 系統負責；你的 Vercel 應用只要透過這個 skill 觸發瀏覽器動作，skill 就會確保這些操作在具備 Chrome 的 microVM 內執行。

3. Installing vercel-sandbox as a skill

如果你使用的是以 skills 為中心的 agent 環境，可以透過以下 repository 新增這個 skill：

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

這會從 vercel-labs/agent-browser 拉取 vercel-sandbox 的 skill 定義，並在你的 agent 或自動化框架中啟用。之後這個 skill 會負責：

• 啟動一個 Vercel Sandbox microVM。
• 確保 Chrome 與系統相依套件已安裝完成。
• 呼叫 agent-browser 來控制瀏覽器工作階段。

4. Typical workflows

安裝並接好到你的 agent 之後，vercel-sandbox 可以在 Vercel 應用中支援各種瀏覽器自動化任務，例如：

a. Automating end-to-end user flows

利用這個 skill 重現使用者操作流程：

• 在 microVM 裡的瀏覽器開啟你的應用程式 URL。
• 登入、填寫表單並依序完成操作流程。
• 在每個步驟擷取截圖或 HTML snapshot。

這對於在部署後或排程執行的 smoke tests 特別實用。

b. Capturing screenshots and visual checks

使用 headless Chrome 來：

• 擷取整頁或特定 viewport 的截圖。
• 驗證版面配置與關鍵 UI 元件是否正常。
• 搭配自有比較邏輯，在不同版本之間比對截圖。

c. Interacting with third-party sites

有些整合情境需要大量 JavaScript 的頁面或複雜的驗證流程，無法單純用 HTTP 處理：

• 開啟外部儀表板或合作夥伴網站。
• 執行受控的互動（點擊、等待、評估）。
• 使用 agent-browser 的指令擷取所需資料。

由於所有操作都在 sandbox VM 內進行，每個請求都與其他請求彼此隔離。

5. Performance and snapshots

在 repository 中提到，你可以利用 sandbox snapshots 預先安裝 Chromium 與 agent-browser，以達到 次秒級啟動時間。實務上代表：

• 你先建立一個 VM snapshot，其中已安裝好 Chrome 與相依套件。
• 之後的瀏覽器任務就可以直接從這個 snapshot 啟動，而不必每次重頭安裝。

這能讓 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 中，同時執行 agent-browser 與 headless Chrome。VM 會安裝好 Chromium 所需的系統相依套件、啟動瀏覽器，並提供導覽、互動與擷取等指令介面。

Can I use vercel-sandbox with any Vercel framework?

可以。這個 skill 與框架無關，設計上就是要支援 任何部署在 Vercel 上的框架，包含 Next.js、SvelteKit、Nuxt、Remix、Astro 等，只要你能在其中執行與 sandbox 溝通的 server-side 程式碼即可。

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

直接在 serverless function 中跑 Chrome 會受限於 bundle 大小、缺少系統函式庫與執行環境限制。vercel-sandbox 的做法則是每個工作都使用一台 專用 microVM，你可以在其中：

• 安裝 Chromium 所需的所有系統函式庫。
• 不受二進位大小限制地執行 agent-browser。
• 在整個 sandbox 工作階段中保留瀏覽器狀態。

Does vercel-sandbox support persistent sessions?

在單一 sandbox 生命週期內，可以。說明中明確提到，在 VM 運行期間，你可以透過多個指令維持 持續的瀏覽器工作階段。但每個 microVM 本質上仍是 短暫存在：一旦 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?

在 repository 的核心模式中，針對 Amazon Linux / dnf 環境定義了一組 Chromium system dependencies。vercel-sandbox skill 會沿用這個模式，在 sandbox VM 內安裝所需的函式庫，而不是放到你的主應用 bundle 裡。不過，你仍需依照自身使用的 Chromium 版本，維護並同步這份相依套件清單。

When should I not use vercel-sandbox?

以下情況建議不要使用 vercel-sandbox：

• 你不在 Vercel 上，或無法啟用 Vercel Sandbox。
• 一般 HTTP client 或 API 串接就足以滿足需求。
• 你需要的是長時間常駐的自動化 worker，而不是 按需啟動、壽命短暫 的 sandbox 執行。

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

使用以下指令，從 vercel-labs/agent-browser repository 安裝這個 skill：

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

安裝完成後，將你的 agent 設定為把瀏覽器自動化的請求（例如「Vercel Sandbox browser」、「microVM Chrome」或「browser automation on Vercel」）路由到 vercel-sandbox skill。

Where can I learn more about the implementation details?

主要參考資料位在 vercel-labs/agent-browser repository 的 skills/vercel-sandbox 目錄。請從那裡的 SKILL.md 開始閱讀，你會看到：

• sandbox 的設定模式。
• Chromium 系統相依套件清單。
• agent-browser 預期如何在 microVM 內執行。

如果你想在自己的專案中客製化或延伸 vercel-sandbox 的行為，可以把這份文件當作實作指南。