Vercel Sandbox: como usar Drives persistentes

Como usar o Vercel Sandbox com um Drive persistente

Crie o Drive uma vez com Drive.getOrCreate(), informe-o ao Sandbox.create() em um caminho absoluto de montagem, como /data, e mantenha dentro desse caminho todos os arquivos que precisam persistir. Pare o primeiro sandbox antes que outro solicite acesso de leitura e escrita. Para sandboxes paralelos de teste ou revisão, monte drive.snapshot(). Esses leitores recebem uma visão congelada e não enxergam gravações posteriores.

Um Drive se parece mais com uma sala de projeto destacável do que com um disco maior dentro de uma única máquina. O sandbox é a equipe temporária e sua oficina; o Drive é o depósito trancado que permanece quando a equipe sai e pode ser conectado à oficina seguinte.

A Vercel aponta workspaces de agentes, memória em disco, árvores de dependências, conjuntos de dados, modelos e artefatos de build como usos previstos para os Drives. Um dos primeiros usuários também relatou que um Drive por agente eliminou a reinstalação de dependências nas reconexões. Esse é o ganho que merece ser testado: menos trabalho de configuração, não apenas mais armazenamento.

Configure um workspace durável

Comece com um projeto na Vercel e autenticação local. Para o desenvolvimento local, a Vercel recomenda um token OIDC. O comando vercel env pull grava esse token de desenvolvimento em .env.local, e ele expira após 12 horas. Já um sistema externo de CI pode usar o ID da equipe, o ID do projeto e um token de acesso.

Na data de publicação, a versão estável do pacote npm é @vercel/sandbox 3.5.0. Alguns textos antigos do SDK da Vercel ainda mencionam beta privado e recomendam o canal beta, mas a página atual sobre o conceito de Drive e o lançamento de 23 de setembro confirmam o beta público nos três planos.

npm install @vercel/sandbox@3.5.0
npx vercel link
npx vercel env pull

Agora, crie um Drive, monte-o, grave um marcador e um pequeno cache, pare esse sandbox e leia os dois arquivos em um sandbox novo:

import { Drive, Sandbox } from '@vercel/sandbox';

const workspace = await Drive.getOrCreate({
  name: 'agent-workspace',
  region: 'iad1',
});

const first = await Sandbox.create({
  persistent: false,
  region: 'iad1',
  mounts: { '/data': workspace },
});

await first.runCommand('bash', [
  '-lc',
  "mkdir -p /data/.cache/demo && printf 'ready\\n' > /data/marker.txt && printf 'cached\\n' > /data/.cache/demo/package.txt",
]);
await first.stop();

const next = await Sandbox.create({
  persistent: false,
  region: 'iad1',
  mounts: { '/data': workspace },
});

const check = await next.runCommand('bash', [
  '-lc',
  'cat /data/marker.txt /data/.cache/demo/package.txt',
]);
console.log(await check.stdout());
await next.stop();

persistent: false mantém o exemplo concentrado no Drive. Um sandbox persistente tem seu próprio mecanismo de retomada baseado em snapshot, enquanto o Drive continua sendo um diretório independente, capaz de passar de um sandbox para outro. É possível combinar os dois quando você precisa de um ambiente-base reutilizável e de uma pasta de projeto que evolui separadamente.

Faça os quatro testes que realmente importam

O caminho ideal comprova a persistência. Os quatro testes a seguir mostram se a arquitetura vai se comportar bem quando vários jobs acessarem o mesmo workspace.

1. Confirme que o workspace sobrevive a um novo sandbox

Grave tanto um marcador quanto o cache em /data, pare o sandbox com acesso de escrita e crie outro sandbox com o mesmo Drive. Leia os arquivos em /data. Arquivos deixados em outros caminhos do primeiro sandbox não comprovam a persistência do Drive.

Meça quatro momentos no seu próprio job: a criação do primeiro sandbox, a instalação inicial das dependências, a primeira parada e a criação do novo sandbox com o reaproveitamento do cache. O número relevante é o tempo de configuração eliminado na segunda execução. Um Drive que preserva arquivos, mas não encurta o job real, ainda pode ser conveniente; só não terá reduzido o orçamento de computação.

2. Confirme que um leitor antigo continua vendo o estado antigo

Grave um marcador inicial, pare o processo de escrita e crie um leitor com mounts: { '/data': workspace.snapshot() }. Mantenha esse leitor em execução. Monte o Drive com leitura e escrita em outro sandbox, substitua o marcador e pare esse sandbox. O leitor já existente deve continuar retornando o marcador original, pois sua visão foi fixada no momento da montagem. Para enxergar a substituição, crie um novo leitor por snapshot.

O modelo mental correto é o de uma fotografia, não o de um espelho em tempo real. A chamada snapshot() descreve a montagem somente para leitura; a visão daquele instante é definida quando o sandbox leitor a monta. Além disso, o Drive precisa receber pelo menos uma gravação antes que um snapshot possa ser montado. Um Drive ainda não inicializado retorna drive_not_initialized.

3. Confirme que um segundo acesso de escrita é recusado

Mantenha em execução um sandbox com leitura e escrita e tente criar outro, também com leitura e escrita, usando o mesmo Drive. A Vercel permite apenas uma montagem desse tipo por vez. Não transforme a falha esperada em uma enxurrada de novas tentativas. Coloque um lease ou uma fila na frente das operações de escrita, encerre o proprietário de forma limpa e consulte Drive.list() ou currentSandboxName quando precisar descobrir a qual sandbox o Drive está conectado.

A documentação da Vercel consultada para este artigo não informa um código de erro estável para o caso do segundo processo de escrita. Considere a falha na criação do sandbox como parte do contrato e evite ramificações na lógica de produção baseadas em um código presumido.

4. Confirme que a região principal é a mesma

Crie o Drive em iad1 e tente montá-lo em um sandbox cuja região principal seja sfo1. A Vercel documenta essa incompatibilidade como drive_region_mismatch. Não é possível mudar a região de um Drive depois da criação; além disso, chamar getOrCreate() com o mesmo nome, mas outra região ou outro tamanho máximo, gera um erro conflict.

Defina a região nos dois objetos, mesmo que iad1 já seja o padrão do projeto. Uma configuração explícita impede que uma futura mudança no padrão do projeto transforme uma reinicialização comum em uma falha de região.

Depois de um teste descartável, pare todos os processos de leitura e escrita, confirme com Drive.list() ou currentSandboxName que o Drive foi desconectado e então chame await workspace.delete(). A exclusão remove os arquivos de forma permanente, e a Vercel a recusa enquanto ainda houver um sandbox conectado.

Quatro componentes diferentes na conta

O armazenamento do Drive não substitui a computação do sandbox. Ele acrescenta três medidores de armazenamento ao medidor de computação já existente. Em iad1, os preços publicados atualmente são:

Os preços variam por região. Downloads da internet, como pacotes npm e repositórios Git, são gratuitos, mas a CPU e a memória provisionada usadas na instalação continuam sendo cobradas. É por isso que um cache de dependências pode compensar: ele elimina a repetição da configuração, não o tráfego de saída do download.

Veja um exemplo útil para planejamento nos planos Pro ou Enterprise — não se trata de um benchmark. Uma árvore de dependências de 10 GB armazenada por um mês inteiro custa $0.50. Ler a árvore completa em 100 execuções representa 1,000 GB de leituras lógicas, ou $1.50. Gravar os 10 GB uma vez custa $0.04. A parcela do Drive soma $2.04, antes de computação, memória, transferência ou gravações posteriores.

No exemplo de preços da própria Vercel, uma execução de validação de código por IA com cinco minutos, 2 vCPUs e 4 GB custa cerca de $0.03 em iad1, considerando 100% de utilização da CPU. Não presuma que o Drive economizará todo esse valor. Meça o trecho da instalação que ele realmente elimina e compare a economia de computação e de tempo humano com a conta de armazenamento, leitura e gravação do Drive.

O plano Hobby inclui 15 GB de armazenamento em Drive, além de 30 GB por mês tanto para leituras quanto para gravações. Separadamente, cada Drive individual no Hobby tem limite máximo padrão de 1 GiB. O Hobby não cobra excedentes: a criação de novos sandboxes é interrompida quando uma cota é ultrapassada. Nos planos pagos, se maxSize for omitido, o limite máximo padrão de um Drive é 1 TiB, e a cota padrão pode ser configurada até 16 TiB.

Sete casos de uso, do maior para o menor ganho

1. Um produto de agentes de programação com projetos recorrentes

Dê a cada workspace de agente seu próprio Drive. Guarde sob o ponto de montagem o repositório, os arquivos gerados, as anotações das tarefas e o cache de pacotes; na interação seguinte, conecte esse Drive a um novo sandbox. A equipe do produto deixa de reconstruir o mesmo workspace a cada evento do ciclo de vida do sandbox, e o usuário ganha continuidade sem manter a computação ativa.

Este é o caso mais forte porque a frequência das reinicializações e a configuração repetida se acumulam. A regra de um único processo de escrita também combina bem com um agente ativo por workspace, enquanto prévias e testes podem usar leitores congelados.

2. Uma equipe de build que repete a mesma instalação de dependências

Preencha um Drive por meio de um processo de escrita controlado e permita que jobs posteriores montem snapshots somente para leitura da árvore de dependências. A equipe troca CPU e espera em instalações repetidas por uma cópia armazenada e pelas cobranças de leitura. A conta fecha melhor quando as dependências são grandes, mudam com menos frequência do que os jobs são executados e o caminho do cache pode ficar separado da árvore de código-fonte.

3. Um pipeline de revisão com vários agentes

Deixe um coordenador gravar o repositório candidato e, em seguida, distribua a revisão de segurança, os testes, o lint e as verificações de documentação entre leitores por snapshot. Todos os revisores começam do mesmo estado e não conseguem modificar o código-fonte compartilhado. A ressalva é intencional: se um revisor precisar de uma edição posterior feita pelo coordenador, terá de ser recriado com um novo snapshot.

4. Uma equipe de dados que reaproveita um conjunto já preparado

Use um processo de escrita para baixar, normalizar e indexar um conjunto de dados e depois monte snapshots em sandboxes de análise de curta duração. A preparação cara acontece uma só vez, enquanto leitores simultâneos recebem uma entrada consistente. É uma boa opção para avaliações reproduzíveis, mas não para dados vivos que todos os leitores esperam atualizar no próprio local.

5. Um agente de pesquisa que acumula arquivos ao longo de várias sessões

Armazene no Drive citações, texto extraído, tabelas intermediárias e um índice de busca local. Assim, um novo sandbox retoma o trabalho a partir dessa pasta, sem raspar e indexar novamente as mesmas fontes. O ganho está no material de trabalho reproduzível; o risco é tratar os arquivos como verdade durável sem um sistema separado de backup ou proveniência.

6. Um cache de modelos ou toolchains para jobs esporádicos

Pré-carregue no Drive pesos de modelos, compiladores ou outras entradas grandes e só inicie a computação quando surgir um job. A primeira leitura quando o item ainda não está em cache pode ser mais lenta porque a Vercel busca os dados no armazenamento durável; leituras posteriores com cache hit rodam na velocidade de NVMe. Esse padrão compensa quando manter os bytes usados armazenados custa menos do que deixar a computação ociosa.

7. Uma plataforma de ensino com projetos de alunos retomáveis

Atribua um Drive a cada projeto, monte-o em um sandbox novo durante a sessão e desconecte-o ao final. Os alunos mantêm seus arquivos enquanto a plataforma libera a computação. O limite de um processo de escrita ajuda a impedir que duas sessões ativas editem o mesmo projeto, mas o produto ainda precisa de regras próprias de identidade, backup e retenção.

Dois produtos que vale a pena construir

Volume de busca é um sinal de demanda, não uma previsão de receita. A pergunta útil é se o recurso elimina um trabalho doloroso para um grupo que já procura uma solução.

A opção mais forte: um broker de leases para workspaces de agentes

Crie um pequeno plano de controle que associe cada agente ou projeto de usuário a um Drive, conceda um lease temporário para um único processo de escrita, crie sandboxes leitores congelados para testes e prévias e mostre região, conexão e status de exclusão. Equipes que desenvolvem agentes de programação pagariam pela camada de coordenação porque a primitiva de armazenamento, sozinha, não decide quem controla a escrita.

Dados de palavras-chave dos Estados Unidos indicam cerca de 8,100 buscas mensais por “ai powered coding agent”, com intenção comercial. O mercado adjacente já aceita pagar por uma plataforma: a E2B oferece o Pro por $150 por mês, mais o uso, enquanto sessões persistentes de vários dias ficam na categoria Enterprise personalizada. Não é uma comparação direta de preços, mas serve como uma referência crível de orçamento para equipes que compram infraestrutura de agentes.

A menor versão vendável precisa de um mapeamento entre Drive e workspace, uma fila de escrita com expiração, criação de leitores por snapshot, visualização de uso e limpeza segura. A ressalva é a vantagem competitiva. A Vercel ou um framework de agentes pode incorporar uma camada superficial; por isso, o produto precisa oferecer política operacional, histórico de auditoria, recuperação e portabilidade entre provedores — não apenas um botão getOrCreate() mais bonito.

Uma camada de inicialização rápida para ambientes de desenvolvimento em nuvem

Reúna um template de repositório, um caminho de dependências apoiado por Drive, um aquecedor de cache, uma política explícita de região e telemetria que compare o tempo de configuração antes e depois para equipes de plataforma. Venda o resultado como uma forma de reduzir cold starts dentro de uma operação que já usa Vercel, não como um ambiente de desenvolvimento completo.

Dados de palavras-chave dos Estados Unidos indicam cerca de 1,900 buscas mensais por “cloud integrated development environment”, com CPC de $9.03. Esse valor de mídia paga sugere que há fornecedores disputando o público. O MVP pode ser restrito: primeiro Node e pnpm, uma região, uma política de cache e um painel que separe armazenamento, leituras, gravações, CPU ativa e memória.

A ressalva é o escopo. Um Drive oferece um único diretório persistente. Ele não entrega IDE, gestão de segredos, colaboração, gestão de imagens, backup nem replicação entre regiões. Um produto que prometa uma estação de trabalho completa na nuvem usando apenas essa primitiva vai frustrar os compradores.

Limites que precisam orientar a arquitetura

• Um processo de escrita significa um único proprietário. Serialize as mutações. Leitores por snapshot servem para distribuir trabalho, não para edição colaborativa.
• Os leitores ficam congelados. Um leitor em execução nunca recebe uma gravação posterior. Recrie-o com um novo snapshot.
• O primeiro snapshot exige uma gravação. Inicialize o Drive antes de iniciar sandboxes leitores.
• A região principal precisa ser a mesma. O Drive permanece em uma região e não pode ser movido. Defina a região explicitamente.
• Cada sandbox aceita quatro montagens. Todos os caminhos precisam ser absolutos e não podem se sobrepor.
• O Drive não representa a máquina inteira. Use um snapshot do sandbox para um ambiente completo. Use o Drive para um diretório que deve evoluir de forma independente.
• Leituras frias podem ser mais lentas. Leituras com cache hit e gravações rodam na velocidade de NVMe, mas isso não vale para cache misses no armazenamento durável.
• A exclusão é definitiva. A Vercel descreve drive.delete() como permanente. Um Drive não deve ser seu único backup.

Também existe um conflito na documentação disponível. O anúncio de 23 de setembro afirma que sandboxes com Drives montados não podem usar regiões de failover. Já a página sobre regiões, datada de 22 de setembro, diz que o failover pode carregar um Drive entre regiões, com maior latência de leitura. Até que a Vercel concilie as duas informações, trate o failover de Drives como não suportado na sua arquitetura e teste novamente antes de depender dele.

Se o seu job só precisa de mais espaço temporário durante uma execução, um Drive não deve ser a primeira escolha. Leia o guia relacionado sobre o disco temporário maior do Vercel Sandbox e não acrescente persistência à arquitetura.

O próximo passo na segunda-feira

Escolha, na próxima semana, um fluxo de agente que reinicie com frequência. Coloque em um único Drive apenas os arquivos do projeto e o cache de dependências, mantenha um único processo de escrita e execute os quatro testes acima. Registre o tempo de configuração antes e depois, além de armazenamento, leituras, gravações, CPU ativa e memória do Drive em linhas separadas. Só amplie o padrão se a reinicialização mais rápida compensar a conta extra de armazenamento e a regra de coordenação.

Se você precisa de um workspace durável para agentes, projetado e instrumentado para produção, eu desenvolvo sistemas de IA para produção.