vercel-sandbox

Overview

What is vercel-sandbox?

vercel-sandbox ist ein Browser-Automatisierungs-Skill, der agent-browser + headless Chrome in ephemeren Vercel Sandbox microVMs ausführt. Für jede Anfrage wird eine schlanke Linux-VM gestartet, Ihre Browser-Befehle werden ausgeführt und die VM anschließend wieder beendet.

Da alles vollständig in Vercel Sandbox läuft, ist dieser Skill für auf Vercel deployte Apps (Next.js, SvelteKit, Nuxt, Remix, Astro und andere Frameworks) ausgelegt, die echte Browser-Automatisierung direkt aus serverlosen oder Edge-ähnlichen Umgebungen benötigen.

What problems does it solve?

Klassische Serverless-Runtimes sind für den Betrieb eines vollständigen Chrome nicht besonders geeignet:

• Beschränkte Binary-Größen und Cold Starts erschweren das Bundling von headless Chrome.
• Die von Chromium benötigten Systembibliotheken fehlen häufig.
• Langlebige oder zustandsbehaftete Browser-Sessions sind schwer zu verwalten.

vercel-sandbox löst diese Probleme, indem es:

• Für jeden Browser-Job eine dedizierte microVM startet.
• Chromium System Dependencies innerhalb der VM installiert.
• agent-browser ausführt, um Chrome für Navigation, Klicks, Formulare, Screenshots und mehr zu steuern.
• Persistente Browser-Sessions über mehrere Commands innerhalb desselben Sandbox-Lifecycles ermöglicht.
• Jeden Lauf isoliert und ephemer hält, was Sicherheit erhöht und Leaks zwischen Requests reduziert.

Who is vercel-sandbox for?

Dieser Skill passt gut, wenn Sie:

• Auf Vercel deployen und echte Browser-Automatisierung aus Ihrer App oder aus API-Routen heraus benötigen.
• headless Chrome nutzen möchten, ohne sich um Bundle-Size-Limits zu kümmern.
• UI-Tests, Scraping oder Interaktionsflows in eine auf Vercel gehostete Anwendung integrieren wollen.
• Kurzlebige, isolierte Browser-Umgebungen für benutzerspezifische Aufgaben benötigen.

Besonders relevant ist er für:

• Next.js-, SvelteKit-, Nuxt-, Remix- und Astro-Apps auf Vercel.
• Frontend-Teams, die End-to-End-Checks, visuelle Regressionstests oder Smoke Tests ergänzen möchten.
• API-Endpunkte, die Drittanbieter-Seiten in einem echten Browser laden müssen (z. B. Login-Flows oder komplexe Client-Side-Apps).

When is it not a good fit?

vercel-sandbox ist möglicherweise nicht ideal, wenn:

• Sie nicht auf Vercel deployen oder Vercel Sandbox nicht nutzen können.
• Sie nur einfache HTTP-Requests brauchen und kein echter Browser erforderlich ist (verwenden Sie stattdessen einen einfachen HTTP-Client).
• Sie langlebige, dauerhaft laufende Browser-Prozesse benötigen, die viele Minuten oder Stunden aktiv sind; dieser Skill basiert auf kurzlebigen microVMs.

Wenn Sie primär generische Frontend-Utilities oder Build-Time-Tooling suchen, ist ein einfacherer Skill ohne Sandbox-Abhängigkeit vermutlich besser geeignet.

How to Use

1. Prerequisites and dependencies

Um vercel-sandbox zu verwenden, benötigen Sie:

• Ein Vercel-Projekt, das Vercel Sandbox microVMs nutzen kann.
• Eine JavaScript/TypeScript-Codebasis (z. B. Next.js API routes oder server actions), von der aus Sie die Sandbox ansprechen können.
• @vercel/sandbox in Ihrem Projekt installiert:

pnpm add @vercel/sandbox

Innerhalb der Sandbox-VM benötigt Chromium mehrere Systembibliotheken (für eine Amazon Linux / dnf-basierte Umgebung). Das zugrunde liegende Pattern im Repository definiert ein CHROMIUM_SYSTEM_DEPS Array, das diese Anforderungen abbildet und sie in der VM installiert, bevor Chrome gestartet wird.

2. Core execution pattern

Das zentrale Ausführungsmuster für vercel-sandbox ist:

1. Sandbox aus @vercel/sandbox importieren.
2. Die Sandbox so konfigurieren, dass Chromium system deps und agent-browser installiert werden.
3. Die Sandbox starten, Ihre Browser-Automatisierung ausführen und die microVM anschließend herunterfahren lassen.

Das Wiring des Skills übernimmt das Agent-System; Ihre Vercel-App triggert Browser-Aktionen über diesen Skill, und der Skill stellt sicher, dass sie in der microVM mit verfügbarem Chrome laufen.

3. Installing vercel-sandbox as a skill

Wenn Sie eine Skills-basierte Agent-Umgebung nutzen, können Sie diesen Skill über das Repository hinzufügen:

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

Damit wird die vercel-sandbox Skill-Definition aus vercel-labs/agent-browser geladen und Ihrem Agent- oder Automatisierungs-Framework zur Verfügung gestellt. Der Skill weiß dann, wie er:

• Eine Vercel Sandbox microVM startet.
• Chrome und Systemabhängigkeiten sicherstellt.
• agent-browser aufruft, um die Browser-Session zu steuern.

4. Typical workflows

Sobald vercel-sandbox installiert und in Ihren Agent integriert ist, kann es eine Vielzahl von Browser-Automatisierungsaufgaben in Ihrer Vercel-App übernehmen, zum Beispiel:

a. Automating end-to-end user flows

Nutzen Sie den Skill, um User Journeys nachzustellen:

• Navigieren Sie im microVM-Browser zu der URL Ihrer App.
• Loggen Sie sich ein, füllen Sie Formulare aus und klicken Sie durch die gewünschten Flows.
• Erfassen Sie an jedem Schritt Screenshots oder HTML-Snapshots.

Dies eignet sich gut für Smoke Tests nach Deployments oder für geplante, wiederkehrende Checks.

b. Capturing screenshots and visual checks

Führen Sie headless Chrome aus, um:

• Vollseiten- oder Viewport-spezifische Screenshots zu erstellen.
• Layout und kritische UI-Elemente zu validieren.
• Screenshots über Releases hinweg zu vergleichen (in Kombination mit Ihrer eigenen Vergleichslogik).

c. Interacting with third-party sites

Manche Integrationen erfordern stark JavaScript-lastige Seiten oder komplexe Authentifizierungsflows, die sich nicht per reinem HTTP abbilden lassen:

• Öffnen Sie externe Dashboards oder Partner-Portale.
• Führen Sie kontrollierte Interaktionen aus (Klicks, Waits, Evaluations).
• Extrahieren Sie relevante Daten über agent-browser Commands.

Da alles in einer isolierten Sandbox-VM läuft, ist jeder Request von den anderen getrennt.

5. Performance and snapshots

Im Repository ist beschrieben, dass Sie sandbox snapshots verwenden können, um Chromium und agent-browser vorzuinstallieren und so Startup-Zeiten im Sub-Sekunden-Bereich zu erreichen. Praktisch bedeutet das:

• Sie erstellen ein Snapshot-Image einer VM, in der Chrome und alle Dependencies bereits installiert sind.
• Spätere Browser-Jobs starten von diesem Snapshot, statt alles erneut zu installieren.

So bleibt vercel-sandbox schnell genug für On-Demand-Automatisierung innerhalb Ihrer Vercel-App.

6. Operational tips

• Arbeit pro VM bündeln: Gruppieren Sie zusammengehörige Browser-Commands möglichst in einem einzigen Sandbox-Run, um VM-Start-Overhead zu minimieren.
• Timeouts berücksichtigen: Entwerfen Sie Ihre Flows mit klaren Timeouts und Retries, da microVMs bewusst kurzlebig sind.
• Ressourcen im Blick behalten: Browser-Automatisierung ist ressourcenintensiver als einfache HTTP-Calls; halten Sie Ihre Scripts effizient und vermeiden Sie unnötige Seiten oder Tabs.

FAQ

What does vercel-sandbox actually run inside the microVM?

vercel-sandbox führt agent-browser zusammen mit headless Chrome in einer Vercel Sandbox microVM aus. Die VM installiert die benötigten Chromium System Dependencies, startet den Browser und stellt Commands für Navigation, Interaktion und Capture bereit.

Can I use vercel-sandbox with any Vercel framework?

Ja. Der Skill ist Framework-agnostisch und soll mit jedem auf Vercel deployten Framework funktionieren, darunter Next.js, SvelteKit, Nuxt, Remix, Astro und weitere – vorausgesetzt, Sie können Server-seitigen Code ausführen, der mit der Sandbox kommuniziert.

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

Chrome direkt in einer Serverless Function auszuführen, ist durch Bundle-Größen, fehlende Systembibliotheken und Runtime-Beschränkungen limitiert. vercel-sandbox verwendet stattdessen eine dedizierte microVM pro Job, in der Sie:

• Alle für Chromium erforderlichen Systembibliotheken installieren können.
• agent-browser ohne Binary-Size-Einschränkungen ausführen.
• Browser-State für die Dauer der Sandbox-Session beibehalten können.

Does vercel-sandbox support persistent sessions?

Innerhalb eines einzelnen Sandbox-Lifecycles ja. Die Beschreibung stellt klar, dass Sie persistente Browser-Sessions über mehrere Commands hinweg haben können, solange die VM läuft. Jede microVM ist dennoch insgesamt ephemer: Sobald die Sandbox abgeschlossen ist, wird ihr Zustand verworfen.

Is vercel-sandbox safe to run with untrusted tasks?

Jeder Browser-Run läuft in einer isolierten Vercel Sandbox microVM, die eine starke Trennschicht zwischen den Tasks bereitstellt. Sie sollten weiterhin Ihre üblichen Sicherheitsmaßnahmen anwenden (Input-Validierung, Rate Limiting, Monitoring), aber die VM-Isolation hilft, jeden Job zu kapseln.

Do I have to manage Chromium system dependencies myself?

Das zentrale Pattern im Repository definiert eine Menge an Chromium System Dependencies für die Amazon Linux / dnf-Umgebung. Der vercel-sandbox Skill nutzt dieses Pattern, sodass die benötigten Bibliotheken in der Sandbox-VM installiert werden – nicht in Ihrem Haupt-App-Bundle. Sie müssen jedoch gegebenenfalls die Liste der Dependencies mit Ihrer Chromium-Version synchron halten.

When should I not use vercel-sandbox?

Vermeiden Sie vercel-sandbox, wenn:

• Sie nicht auf Vercel sind oder Vercel Sandbox nicht aktivieren können.
• Ein einfacher HTTP-Client oder eine API-Integration ausreicht.
• Sie langlebige, dauerhaft laufende Automatisierungs-Worker brauchen statt On-Demand, kurzlebiger Sandbox-Runs.

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

Verwenden Sie den bereitgestellten Befehl, um den Skill aus dem vercel-labs/agent-browser Repository hinzuzufügen:

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

Konfigurieren Sie nach der Installation Ihren Agent so, dass Browser-Automatisierungsanfragen (wie "Vercel Sandbox browser", "microVM Chrome" oder "browser automation on Vercel") an den vercel-sandbox Skill geroutet werden.

Where can I learn more about the implementation details?

Die Hauptreferenz befindet sich im vercel-labs/agent-browser Repository unter skills/vercel-sandbox. Beginnen Sie mit SKILL.md, um zu sehen:

• Das Setup-Pattern der Sandbox.
• Die Liste der Chromium System Dependencies.
• Wie agent-browser innerhalb der microVM ausgeführt werden soll.

Nutzen Sie dies als Vorlage, wenn Sie das Verhalten von vercel-sandbox in Ihrem eigenen Projekt anpassen oder erweitern möchten.