vercel-sandbox

Overview

What is vercel-sandbox?

vercel-sandbox est une skill d’automatisation de navigateur qui exécute agent-browser + Chrome en mode headless à l’intérieur de microVM Vercel Sandbox éphémères. Chaque requête démarre une petite machine virtuelle Linux, exécute vos commandes de navigateur, puis détruit la VM.

Comme tout fonctionne entièrement dans Vercel Sandbox, cette skill est pensée pour les applications déployées sur Vercel (Next.js, SvelteKit, Nuxt, Remix, Astro et autres frameworks) qui ont besoin d’une vraie automatisation de navigateur directement depuis des environnements serverless ou de type edge.

What problems does it solve?

Les environnements serverless traditionnels ne sont pas adaptés à l’exécution d’un Chrome complet :

• Les limites de taille de binaire et les cold starts rendent difficile l’intégration de Chrome en mode headless.
• Les bibliothèques système dont Chromium a besoin sont souvent absentes.
• Les sessions de navigateur longues ou stateful sont compliquées à gérer.

vercel-sandbox résout ces problèmes en :

• Démarrant une microVM dédiée pour chaque job navigateur.
• Installant les dépendances système de Chromium à l’intérieur de la VM.
• Exécutant agent-browser pour piloter Chrome (navigation, clics, formulaires, captures d’écran, etc.).
• Prenant en charge des sessions de navigateur persistantes sur plusieurs commandes durant le même cycle de vie du sandbox.
• Gardant chaque exécution isolée et éphémère, ce qui améliore la sécurité et limite les fuites entre requêtes.

Who is vercel-sandbox for?

Cette skill est adaptée si vous :

• Déployez sur Vercel et avez besoin d’une vraie automatisation de navigateur depuis votre application ou vos routes API.
• Souhaitez exécuter Chrome en mode headless sans vous soucier des limites de taille de bundle.
• Devez intégrer des tests UI, du scraping ou des parcours d’interaction dans une application hébergée sur Vercel.
• Avez besoin de navigateurs isolés et de courte durée pour des tâches spécifiques à un utilisateur.

Elle est particulièrement pertinente pour :

• Les apps Next.js, SvelteKit, Nuxt, Remix et Astro sur Vercel.
• Les équipes frontend qui ajoutent des checks end-to-end, de la détection de régressions visuelles ou des smoke tests.
• Les endpoints d’API qui doivent charger des sites tiers dans un vrai navigateur (par exemple, des flux de login ou des apps client lourdes en JavaScript).

When is it not a good fit?

vercel-sandbox n’est pas idéal lorsque :

• Vous ne déployez pas sur Vercel ou ne pouvez pas utiliser Vercel Sandbox.
• Vous n’avez besoin que de simples requêtes HTTP et pas d’un vrai navigateur (utilisez plutôt un client HTTP classique).
• Vous avez besoin de processus navigateurs longs et toujours actifs qui tournent pendant plusieurs minutes ou heures ; cette skill est conçue autour de microVM éphémères.

Si vous cherchez surtout des utilitaires frontend génériques ou des outils de build, une skill plus simple sans dépendance à Sandbox sera probablement plus adaptée.

How to Use

1. Prérequis et dépendances

Pour utiliser vercel-sandbox, vous avez besoin de :

• Un projet Vercel capable d’utiliser les microVM Vercel Sandbox.
• Une base de code JavaScript/TypeScript (par exemple des routes API Next.js ou des server actions) depuis laquelle vous pouvez appeler le sandbox.
• @vercel/sandbox installé dans votre projet :

pnpm add @vercel/sandbox

À l’intérieur de la VM sandbox, Chromium a besoin de plusieurs bibliothèques système (dans un environnement Amazon Linux / basé sur dnf). Le pattern fourni dans le dépôt définit un tableau CHROMIUM_SYSTEM_DEPS qui décrit ces dépendances et les installe dans la VM avant de lancer Chrome.

2. Core execution pattern

Le pattern de base pour vercel-sandbox est :

1. Importer Sandbox depuis @vercel/sandbox.
2. Configurer le sandbox pour installer les dépendances système de Chromium et agent-browser.
3. Démarrer le sandbox, exécuter vos commandes d’automatisation de navigateur, puis laisser la microVM s’arrêter.

Le branchement de la skill est géré par le système d’agent : votre app Vercel déclenche des actions de navigateur via cette skill, qui s’assure qu’elles s’exécutent dans une microVM avec Chrome disponible.

3. Installing vercel-sandbox as a skill

Si vous utilisez un environnement d’agent basé sur des skills, vous pouvez ajouter cette skill via le dépôt :

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

Cette commande récupère la définition de la skill vercel-sandbox depuis vercel-labs/agent-browser et la rend disponible pour votre agent ou framework d’automatisation. La skill sait ensuite :

• Démarrer une microVM Vercel Sandbox.
• Vérifier que Chrome et les dépendances système sont installés.
• Invoquer agent-browser pour contrôler la session de navigateur.

4. Typical workflows

Une fois installée et reliée à votre agent, vercel-sandbox peut alimenter différents scénarios d’automatisation de navigateur dans votre app Vercel, par exemple :

a. Automating end-to-end user flows

Utilisez la skill pour reproduire des parcours utilisateurs :

• Naviguer vers l’URL de votre app dans le navigateur de la microVM.
• Se connecter, remplir des formulaires et cliquer à travers les parcours.
• Capturer des captures d’écran ou des snapshots HTML à chaque étape.

C’est utile pour des smoke tests déclenchés à chaque déploiement ou à intervalles réguliers.

b. Capturing screenshots and visual checks

Exécutez Chrome en mode headless pour :

• Capturer des captures d’écran pleine page ou limitées au viewport.
• Valider la mise en page et les éléments UI critiques.
• Comparer des captures entre différentes versions (en les combinant avec votre propre logique de comparaison).

c. Interacting with third-party sites

Certaines intégrations nécessitent des pages très chargées en JavaScript ou des flux d’authentification complexes impossibles à gérer avec de simples requêtes HTTP :

• Ouvrir des dashboards externes ou des sites partenaires.
• Réaliser des interactions contrôlées (clics, attentes, évaluations).
• Extraire les données pertinentes via les commandes agent-browser.

Comme tout s’exécute dans une VM sandboxée, chaque requête est isolée des autres.

5. Performance and snapshots

Le dépôt indique que vous pouvez utiliser des sandbox snapshots pour préinstaller Chromium et agent-browser et obtenir un démarrage en dessous de la seconde. Concrètement :

• Vous créez une image snapshot d’une VM dans laquelle Chrome et ses dépendances sont déjà installés.
• Les jobs navigateurs suivants repartent de ce snapshot plutôt que de tout réinstaller à chaque fois.

Cela permet à vercel-sandbox de rester suffisamment réactif pour de l’automatisation à la demande dans votre app Vercel.

6. Operational tips

• Regroupez le travail par VM : regroupez les commandes navigateur liées dans une même exécution du sandbox pour limiter le coût de démarrage des VM.
• Gérez les timeouts : concevez vos flux avec des timeouts clairs et des tentatives de retry, car les microVM sont par nature de courte durée.
• Surveillez l’usage des ressources : l’automatisation de navigateur est plus gourmande que de simples requêtes HTTP ; gardez vos scripts efficaces et évitez les pages ou onglets superflus.

FAQ

What does vercel-sandbox actually run inside the microVM?

vercel-sandbox exécute agent-browser aux côtés de Chrome en mode headless dans une microVM Vercel Sandbox. La VM installe les dépendances système de Chromium, lance le navigateur et expose des commandes pour la navigation, l’interaction et la capture.

Can I use vercel-sandbox with any Vercel framework?

Oui. La skill est agnostique du framework et conçue pour fonctionner avec n’importe quel framework déployé sur Vercel, y compris Next.js, SvelteKit, Nuxt, Remix, Astro, et d’autres, tant que vous pouvez exécuter du code côté serveur qui communique avec le sandbox.

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

Exécuter Chrome directement dans une fonction serverless est limité par la taille du bundle, l’absence de bibliothèques système et les contraintes du runtime. vercel-sandbox utilise au contraire une microVM dédiée par job, où vous pouvez :

• Installer toutes les bibliothèques système requises par Chromium.
• Exécuter agent-browser sans contraintes de taille de binaire.
• Conserver l’état du navigateur pendant toute la durée de la session sandbox.

Does vercel-sandbox support persistent sessions?

Oui, au sein d’un même cycle de vie de sandbox. La description indique que vous pouvez conserver des sessions de navigateur persistantes sur plusieurs commandes tant que la VM est en cours d’exécution. Chaque microVM reste toutefois éphémère : une fois le sandbox terminé, son état est supprimé.

Is vercel-sandbox safe to run with untrusted tasks?

Chaque exécution de navigateur se fait dans une microVM Vercel Sandbox isolée, qui fournit une séparation forte entre les tâches. Vous devez malgré tout appliquer vos bonnes pratiques de sécurité (validation d’entrée, rate limiting, monitoring), mais l’isolation par VM aide à contenir chaque job.

Do I have to manage Chromium system dependencies myself?

Le pattern principal décrit dans le dépôt définit un ensemble de dépendances système Chromium pour l’environnement Amazon Linux / dnf. La skill vercel-sandbox utilise ce pattern afin que les bibliothèques nécessaires soient installées dans la VM sandbox, et non dans votre bundle principal. Vous devrez cependant garder cette liste de dépendances alignée avec la version de Chromium que vous utilisez.

When should I not use vercel-sandbox?

Évitez vercel-sandbox lorsque :

• Vous n’êtes pas sur Vercel ou ne pouvez pas activer Vercel Sandbox.
• Un simple client HTTP ou une intégration d’API suffit.
• Vous avez besoin de workers d’automatisation longue durée et toujours actifs plutôt que d’exécutions à la demande et de courte durée dans un sandbox.

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

Utilisez la commande suivante pour ajouter la skill depuis le dépôt vercel-labs/agent-browser :

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

Après l’installation, configurez votre agent pour router les requêtes d’automatisation de navigateur (par exemple "Vercel Sandbox browser", "microVM Chrome" ou "browser automation on Vercel") vers la skill vercel-sandbox.

Where can I learn more about the implementation details?

La référence principale se trouve dans le dépôt vercel-labs/agent-browser, sous skills/vercel-sandbox. Commencez par SKILL.md pour découvrir :

• Le pattern de configuration du sandbox.
• La liste des dépendances système de Chromium.
• La façon dont agent-browser est censé s’exécuter à l’intérieur de la microVM.

Servez-vous-en comme guide si vous souhaitez personnaliser ou étendre le comportement de vercel-sandbox dans votre propre projet.