vercel-sandbox

Overview

What is vercel-sandbox?

vercel-sandbox is a browser-automation skill that runs agent-browser + headless Chrome inside ephemeral Vercel Sandbox microVMs. Each request spins up a lightweight Linux virtual machine, runs your browser commands, and then tears the VM down.

Because it runs entirely inside Vercel Sandbox, this skill is designed for Vercel-deployed apps (Next.js, SvelteKit, Nuxt, Remix, Astro, and other frameworks) that need real browser automation directly from serverless or edge-style environments.

What problems does it solve?

Traditional serverless runtimes are not well suited for running full Chrome:

• Binary size limits and cold starts make headless Chrome hard to bundle.
• System libraries required by Chromium are often missing.
• Long-running or stateful browser sessions are difficult to manage.

vercel-sandbox solves this by:

• Spinning up a dedicated microVM for each browser job.
• Installing Chromium system dependencies inside the VM.
• Running agent-browser to control Chrome for navigation, clicks, forms, screenshots, and more.
• Supporting persistent browser sessions across multiple commands within the same sandbox lifecycle.
• Keeping each run isolated and ephemeral, improving safety and reducing cross-request leakage.

Who is vercel-sandbox for?

This skill is a good fit if you:

• Deploy to Vercel and need real browser automation from within your app or API routes.
• Want to run headless Chrome without worrying about bundle size limits.
• Need to integrate UI testing, scraping, or interaction flows into a Vercel-hosted application.
• Need short-lived, isolated browser environments for user-specific tasks.

It is especially relevant for:

• Next.js, SvelteKit, Nuxt, Remix, and Astro apps on Vercel.
• Frontend teams adding end-to-end checks, visual regressions, or smoke tests.
• API endpoints that must load third-party sites in a real browser (for example, login flows or complex client-side apps).

When is it not a good fit?

vercel-sandbox may not be ideal when:

• You are not deploying on Vercel or cannot use Vercel Sandbox.
• You only need simple HTTP requests and do not require a real browser (use a plain HTTP client instead).
• You need long-lived, always-on browser processes that run for many minutes or hours; this skill is designed around ephemeral microVMs.

If you primarily want generic frontend utilities or build-time tooling, a simpler skill without a Sandbox dependency may be more appropriate.

How to Use

1. Prerequisites and dependencies

To use vercel-sandbox, you need:

• A Vercel project that can use Vercel Sandbox microVMs.
• A JavaScript/TypeScript codebase (e.g., Next.js API routes or server actions) where you can call the sandbox.
• @vercel/sandbox installed in your project:

pnpm add @vercel/sandbox

Inside the sandbox VM, Chromium needs several system libraries (for an Amazon Linux / dnf-based environment). The underlying pattern in the repository defines a CHROMIUM_SYSTEM_DEPS array to represent these requirements and installs them inside the VM before launching Chrome.

2. Core execution pattern

The core pattern for vercel-sandbox is:

1. Import Sandbox from @vercel/sandbox.
2. Configure the sandbox to install Chromium system deps and agent-browser.
3. Start the sandbox, run your browser automation commands, and then let the microVM shut down.

The skill wiring is handled by the agent system; your Vercel app triggers browser actions through this skill, and the skill ensures they run inside the microVM with Chrome available.

3. Installing vercel-sandbox as a skill

If you are using a skills-based agent environment, you can add this skill via the repository:

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

This pulls the vercel-sandbox skill definition from vercel-labs/agent-browser and makes it available to your agent or automation framework. The skill then knows how to:

• Start a Vercel Sandbox microVM.
• Ensure Chrome and system dependencies are installed.
• Invoke agent-browser to control the browser session.

4. Typical workflows

Once installed and wired into your agent, vercel-sandbox can power a variety of browser-automation tasks in your Vercel app, such as:

a. Automating end-to-end user flows

Use the skill to reproduce user journeys:

• Navigate to your app’s URL inside the microVM browser.
• Log in, fill forms, and click through flows.
• Capture screenshots or HTML snapshots at each step.

This is useful for smoke tests triggered by deployments or scheduled runs.

b. Capturing screenshots and visual checks

Run headless Chrome to:

• Capture full-page or viewport-specific screenshots.
• Validate layout and critical UI elements.
• Compare screenshots across releases (when combined with your own comparison logic).

c. Interacting with third-party sites

Some integrations require JavaScript-heavy pages or complex authentication flows that cannot be handled via raw HTTP:

• Open external dashboards or partner sites.
• Perform controlled interactions (clicks, waits, evaluations).
• Extract relevant data using agent-browser commands.

Because everything runs inside a sandboxed VM, each request is isolated from others.

5. Performance and snapshots

The repository notes that you can use sandbox snapshots to pre-install Chromium and agent-browser for sub-second startup. In practice this means:

• You create a snapshot image of a VM where Chrome and dependencies are already installed.
• Future browser jobs start from that snapshot instead of installing everything from scratch.

This keeps vercel-sandbox responsive enough for on-demand automation within your Vercel app.

6. Operational tips

• Scope work per VM: Group related browser commands into a single sandbox run when possible to minimize VM spin-up overhead.
• Handle timeouts: Design your flows with clear timeouts and retries, as microVMs are short-lived by design.
• Watch resource usage: Browser automation is heavier than simple HTTP; keep scripts efficient and avoid unnecessary pages or tabs.

FAQ

What does vercel-sandbox actually run inside the microVM?

vercel-sandbox runs agent-browser alongside headless Chrome inside a Vercel Sandbox microVM. The VM installs the Chromium system dependencies, launches the browser, and exposes commands for navigation, interaction, and capture.

Can I use vercel-sandbox with any Vercel framework?

Yes. The skill is framework-agnostic and is intended to work with any Vercel-deployed framework, including Next.js, SvelteKit, Nuxt, Remix, Astro, and others, as long as you can execute server-side code that talks to the sandbox.

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

Running Chrome directly in a serverless function is limited by bundle size, missing system libraries, and runtime constraints. vercel-sandbox instead uses a dedicated microVM per job, where you can:

• Install all system libraries required by Chromium.
• Run agent-browser without binary size restrictions.
• Keep browser state for the life of the sandbox session.

Does vercel-sandbox support persistent sessions?

Within a single sandbox lifecycle, yes. The description specifies that you can have persistent browser sessions across commands while the VM is running. Each microVM is still ephemeral overall: once the sandbox completes, its state is discarded.

Is vercel-sandbox safe to run with untrusted tasks?

Each browser run happens in an isolated Vercel Sandbox microVM, which provides a strong separation boundary between tasks. You should still apply your normal security practices (input validation, rate limiting, and monitoring), but the VM isolation helps contain each job.

Do I have to manage Chromium system dependencies myself?

The core pattern in the repository defines a set of Chromium system dependencies for the Amazon Linux / dnf environment. The vercel-sandbox skill uses this pattern so that the required libraries are installed inside the sandbox VM, not in your main app bundle. You may still need to keep the dependency list in sync with your Chromium version.

When should I not use vercel-sandbox?

Avoid vercel-sandbox when:

• You are not on Vercel or cannot enable Vercel Sandbox.
• A simple HTTP client or API integration is enough.
• You need long-running, always-on automation workers rather than on-demand, short-lived sandbox runs.

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

Use the provided command to add the skill from the vercel-labs/agent-browser repository:

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

After installation, configure your agent to route browser-automation requests (such as "Vercel Sandbox browser", "microVM Chrome", or "browser automation on Vercel") to the vercel-sandbox skill.

Where can I learn more about the implementation details?

The main reference lives in the vercel-labs/agent-browser repository under skills/vercel-sandbox. Start from SKILL.md there to see:

• The sandbox setup pattern.
• The Chromium system dependency list.
• How agent-browser is expected to run inside the microVM.

Use that as a guide if you want to customize or extend the vercel-sandbox behavior in your own project.