vercel-sandbox

Overview

What is vercel-sandbox?

vercel-sandbox 是一个浏览器自动化 skill，会在短暂存在的 Vercel Sandbox microVM 中运行 agent-browser + headless Chrome。每个请求都会临时启动一个轻量级 Linux 虚拟机，执行你的浏览器命令，然后销毁该虚拟机。

由于它完全运行在 Vercel Sandbox 内，这个 skill 专为需要在 无服务器或 edge 场景 中直接执行真实浏览器自动化的 Vercel 部署应用（Next.js、SvelteKit、Nuxt、Remix、Astro 等框架）而设计。

What problems does it solve?

传统 serverless 运行环境并不适合运行完整的 Chrome：

• 二进制体积限制和冷启动问题让 headless Chrome 难以打包。
• Chromium 所需的系统库往往缺失。
• 难以管理长时间运行或有状态的浏览器会话。

vercel-sandbox 通过以下方式解决这些问题：

• 为每个浏览器任务启动一个独立的 microVM。
• 在 VM 内安装 Chromium system dependencies。
• 运行 agent-browser 来控制 Chrome，完成跳转、点击、表单填写、截图等操作。
• 在同一次 sandbox 生命周期内支持 跨多条命令的持久浏览器会话。
• 保持每次运行都 隔离且短暂存在，提升安全性并减少跨请求泄漏。

Who is vercel-sandbox for?

如果你符合以下情况，这个 skill 很适合你：

• 部署在 Vercel，并且需要在应用或 API 路由内部执行真实浏览器自动化。
• 想要运行 headless Chrome，而不想被 bundle 体积限制拖累。
• 需要在 Vercel 托管的应用中集成 UI 测试、爬取（scraping）或复杂交互流程。
• 需要为特定用户任务提供 短生命周期、彼此隔离的浏览器环境。

它尤其适用于：

• 运行在 Vercel 上的 Next.js、SvelteKit、Nuxt、Remix、Astro 等应用。
• 希望增加端到端检查、可视化回归（visual regression）或冒烟测试的前端团队。
• 必须在真实浏览器中加载第三方站点的 API endpoint（例如登录流程或复杂的前端应用）。

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 的环境）。仓库中的基础模式通过一个 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 环境，可以通过仓库添加此 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 和系统依赖已在 VM 中安装。
• 调用 agent-browser 来控制浏览器会话。

4. Typical workflows

安装并接入你的 agent 之后，vercel-sandbox 可以在 Vercel 应用中驱动多种浏览器自动化场景，例如：

a. Automating end-to-end user flows

使用该 skill 重现真实用户路径：

• 在 microVM 浏览器中访问你的应用 URL。
• 登录、填写表单并完成各类交互流程。
• 在每个关键步骤截取截图或保存 HTML 快照。

这非常适合在部署后或定时任务中触发的冒烟测试。

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

仓库中提到可以利用 sandbox snapshots 预安装 Chromium 和 agent-browser，以实现 亚秒级启动。实践方式是：

• 创建一个 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 system dependencies，启动浏览器，并暴露用于导航、交互和内容捕获的命令。

Can I use vercel-sandbox with any Vercel framework?

可以。这个 skill 与框架无关，目标是支持 任何部署在 Vercel 上的框架，包括 Next.js、SvelteKit、Nuxt、Remix、Astro 等，只要你能在其中执行与 sandbox 通信的服务端代码即可。

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 中执行，为不同任务之间提供了强隔离边界。你仍然需要遵循常规安全实践（输入校验、限流、监控等），但 VM 的隔离有助于将每个任务控制在自己的边界内。

Do I have to manage Chromium system dependencies myself?

仓库中的核心模式为 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 仓库中添加该 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 仓库的 skills/vercel-sandbox 目录。可以从其中的 SKILL.md 开始阅读，了解：

• sandbox 的初始化与配置模式。
• Chromium system dependency 列表。
• agent-browser 在 microVM 中的预期运行方式。

如果你希望在自己的项目中自定义或扩展 vercel-sandbox 的行为，可以将其作为实现参考。