vercel-sandbox

Overview

What is vercel-sandbox?

vercel-sandbox é uma skill de automação de navegador que executa agent-browser + Chrome headless dentro de microVMs efêmeras do Vercel Sandbox. Cada requisição inicia uma máquina virtual Linux leve, executa seus comandos de navegador e em seguida encerra a VM.

Como tudo roda dentro do Vercel Sandbox, essa skill foi projetada para apps implantados na Vercel (Next.js, SvelteKit, Nuxt, Remix, Astro e outros frameworks) que precisam de automação real de navegador diretamente a partir de ambientes serverless ou estilo edge.

What problems does it solve?

Runtimes serverless tradicionais não são ideais para executar o Chrome completo:

• Limites de tamanho de binário e cold starts dificultam empacotar o Chrome headless.
• As bibliotecas de sistema exigidas pelo Chromium muitas vezes não estão disponíveis.
• Sessões de navegador de longa duração ou com estado são difíceis de gerenciar.

vercel-sandbox resolve isso ao:

• Subir uma microVM dedicada para cada job de navegador.
• Instalar dependências de sistema do Chromium dentro da VM.
• Executar o agent-browser para controlar o Chrome para navegação, cliques, formulários, screenshots e mais.
• Suportar sessões de navegador persistentes entre vários comandos dentro do mesmo ciclo de vida do sandbox.
• Manter cada execução isolada e efêmera, aumentando a segurança e reduzindo vazamento entre requisições.

Who is vercel-sandbox for?

Essa skill é uma boa opção se você:

• Faz deploy na Vercel e precisa de automação real de navegador a partir do seu app ou rotas de API.
• Quer executar Chrome headless sem se preocupar com limites de tamanho de bundle.
• Precisa integrar testes de UI, scraping ou fluxos de interação em um app hospedado na Vercel.
• Precisa de ambientes de navegador de curta duração e isolados, para tarefas específicas de usuário.

Ela é especialmente relevante para:

• Apps Next.js, SvelteKit, Nuxt, Remix e Astro na Vercel.
• Times de frontend que querem adicionar checks de ponta a ponta, regressão visual ou smoke tests.
• Endpoints de API que precisam carregar sites de terceiros em um navegador real (por exemplo, fluxos de login ou apps client-side complexos).

When is it not a good fit?

vercel-sandbox talvez não seja ideal quando:

• Você não faz deploy na Vercel ou não pode usar o Vercel Sandbox.
• Você só precisa de requisições HTTP simples e não precisa de um navegador real (use em vez disso um cliente HTTP comum).
• Você precisa de processos de navegador de longa duração, sempre ligados, que rodem por muitos minutos ou horas; esta skill é pensada para microVMs efêmeras.

Se sua necessidade principal são utilitários genéricos de frontend ou tooling em tempo de build, uma skill mais simples, sem dependência de Sandbox, pode ser mais adequada.

How to Use

1. Prerequisites and dependencies

Para usar o vercel-sandbox, você precisa de:

• Um projeto na Vercel que possa usar microVMs do Vercel Sandbox.
• Uma base de código em JavaScript/TypeScript (por exemplo, rotas de API do Next.js ou server actions) onde você possa chamar o sandbox.
• @vercel/sandbox instalado no seu projeto:

pnpm add @vercel/sandbox

Dentro da VM do sandbox, o Chromium precisa de várias bibliotecas de sistema (para um ambiente Amazon Linux / baseado em dnf). O padrão definido no repositório cria um array CHROMIUM_SYSTEM_DEPS para representar esses requisitos e os instala dentro da VM antes de iniciar o Chrome.

2. Core execution pattern

O padrão central de uso do vercel-sandbox é:

1. Importar Sandbox de @vercel/sandbox.
2. Configurar o sandbox para instalar as Chromium system deps e o agent-browser.
3. Iniciar o sandbox, executar seus comandos de automação de navegador e deixar a microVM ser desligada.

A conexão com a skill é gerenciada pelo sistema de agente; seu app na Vercel dispara ações de navegador por meio dessa skill, e ela garante que tudo rode dentro da microVM com o Chrome disponível.

3. Installing vercel-sandbox as a skill

Se você estiver usando um ambiente de agente baseado em skills, pode adicionar esta skill via repositório:

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

Esse comando busca a definição da skill vercel-sandbox em vercel-labs/agent-browser e a torna disponível para seu agente ou framework de automação. A skill então sabe como:

• Iniciar uma microVM do Vercel Sandbox.
• Garantir que o Chrome e as dependências de sistema estejam instalados.
• Invocar o agent-browser para controlar a sessão de navegador.

4. Typical workflows

Depois de instalada e conectada ao seu agente, a vercel-sandbox pode dar suporte a vários tipos de tarefas de automação de navegador no seu app na Vercel, como:

a. Automating end-to-end user flows

Use a skill para reproduzir jornadas de usuário:

• Navegar até a URL do seu app dentro do navegador na microVM.
• Fazer login, preencher formulários e percorrer os fluxos.
• Capturar screenshots ou snapshots de HTML em cada etapa.

Isso é útil para smoke tests disparados por deploys ou execuções agendadas.

b. Capturing screenshots and visual checks

Execute o Chrome headless para:

• Capturar screenshots de página inteira ou apenas da área visível.
• Validar layout e elementos críticos da UI.
• Comparar screenshots entre releases (quando combinado com a sua lógica de comparação).

c. Interacting with third-party sites

Algumas integrações exigem páginas pesadas em JavaScript ou fluxos de autenticação complexos que não podem ser tratados apenas com HTTP bruto:

• Abrir dashboards externos ou sites de parceiros.
• Realizar interações controladas (cliques, esperas, avaliações).
• Extrair dados relevantes usando comandos do agent-browser.

Como tudo roda em uma VM isolada, cada requisição fica separada das demais.

5. Performance and snapshots

O repositório destaca que você pode usar sandbox snapshots para pré-instalar Chromium e agent-browser e obter startup abaixo de 1 segundo. Na prática isso significa:

• Você cria uma imagem de snapshot de uma VM onde o Chrome e as dependências já estão instalados.
• Jobs futuros de navegador iniciam a partir desse snapshot em vez de instalar tudo do zero.

Isso mantém o vercel-sandbox rápido o suficiente para automação sob demanda dentro do seu app na Vercel.

6. Operational tips

• Agrupe trabalho por VM: sempre que possível, concentre comandos relacionados de navegador em uma única execução de sandbox para reduzir o overhead de subir a VM.
• Trate timeouts: desenhe seus fluxos com timeouts e tentativas bem definidos, já que as microVMs são, por natureza, de curta duração.
• Monitore uso de recursos: automação de navegador é mais pesada que HTTP simples; mantenha os scripts eficientes e evite páginas ou abas desnecessárias.

FAQ

What does vercel-sandbox actually run inside the microVM?

vercel-sandbox executa o agent-browser junto com o Chrome headless dentro de uma microVM do Vercel Sandbox. A VM instala as dependências de sistema do Chromium, inicia o navegador e expõe comandos para navegação, interação e captura.

Can I use vercel-sandbox with any Vercel framework?

Sim. A skill é agnóstica de framework e foi pensada para funcionar com qualquer framework implantado na Vercel, incluindo Next.js, SvelteKit, Nuxt, Remix, Astro e outros, desde que você consiga executar código server-side que converse com o sandbox.

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

Executar o Chrome diretamente em uma função serverless sofre com limitações de tamanho de bundle, falta de bibliotecas de sistema e restrições de runtime. O vercel-sandbox, em vez disso, usa uma microVM dedicada por job, onde você pode:

• Instalar todas as bibliotecas de sistema exigidas pelo Chromium.
• Rodar o agent-browser sem restrições de tamanho de binário.
• Manter o estado do navegador durante toda a sessão do sandbox.

Does vercel-sandbox support persistent sessions?

Dentro de um único ciclo de vida de sandbox, sim. A descrição especifica que você pode ter sessões de navegador persistentes ao longo de vários comandos enquanto a VM estiver em execução. Cada microVM ainda é efêmera no geral: assim que o sandbox termina, o estado é descartado.

Is vercel-sandbox safe to run with untrusted tasks?

Cada execução de navegador acontece em uma microVM isolada do Vercel Sandbox, que oferece uma barreira forte de separação entre tarefas. Você ainda deve aplicar suas práticas normais de segurança (validação de entrada, rate limiting e monitoramento), mas o isolamento por VM ajuda a conter cada job.

Do I have to manage Chromium system dependencies myself?

O padrão central no repositório define um conjunto de Chromium system dependencies para o ambiente Amazon Linux / dnf. A skill vercel-sandbox usa esse padrão para que as bibliotecas necessárias sejam instaladas dentro da VM do sandbox, e não no bundle principal do seu app. Ainda assim, você pode precisar manter a lista de dependências alinhada com a versão do seu Chromium.

When should I not use vercel-sandbox?

Evite o vercel-sandbox quando:

• Você não estiver na Vercel ou não puder habilitar o Vercel Sandbox.
• Um cliente HTTP simples ou integração via API for suficiente.
• Você precisar de workers de automação de longa duração, sempre ativos, em vez de execuções de sandbox sob demanda e de curta duração.

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

Use o comando abaixo para adicionar a skill a partir do repositório vercel-labs/agent-browser:

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

Depois de instalar, configure seu agente para direcionar requisições de automação de navegador (como "Vercel Sandbox browser", "microVM Chrome" ou "browser automation on Vercel") para a skill vercel-sandbox.

Where can I learn more about the implementation details?

A principal referência está no repositório vercel-labs/agent-browser, em skills/vercel-sandbox. Comece por SKILL.md para ver:

• O padrão de configuração do sandbox.
• A lista de dependências de sistema do Chromium.
• Como o agent-browser deve rodar dentro da microVM.

Use esse material como guia se quiser customizar ou estender o comportamento do vercel-sandbox no seu próprio projeto.