Browser Automation with Vercel Sandbox

Screenshot

The screenshot --json command saves to a file and returns the path. Read the file back as base64:

export async function screenshotUrl(url: string) {
  return withBrowser(async (sandbox) => {
    await sandbox.runCommand('agent-browser', ['open', url])

    const titleResult = await sandbox.runCommand('agent-browser', ['get', 'title', '--json'])
    const title = JSON.parse(await titleResult.stdout())?.data?.title || url

    const ssResult = await sandbox.runCommand('agent-browser', ['screenshot', '--json'])
    const ssPath = JSON.parse(await ssResult.stdout())?.data?.path
    const b64Result = await sandbox.runCommand('base64', ['-w', '0', ssPath])
    const screenshot = (await b64Result.stdout()).trim()

    await sandbox.runCommand('agent-browser', ['close'])

    return { title, screenshot }
  })
}

Accessibility Snapshot

export async function snapshotUrl(url: string) {
  return withBrowser(async (sandbox) => {
    await sandbox.runCommand('agent-browser', ['open', url])

    const titleResult = await sandbox.runCommand('agent-browser', ['get', 'title', '--json'])
    const title = JSON.parse(await titleResult.stdout())?.data?.title || url

    const snapResult = await sandbox.runCommand('agent-browser', ['snapshot', '-i', '-c'])
    const snapshot = await snapResult.stdout()

    await sandbox.runCommand('agent-browser', ['close'])

    return { title, snapshot }
  })
}

Multi-Step Workflows

The sandbox persists between commands, so you can run full automation sequences:

export async function fillAndSubmitForm(url: string, data: Record<string, string>) {
  return withBrowser(async (sandbox) => {
    await sandbox.runCommand('agent-browser', ['open', url])

    const snapResult = await sandbox.runCommand('agent-browser', ['snapshot', '-i'])
    const snapshot = await snapResult.stdout()
    // Parse snapshot to find element refs...

    for (const [ref, value] of Object.entries(data)) {
      await sandbox.runCommand('agent-browser', ['fill', ref, value])
    }

    await sandbox.runCommand('agent-browser', ['click', '@e5'])
    await sandbox.runCommand('agent-browser', ['wait', '--load', 'networkidle'])

    const ssResult = await sandbox.runCommand('agent-browser', ['screenshot', '--json'])
    const ssPath = JSON.parse(await ssResult.stdout())?.data?.path
    const b64Result = await sandbox.runCommand('base64', ['-w', '0', ssPath])
    const screenshot = (await b64Result.stdout()).trim()

    await sandbox.runCommand('agent-browser', ['close'])

    return { screenshot }
  })
}

Sandbox Snapshots (Fast Startup)

A 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.

This 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.

Without a sandbox snapshot, each run installs system deps + agent-browser + Chromium (~30s). With one, startup is sub-second.

Creating a sandbox snapshot

The snapshot must include system dependencies (via dnf), agent-browser, and Chromium:

import { Sandbox } from '@vercel/sandbox'

const CHROMIUM_SYSTEM_DEPS = [
  'nss',
  'nspr',
  'libxkbcommon',
  'atk',
  'at-spi2-atk',
  'at-spi2-core',
  'libXcomposite',
  'libXdamage',
  'libXrandr',
  'libXfixes',
  'libXcursor',
  'libXi',
  'libXtst',
  'libXScrnSaver',
  'libXext',
  'mesa-libgbm',
  'libdrm',
  'mesa-libGL',
  'mesa-libEGL',
  'cups-libs',
  'alsa-lib',
  'pango',
  'cairo',
  'gtk3',
  'dbus-libs',
]

async function createSnapshot(): Promise<string> {
  const sandbox = await Sandbox.create({
    runtime: 'node24',
    timeout: 300_000,
  })

  await sandbox.runCommand('sh', [
    '-c',
    `sudo dnf clean all 2>&1 && sudo dnf install -y --skip-broken ${CHROMIUM_SYSTEM_DEPS.join(' ')} 2>&1 && sudo ldconfig 2>&1`,
  ])
  await sandbox.runCommand('npm', ['install', '-g', 'agent-browser'])
  await sandbox.runCommand('npx', ['agent-browser', 'install'])

  const snapshot = await sandbox.snapshot()
  return snapshot.snapshotId
}

Run this once, then set the environment variable:

AGENT_BROWSER_SNAPSHOT_ID=snap_xxxxxxxxxxxx

A helper script is available in the demo app:

npx tsx examples/environments/scripts/create-snapshot.ts

Recommended for any production deployment using the Sandbox pattern.

Authentication

On Vercel deployments, the Sandbox SDK authenticates automatically via OIDC. For local development or explicit control, set:

VERCEL_TOKEN=<personal-access-token>
VERCEL_TEAM_ID=<team-id>
VERCEL_PROJECT_ID=<project-id>

These are spread into Sandbox.create() calls. When absent, the SDK falls back to VERCEL_OIDC_TOKEN (automatic on Vercel).

Scheduled Workflows (Cron)

Combine with Vercel Cron Jobs for recurring browser tasks:

// app/api/cron/route.ts  (or equivalent in your framework)
export async function GET() {
  const result = await withBrowser(async (sandbox) => {
    await sandbox.runCommand('agent-browser', ['open', 'https://example.com/pricing'])
    const snap = await sandbox.runCommand('agent-browser', ['snapshot', '-i', '-c'])
    await sandbox.runCommand('agent-browser', ['close'])
    return await snap.stdout()
  })

  // Process results, send alerts, store data...
  return Response.json({ ok: true, snapshot: result })
}

// vercel.json
{ "crons": [{ "path": "/api/cron", "schedule": "0 9 * * *" }] }

Environment Variables

Framework Examples

The pattern works identically across frameworks. The only difference is where you put the server-side code:

Example

See 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.