vercel-sandbox

Overview

What is vercel-sandbox?

vercel-sandbox es una skill de automatización de navegador que ejecuta agent-browser + headless Chrome dentro de microVMs efímeras de Vercel Sandbox. Cada petición arranca una máquina virtual Linux ligera, ejecuta tus comandos de navegador y luego destruye la VM.

Como se ejecuta íntegramente dentro de Vercel Sandbox, esta skill está diseñada para apps desplegadas en Vercel (Next.js, SvelteKit, Nuxt, Remix, Astro y otros frameworks) que necesitan automatización real de navegador directamente desde entornos serverless o de tipo edge.

What problems does it solve?

Los runtimes serverless tradicionales no están pensados para ejecutar un Chrome completo:

• Los límites de tamaño de binarios y los cold starts hacen difícil incluir headless Chrome.
• A menudo faltan las librerías de sistema que necesita Chromium.
• Las sesiones de navegador de larga duración o con estado son difíciles de gestionar.

vercel-sandbox resuelve esto mediante:

• Levantar una microVM dedicada para cada trabajo de navegador.
• Instalar las dependencias de sistema de Chromium dentro de la VM.
• Ejecutar agent-browser para controlar Chrome para navegación, clics, formularios, capturas de pantalla y más.
• Permitir sesiones de navegador persistentes a lo largo de varios comandos dentro del mismo ciclo de vida del sandbox.
• Mantener cada ejecución aislada y efímera, mejorando la seguridad y reduciendo filtraciones entre peticiones.

Who is vercel-sandbox for?

Esta skill encaja bien si:

• Despliegas en Vercel y necesitas automatización real de navegador desde tu app o rutas de API.
• Quieres ejecutar headless Chrome sin preocuparte por los límites de tamaño del bundle.
• Necesitas integrar tests de UI, scraping o flujos de interacción en una aplicación alojada en Vercel.
• Requieres entornos de navegador de corta duración y aislados para tareas específicas de usuario.

Es especialmente relevante para:

• Apps de Next.js, SvelteKit, Nuxt, Remix y Astro en Vercel.
• Equipos de frontend que añaden checks end-to-end, regresiones visuales o smoke tests.
• Endpoints de API que deben cargar sitios de terceros en un navegador real (por ejemplo, flujos de login o apps cliente complejas).

When is it not a good fit?

vercel-sandbox puede no ser ideal cuando:

• No despliegas en Vercel o no puedes usar Vercel Sandbox.
• Solo necesitas peticiones HTTP sencillas y no requieres un navegador real (usa en su lugar un cliente HTTP convencional).
• Necesitas procesos de navegador de larga duración y siempre activos que se ejecuten durante muchos minutos u horas; esta skill está pensada para microVMs efímeras.

Si principalmente buscas utilidades genéricas de frontend o tooling de build, puede ser más adecuado usar una skill más simple sin dependencia de Sandbox.

How to Use

1. Prerequisites and dependencies

Para usar vercel-sandbox, necesitas:

• Un proyecto de Vercel que pueda utilizar microVMs de Vercel Sandbox.
• Una base de código en JavaScript/TypeScript (por ejemplo, rutas de API de Next.js o server actions) desde la que puedas invocar el sandbox.
• @vercel/sandbox instalado en tu proyecto:

pnpm add @vercel/sandbox

Dentro de la VM del sandbox, Chromium necesita varias librerías de sistema (para un entorno Amazon Linux basado en dnf). El patrón base en el repositorio define un array CHROMIUM_SYSTEM_DEPS para representar estos requisitos y los instala dentro de la VM antes de lanzar Chrome.

2. Core execution pattern

El patrón básico para vercel-sandbox es:

1. Importar Sandbox desde @vercel/sandbox.
2. Configurar el sandbox para instalar las Chromium system deps y agent-browser.
3. Iniciar el sandbox, ejecutar tus comandos de automatización de navegador y dejar que la microVM se apague.

El wiring de la skill lo gestiona el sistema de agentes; tu app en Vercel dispara acciones de navegador a través de esta skill, y la skill se encarga de ejecutarlas dentro de la microVM con Chrome disponible.

3. Installing vercel-sandbox as a skill

Si usas un entorno de agentes basado en skills, puedes añadir esta skill a través del repositorio:

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

Esto descarga la definición de la skill vercel-sandbox desde vercel-labs/agent-browser y la pone a disposición de tu agente o framework de automatización. La skill sabe cómo:

• Arrancar una microVM de Vercel Sandbox.
• Garantizar que Chrome y las dependencias de sistema estén instaladas.
• Invocar agent-browser para controlar la sesión de navegador.

4. Typical workflows

Una vez instalada e integrada en tu agente, vercel-sandbox puede impulsar una gran variedad de tareas de automatización de navegador en tu app de Vercel, como:

a. Automating end-to-end user flows

Usa la skill para reproducir journeys de usuario:

• Navega a la URL de tu app dentro del navegador en la microVM.
• Inicia sesión, rellena formularios y recorre los flujos.
• Captura capturas de pantalla o snapshots de HTML en cada paso.

Esto es útil para smoke tests disparados tras despliegues o ejecuciones programadas.

b. Capturing screenshots and visual checks

Ejecuta headless Chrome para:

• Capturar capturas de pantalla de página completa o de un viewport concreto.
• Validar el layout y elementos críticos de UI.
• Comparar capturas entre versiones (combinado con tu propia lógica de comparación).

c. Interacting with third-party sites

Algunas integraciones requieren páginas muy cargadas de JavaScript o flujos de autenticación complejos que no se pueden manejar solo con HTTP bruto:

• Abrir dashboards externos o sitios de partners.
• Realizar interacciones controladas (clics, esperas, evaluaciones).
• Extraer datos relevantes usando comandos de agent-browser.

Como todo se ejecuta dentro de una VM aislada, cada petición queda separada de las demás.

5. Performance and snapshots

En el repositorio se indica que puedes usar sandbox snapshots para preinstalar Chromium y agent-browser y lograr arranques por debajo del segundo. En la práctica esto implica:

• Crear una imagen snapshot de una VM donde Chrome y sus dependencias ya estén instalados.
• Hacer que futuros trabajos de navegador arranquen desde ese snapshot en lugar de instalarlo todo desde cero.

Así mantienes vercel-sandbox lo suficientemente ágil para automatización bajo demanda dentro de tu app en Vercel.

6. Operational tips

• Acuota el trabajo por VM: agrupa comandos de navegador relacionados en una sola ejecución de sandbox cuando sea posible, para minimizar el overhead de arranque de la VM.
• Gestiona timeouts: diseña tus flujos con timeouts y reintentos claros, ya que las microVMs son, por diseño, de corta duración.
• Vigila el uso de recursos: la automatización de navegador es más pesada que simples peticiones HTTP; mantén los scripts eficientes y evita páginas o pestañas innecesarias.

FAQ

What does vercel-sandbox actually run inside the microVM?

vercel-sandbox ejecuta agent-browser junto con headless Chrome dentro de una microVM de Vercel Sandbox. La VM instala las dependencias de sistema de Chromium, lanza el navegador y expone comandos para navegación, interacción y captura.

Can I use vercel-sandbox with any Vercel framework?

Sí. La skill es agnóstica al framework y está pensada para funcionar con cualquier framework desplegado en Vercel, incluidos Next.js, SvelteKit, Nuxt, Remix, Astro y otros, siempre que puedas ejecutar código del lado del servidor que se comunique con el sandbox.

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

Ejecutar Chrome directamente en una función serverless está limitado por el tamaño del bundle, la ausencia de librerías de sistema y las restricciones del runtime. vercel-sandbox, en cambio, usa una microVM dedicada por trabajo, donde puedes:

• Instalar todas las librerías de sistema que requiere Chromium.
• Ejecutar agent-browser sin restricciones de tamaño de binario.
• Mantener el estado del navegador durante toda la sesión del sandbox.

Does vercel-sandbox support persistent sessions?

Dentro de un mismo ciclo de vida del sandbox, sí. La descripción indica que puedes tener sesiones de navegador persistentes entre comandos mientras la VM esté en ejecución. Cada microVM sigue siendo efímera en conjunto: cuando el sandbox termina, su estado se descarta.

Is vercel-sandbox safe to run with untrusted tasks?

Cada ejecución de navegador se realiza en una microVM aislada de Vercel Sandbox, que proporciona una fuerte barrera de separación entre tareas. Aun así, debes seguir aplicando tus prácticas de seguridad habituales (validación de entrada, rate limiting y monitorización), pero el aislamiento por VM ayuda a contener cada trabajo.

Do I have to manage Chromium system dependencies myself?

El patrón principal del repositorio define un conjunto de Chromium system dependencies para el entorno Amazon Linux / dnf. La skill vercel-sandbox utiliza este patrón para que las librerías necesarias se instalen dentro de la VM del sandbox, no en el bundle principal de tu app. Aun así, puede que tengas que mantener la lista de dependencias alineada con tu versión de Chromium.

When should I not use vercel-sandbox?

Evita vercel-sandbox cuando:

• No estás en Vercel o no puedes activar Vercel Sandbox.
• Te basta con un cliente HTTP sencillo o una integración vía API.
• Necesitas workers de automatización de larga duración y siempre activos, en lugar de ejecuciones de sandbox bajo demanda y de corta duración.

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

Usa el siguiente comando para añadir la skill desde el repositorio vercel-labs/agent-browser:

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

Después de instalarla, configura tu agente para enrutar las peticiones de automatización de navegador (como "Vercel Sandbox browser", "microVM Chrome" o "browser automation on Vercel") hacia la skill vercel-sandbox.

Where can I learn more about the implementation details?

La referencia principal está en el repositorio vercel-labs/agent-browser, en skills/vercel-sandbox. Empieza por SKILL.md para ver:

• El patrón de configuración del sandbox.
• La lista de dependencias de sistema de Chromium.
• Cómo se espera que agent-browser se ejecute dentro de la microVM.

Úsalo como guía si quieres personalizar o extender el comportamiento de vercel-sandbox en tu propio proyecto.