1---
2name: vercel-sandbox
3description: Run agent-browser + Chrome inside Vercel Sandbox microVMs for browser automation from any Vercel-deployed app. Use when the user needs browser automation in a Vercel app (Next.js, SvelteKit, Nuxt, Remix, Astro, etc.), wants to run headless Chrome without binary size limits, needs persistent browser sessions across commands, or wants ephemeral isolated browser environments. Triggers include "Vercel Sandbox browser", "microVM Chrome", "agent-browser in sandbox", "browser automation on Vercel", or any task requiring Chrome in a Vercel Sandbox.
4---
5 
6# Browser Automation with Vercel Sandbox
7 
8Run agent-browser + headless Chrome inside ephemeral Vercel Sandbox microVMs. A Linux VM spins up on demand, executes browser commands, and shuts down. Works with any Vercel-deployed framework (Next.js, SvelteKit, Nuxt, Remix, Astro, etc.).
9 
10## Dependencies
11 
12```bash
13pnpm add @vercel/sandbox
14```
15 
16The sandbox VM needs system dependencies for Chromium plus agent-browser itself. Use sandbox snapshots (below) to pre-install everything for sub-second startup.
17 
18## Core Pattern
19 
20```ts
21import { Sandbox } from "@vercel/sandbox";
22 
23// System libraries required by Chromium on the sandbox VM (Amazon Linux / dnf)
24const CHROMIUM_SYSTEM_DEPS = [
25  "nss", "nspr", "libxkbcommon", "atk", "at-spi2-atk", "at-spi2-core",
26  "libXcomposite", "libXdamage", "libXrandr", "libXfixes", "libXcursor",
27  "libXi", "libXtst", "libXScrnSaver", "libXext", "mesa-libgbm", "libdrm",
28  "mesa-libGL", "mesa-libEGL", "cups-libs", "alsa-lib", "pango", "cairo",
29  "gtk3", "dbus-libs",
30];
31 
32function getSandboxCredentials() {
33  if (
34    process.env.VERCEL_TOKEN &&
35    process.env.VERCEL_TEAM_ID &&
36    process.env.VERCEL_PROJECT_ID
37  ) {
38    return {
39      token: process.env.VERCEL_TOKEN,
40      teamId: process.env.VERCEL_TEAM_ID,
41      projectId: process.env.VERCEL_PROJECT_ID,
42    };
43  }
44  return {};
45}
46 
47async function withBrowser<T>(
48  fn: (sandbox: InstanceType<typeof Sandbox>) => Promise<T>,
49): Promise<T> {
50  const snapshotId = process.env.AGENT_BROWSER_SNAPSHOT_ID;
51  const credentials = getSandboxCredentials();
52 
53  const sandbox = snapshotId
54    ? await Sandbox.create({
55        ...credentials,
56        source: { type: "snapshot", snapshotId },
57        timeout: 120_000,
58      })
59    : await Sandbox.create({ ...credentials, runtime: "node24", timeout: 120_000 });
60 
61  if (!snapshotId) {
62    await sandbox.runCommand("sh", [
63      "-c",
64      `sudo dnf clean all 2>&1 && sudo dnf install -y --skip-broken ${CHROMIUM_SYSTEM_DEPS.join(" ")} 2>&1 && sudo ldconfig 2>&1`,
65    ]);
66    await sandbox.runCommand("npm", ["install", "-g", "agent-browser"]);
67    await sandbox.runCommand("npx", ["agent-browser", "install"]);
68  }
69 
70  try {
71    return await fn(sandbox);
72  } finally {
73    await sandbox.stop();
74  }
75}
76```
77 
78## Screenshot
79 
80The `screenshot --json` command saves to a file and returns the path. Read the file back as base64:
81 
82```ts
83export async function screenshotUrl(url: string) {
84  return withBrowser(async (sandbox) => {
85    await sandbox.runCommand("agent-browser", ["open", url]);
86 
87    const titleResult = await sandbox.runCommand("agent-browser", [
88      "get", "title", "--json",
89    ]);
90    const title = JSON.parse(await titleResult.stdout())?.data?.title || url;
91 
92    const ssResult = await sandbox.runCommand("agent-browser", [
93      "screenshot", "--json",
94    ]);
95    const ssPath = JSON.parse(await ssResult.stdout())?.data?.path;
96    const b64Result = await sandbox.runCommand("base64", ["-w", "0", ssPath]);
97    const screenshot = (await b64Result.stdout()).trim();
98 
99    await sandbox.runCommand("agent-browser", ["close"]);
100 
101    return { title, screenshot };
102  });
103}
104```
105 
106## Accessibility Snapshot
107 
108```ts
109export async function snapshotUrl(url: string) {
110  return withBrowser(async (sandbox) => {
111    await sandbox.runCommand("agent-browser", ["open", url]);
112 
113    const titleResult = await sandbox.runCommand("agent-browser", [
114      "get", "title", "--json",
115    ]);
116    const title = JSON.parse(await titleResult.stdout())?.data?.title || url;
117 
118    const snapResult = await sandbox.runCommand("agent-browser", [
119      "snapshot", "-i", "-c",
120    ]);
121    const snapshot = await snapResult.stdout();
122 
123    await sandbox.runCommand("agent-browser", ["close"]);
124 
125    return { title, snapshot };
126  });
127}
128```
129 
130## Multi-Step Workflows
131 
132The sandbox persists between commands, so you can run full automation sequences:
133 
134```ts
135export async function fillAndSubmitForm(url: string, data: Record<string, string>) {
136  return withBrowser(async (sandbox) => {
137    await sandbox.runCommand("agent-browser", ["open", url]);
138 
139    const snapResult = await sandbox.runCommand("agent-browser", [
140      "snapshot", "-i",
141    ]);
142    const snapshot = await snapResult.stdout();
143    // Parse snapshot to find element refs...
144 
145    for (const [ref, value] of Object.entries(data)) {
146      await sandbox.runCommand("agent-browser", ["fill", ref, value]);
147    }
148 
149    await sandbox.runCommand("agent-browser", ["click", "@e5"]);
150    await sandbox.runCommand("agent-browser", ["wait", "--load", "networkidle"]);
151 
152    const ssResult = await sandbox.runCommand("agent-browser", [
153      "screenshot", "--json",
154    ]);
155    const ssPath = JSON.parse(await ssResult.stdout())?.data?.path;
156    const b64Result = await sandbox.runCommand("base64", ["-w", "0", ssPath]);
157    const screenshot = (await b64Result.stdout()).trim();
158 
159    await sandbox.runCommand("agent-browser", ["close"]);
160 
161    return { screenshot };
162  });
163}
164```
165 
166## Sandbox Snapshots (Fast Startup)
167 
168A **sandbox snapshot** is a saved VM image of a Vercel Sandbox with system dependencies + agent-browser + Chromium already installed. Think of it like a Docker image -- instead of installing dependencies from scratch every time, the sandbox boots from the pre-built image.
169 
170This is unrelated to agent-browser's *accessibility snapshot* feature (`agent-browser snapshot`), which dumps a page's accessibility tree. A sandbox snapshot is a Vercel infrastructure concept for fast VM startup.
171 
172Without a sandbox snapshot, each run installs system deps + agent-browser + Chromium (~30s). With one, startup is sub-second.
173 
174### Creating a sandbox snapshot
175 
176The snapshot must include system dependencies (via `dnf`), agent-browser, and Chromium:
177 
178```ts
179import { Sandbox } from "@vercel/sandbox";
180 
181const CHROMIUM_SYSTEM_DEPS = [
182  "nss", "nspr", "libxkbcommon", "atk", "at-spi2-atk", "at-spi2-core",
183  "libXcomposite", "libXdamage", "libXrandr", "libXfixes", "libXcursor",
184  "libXi", "libXtst", "libXScrnSaver", "libXext", "mesa-libgbm", "libdrm",
185  "mesa-libGL", "mesa-libEGL", "cups-libs", "alsa-lib", "pango", "cairo",
186  "gtk3", "dbus-libs",
187];
188 
189async function createSnapshot(): Promise<string> {
190  const sandbox = await Sandbox.create({
191    runtime: "node24",
192    timeout: 300_000,
193  });
194 
195  await sandbox.runCommand("sh", [
196    "-c",
197    `sudo dnf clean all 2>&1 && sudo dnf install -y --skip-broken ${CHROMIUM_SYSTEM_DEPS.join(" ")} 2>&1 && sudo ldconfig 2>&1`,
198  ]);
199  await sandbox.runCommand("npm", ["install", "-g", "agent-browser"]);
200  await sandbox.runCommand("npx", ["agent-browser", "install"]);
201 
202  const snapshot = await sandbox.snapshot();
203  return snapshot.snapshotId;
204}
205```
206 
207Run this once, then set the environment variable:
208 
209```bash
210AGENT_BROWSER_SNAPSHOT_ID=snap_xxxxxxxxxxxx
211```
212 
213A helper script is available in the demo app:
214 
215```bash
216npx tsx examples/environments/scripts/create-snapshot.ts
217```
218 
219Recommended for any production deployment using the Sandbox pattern.
220 
221## Authentication
222 
223On Vercel deployments, the Sandbox SDK authenticates automatically via OIDC. For local development or explicit control, set:
224 
225```bash
226VERCEL_TOKEN=<personal-access-token>
227VERCEL_TEAM_ID=<team-id>
228VERCEL_PROJECT_ID=<project-id>
229```
230 
231These are spread into `Sandbox.create()` calls. When absent, the SDK falls back to `VERCEL_OIDC_TOKEN` (automatic on Vercel).
232 
233## Scheduled Workflows (Cron)
234 
235Combine with Vercel Cron Jobs for recurring browser tasks:
236 
237```ts
238// app/api/cron/route.ts  (or equivalent in your framework)
239export async function GET() {
240  const result = await withBrowser(async (sandbox) => {
241    await sandbox.runCommand("agent-browser", ["open", "https://example.com/pricing"]);
242    const snap = await sandbox.runCommand("agent-browser", ["snapshot", "-i", "-c"]);
243    await sandbox.runCommand("agent-browser", ["close"]);
244    return await snap.stdout();
245  });
246 
247  // Process results, send alerts, store data...
248  return Response.json({ ok: true, snapshot: result });
249}
250```
251 
252```json
253// vercel.json
254{ "crons": [{ "path": "/api/cron", "schedule": "0 9 * * *" }] }
255```
256 
257## Environment Variables
258 
259| Variable | Required | Description |
260|---|---|---|
261| `AGENT_BROWSER_SNAPSHOT_ID` | No (but recommended) | Pre-built sandbox snapshot ID for sub-second startup (see above) |
262| `VERCEL_TOKEN` | No | Vercel personal access token (for local dev; OIDC is automatic on Vercel) |
263| `VERCEL_TEAM_ID` | No | Vercel team ID (for local dev) |
264| `VERCEL_PROJECT_ID` | No | Vercel project ID (for local dev) |
265 
266## Framework Examples
267 
268The pattern works identically across frameworks. The only difference is where you put the server-side code:
269 
270| Framework | Server code location |
271|---|---|
272| Next.js | Server actions, API routes, route handlers |
273| SvelteKit | `+page.server.ts`, `+server.ts` |
274| Nuxt | `server/api/`, `server/routes/` |
275| Remix | `loader`, `action` functions |
276| Astro | `.astro` frontmatter, API routes |
277 
278## Example
279 
280See `examples/environments/` in the agent-browser repo for a working app with the Vercel Sandbox pattern, including a sandbox snapshot creation script, streaming progress UI, and rate limiting.
281