Vercel Sandbox Drives: workspace persistenti per agenti

In breve

Crea il Drive una sola volta con Drive.getOrCreate(), quindi passalo a Sandbox.create() indicando un percorso di mount assoluto, per esempio /data. Tutto ciò che deve durare va salvato sotto quel percorso. Prima che un’altra sandbox chieda accesso in lettura e scrittura, arresta la prima. Per eseguire test o revisioni in parallelo, monta invece drive.snapshot(): ogni lettore ottiene una vista immutabile e non vedrà le scritture successive.

Un Drive somiglia più a una stanza di progetto separabile che a un disco più capiente dentro una singola macchina. La sandbox è la squadra temporanea con il suo laboratorio; il Drive è il deposito chiuso che rimane quando la squadra se ne va e può essere collegato al laboratorio successivo.

Vercel indica come casi d’uso dei Drive i workspace per agenti, la memoria su disco, gli alberi delle dipendenze, i dataset, i modelli e gli artefatti di build. Uno dei primi utenti ha anche segnalato che un Drive dedicato a ciascun agente permette di riconnettersi senza reinstallare le dipendenze. È questo il vantaggio da verificare: meno lavoro di configurazione, non soltanto più spazio.

Come configurare Vercel Sandbox Drives per un workspace persistente

Parti da un progetto Vercel e dall’autenticazione locale. Per lo sviluppo in locale, Vercel consiglia un token OIDC. Il comando vercel env pull salva il token di sviluppo in .env.local; il token scade dopo 12 ore. Un sistema CI esterno può invece usare un ID del team, un ID del progetto e un access token.

Al momento della pubblicazione, la release npm stabile è @vercel/sandbox 3.5.0. Alcuni testi meno recenti dell’SDK Vercel parlano ancora di beta privata e consigliano il canale beta, ma la pagina attuale dedicata ai Drive e il lancio del 23 settembre confermano la beta pubblica su tutti e tre i piani.

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

Ora crea un Drive e montalo. Scrivi al suo interno un file indicatore e una piccola cache, arresta la sandbox e verifica entrambi i file da una nuova sandbox:

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 mantiene l’esempio concentrato sul Drive. Una sandbox persistente dispone di un proprio meccanismo di ripristino basato su snapshot, mentre un Drive resta una directory indipendente, trasferibile tra sandbox diverse. I due strumenti possono anche essere combinati: un ambiente di base riutilizzabile e, accanto, una cartella di progetto che continua a evolvere separatamente.

Le quattro verifiche che contano davvero

Il caso ideale dimostra che i file persistono. Queste quattro prove mostrano invece come si comporta il progetto quando più job accedono allo stesso workspace.

1. Verifica che il workspace sopravviva a una nuova sandbox

Salva sotto /data sia un file indicatore sia la cache, arresta la sandbox che ha scritto i dati e creane un’altra collegata allo stesso Drive. A quel punto leggi i file da /data. Ciò che si trova altrove nella prima sandbox non dimostra la persistenza del Drive.

Per il tuo job, registra quattro tempi: creazione della prima sandbox, installazione iniziale delle dipendenze, primo arresto e creazione della nuova sandbox con riutilizzo della cache. Il dato utile è il tempo di configurazione eliminato dalla seconda esecuzione. Se conserva i file ma non accelera il lavoro reale, il Drive può restare comodo, ma non ha modificato il budget di calcolo.

2. Verifica che un lettore esistente mantenga la vecchia versione

Scrivi un primo indicatore, arresta la sandbox che lo ha creato e avvia un lettore con mounts: { '/data': workspace.snapshot() }. Lascialo in esecuzione. Monta poi il Drive in lettura e scrittura su un’altra sandbox, sostituisci l’indicatore e arresta la sandbox che ha scritto. Il lettore già attivo dovrebbe continuare a restituire il valore originale, perché la sua vista è stata fissata al momento del mount. Per vedere il valore nuovo, crea un altro lettore da snapshot.

Il modello mentale corretto è una fotografia, non uno specchio aggiornato in tempo reale. La chiamata snapshot() descrive il mount in sola lettura; la vista relativa a quel momento viene fissata quando la sandbox del lettore lo monta. Prima di poter montare uno snapshot, inoltre, il Drive deve aver ricevuto almeno una scrittura. Un Drive mai inizializzato restituisce drive_not_initialized.

3. Verifica che il secondo processo di scrittura venga rifiutato

Mantieni attiva una sandbox con mount in lettura e scrittura e prova a crearne una seconda con lo stesso tipo di accesso allo stesso Drive. Vercel consente un solo mount in lettura e scrittura per volta. Non trasformare l’errore previsto in una raffica di tentativi. Metti un lease o una coda davanti ai processi che scrivono, arresta correttamente il proprietario e usa Drive.list() o currentSandboxName quando devi individuare il collegamento.

La documentazione Vercel recuperata non indica un codice di errore stabile per il caso del secondo processo di scrittura. Considera il fallimento nella creazione della sandbox come il contratto da rispettare ed evita di basare la logica di produzione su un codice ipotetico.

4. Verifica che la regione principale coincida

Crea il Drive in iad1, poi prova a montarlo su una sandbox la cui regione principale è sfo1. Vercel documenta questo disallineamento come drive_region_mismatch. Dopo la creazione, la regione del Drive non può essere cambiata; inoltre, richiamare getOrCreate() con lo stesso nome ma con una regione o una dimensione massima diversa produce un errore conflict.

Imposta la regione su entrambi gli oggetti, anche se iad1 è già il valore predefinito. Una configurazione esplicita evita che una futura modifica al default del progetto trasformi un normale riavvio in un errore di regione.

Dopo un test temporaneo, arresta tutti i processi di lettura e scrittura, verifica con Drive.list() o currentSandboxName che il Drive sia scollegato, quindi chiama await workspace.delete(). L’eliminazione cancella i file in modo permanente e Vercel la rifiuta finché una sandbox resta collegata.

Il costo dipende da quattro componenti distinte

Lo storage del Drive non sostituisce il calcolo della sandbox: aggiunge tre contatori di storage a quello del calcolo già esistente. In iad1, le tariffe pubblicate attualmente sono:

Le tariffe cambiano in base alla regione. I download da Internet, come pacchetti npm e repository Git, sono gratuiti; restano però conteggiate la CPU e la memoria allocata usate per installarli. Ecco perché una cache delle dipendenze può convenire: elimina il lavoro ripetuto di configurazione, non il traffico in uscita dei download.

Questo è un esempio utile per pianificare un piano Pro o Enterprise, non un benchmark. Conservare per un mese intero un albero delle dipendenze da 10 GB costa $0.50. Leggerlo integralmente in 100 esecuzioni equivale a 1,000 GB di letture logiche, ossia $1.50. Scrivere una volta i 10 GB costa $0.04. La quota relativa al Drive ammonta quindi a $2.04, prima di calcolo, memoria, trasferimenti o scritture successive.

L’esempio di prezzo fornito da Vercel valuta circa $0.03 in iad1 un’esecuzione di validazione del codice tramite AI di cinque minuti, con 2 vCPU, 4 GB e utilizzo della CPU al 100%. Non dare per scontato che il Drive faccia risparmiare l’intero importo. Misura la parte di installazione che elimina davvero, quindi confronta il calcolo e il tempo umano risparmiati con la spesa del Drive per storage, letture e scritture.

Il piano Hobby include 15 GB di storage per i Drive, oltre a 30 GB al mese sia per le letture sia per le scritture. Separatamente, il limite predefinito di un singolo Drive Hobby è 1 GiB. Hobby non addebita eccedenze: quando si supera una quota, la creazione di nuove sandbox viene sospesa. Nei piani a pagamento, se maxSize non viene specificato, il limite predefinito di un Drive è 1 TiB e può essere configurato fino a 16 TiB.

Sette casi d’uso, in ordine di vantaggio

1. Un prodotto con coding agent e progetti ricorrenti

Assegna un Drive a ogni workspace dell’agente. Salva sotto il punto di mount il repository, i file generati, gli appunti sul task e la cache dei pacchetti, quindi collega il Drive a una nuova sandbox al turno successivo. Il team di prodotto non deve ricostruire lo stesso ambiente dopo ogni evento del ciclo di vita della sandbox e l’utente mantiene la continuità senza lasciare il calcolo sempre attivo.

È il caso d’uso più solido perché la frequenza dei riavvii amplifica il costo di ogni configurazione ripetuta. La regola di un solo processo di scrittura coincide inoltre con un agente attivo per workspace, mentre anteprime e test possono usare lettori fermi a uno snapshot.

2. Un team di build che ripete la stessa installazione

Popola un Drive da un processo di scrittura controllato, poi consenti ai job successivi di montare snapshot in sola lettura dell’albero delle dipendenze. Il team sostituisce CPU e attesa di installazioni ripetute con una copia archiviata e i relativi costi di lettura. La convenienza è maggiore quando le dipendenze sono grandi, cambiano meno spesso dei job e il percorso della cache può essere separato dall’albero dei sorgenti.

3. Una pipeline di revisione multi-agente

Un coordinatore scrive il repository candidato, poi distribuisce in parallelo revisione di sicurezza, test, linting e verifica della documentazione tra lettori da snapshot. Ogni revisore parte dallo stesso stato e non può modificare i sorgenti condivisi. Il limite è intenzionale: se serve una modifica successiva del coordinatore, il revisore va ricreato con un nuovo snapshot.

4. Un team di dati che riutilizza un dataset preparato

Affida a un unico processo il download, la normalizzazione e l’indicizzazione di un dataset, poi monta gli snapshot in sandbox di analisi di breve durata. La preparazione costosa avviene una sola volta e i lettori concorrenti ricevono input coerenti. È una buona soluzione per valutazioni ripetibili, non per un dataset vivo che ogni lettore pretende di aggiornare direttamente.

5. Un agente di ricerca che accumula file in più sessioni

Archivia sul Drive citazioni, testo estratto, tabelle intermedie e un indice di ricerca locale. Una nuova sandbox può ripartire da quella cartella invece di raccogliere e indicizzare di nuovo le stesse fonti. Il vantaggio è un materiale di lavoro riproducibile; il rischio è trattare quei file come verità duratura senza un sistema separato di backup o provenienza.

6. Una cache di modelli o toolchain per job saltuari

Precarica sul Drive i pesi dei modelli, i compilatori o altri input voluminosi, quindi avvia il calcolo solo all’arrivo di un job. La prima lettura con cache miss può essere più lenta, perché Vercel recupera i dati dallo storage durevole; le letture successive con cache hit funzionano invece alla velocità NVMe. Questo modello conviene quando tenere fermo il calcolo costerebbe più che conservare i byte effettivamente usati.

7. Una piattaforma didattica con progetti ripristinabili

Assegna un Drive a ogni progetto, montalo in una nuova sandbox per la sessione e scollegalo al termine. Gli studenti conservano i file mentre la piattaforma libera le risorse di calcolo. Il limite di un solo processo di scrittura aiuta a impedire che due sessioni attive modifichino lo stesso progetto, ma il prodotto deve comunque gestire identità, backup e criteri di conservazione.

Due prodotti che vale la pena costruire

Il volume di ricerca segnala la domanda, non prevede i ricavi. La domanda utile è un’altra: questa funzione elimina un problema doloroso per un pubblico che sta già cercando una soluzione?

La scelta più forte: un broker di lease per workspace di agenti

Costruisci un piccolo control plane che associ ogni progetto di agente o utente a un Drive, assegni un lease di scrittura con scadenza, crei sandbox di lettura basate su snapshot per test e anteprime e mostri regione, collegamenti e stato dell’eliminazione. I team che sviluppano coding agent pagherebbero questo livello di coordinamento, perché la primitiva di storage non stabilisce chi detiene il diritto di scrittura.

I dati sulle keyword negli Stati Uniti indicano circa 8,100 ricerche mensili per “ai powered coding agent”, con intento commerciale. Il mercato adiacente accetta già una spesa di piattaforma: E2B propone il piano Pro a $150 al mese più il consumo, mentre le sessioni persistenti di più giorni rientrano nel piano Enterprise personalizzato. Non è un confronto diretto dei prezzi, ma offre un riferimento credibile per il budget dei team che acquistano infrastrutture per agenti.

La versione minima vendibile richiede un’associazione Drive-workspace, una coda di scrittura con scadenza, la creazione di lettori da snapshot, una vista sui consumi e una procedura di pulizia sicura. Il punto critico è il vantaggio difendibile: Vercel o un framework per agenti possono incorporare facilmente un wrapper sottile. Il prodotto deve quindi offrire policy operative, cronologia di audit, ripristino e portabilità tra provider, non soltanto un pulsante getOrCreate() più gradevole.

Un livello di warm start per ambienti di sviluppo cloud

Prepara per i team di piattaforma un template di repository, un percorso per le dipendenze supportato dal Drive, un sistema per scaldare la cache, una policy esplicita sulle regioni e telemetria che confronti i tempi di configurazione prima e dopo. Vendi il risultato come riduzione dei cold start nell’infrastruttura Vercel esistente, non come ambiente di sviluppo completo.

I dati sulle keyword negli Stati Uniti indicano circa 1,900 ricerche mensili per “cloud integrated development environment”, con un CPC di $9.03. Questo valore nella ricerca a pagamento suggerisce che i fornitori competono per quel pubblico. L’MVP può essere circoscritto: prima Node e pnpm, una sola regione, una sola policy per la cache e una dashboard che separi storage, letture, scritture, CPU attiva e memoria.

Il limite sta nell’ampiezza del prodotto. Un Drive offre una sola directory persistente; non fornisce IDE, gestione dei secret, collaborazione, gestione delle immagini, backup o replica tra regioni. Promettere una workstation cloud completa basandosi soltanto su questa primitiva finirebbe per deludere gli acquirenti.

Limiti che devono guidare l’architettura

• Un solo processo di scrittura significa un solo proprietario. Serializza le modifiche. I lettori da snapshot servono per distribuire il lavoro, non per modificare insieme gli stessi file.
• I lettori restano fermi. Un lettore già attivo non riceve mai una scrittura successiva. Ricrealo con un nuovo snapshot.
• Il primo snapshot richiede una scrittura. Inizializza il Drive prima di avviare le sandbox di lettura.
• La regione principale deve coincidere. Il Drive rimane in una regione e non può essere spostato. Imposta la regione in modo esplicito.
• Ogni sandbox accetta quattro mount. I percorsi devono essere assoluti e non possono sovrapporsi.
• Un Drive non rappresenta l’intera macchina. Usa lo snapshot di una sandbox per un ambiente completo; usa un Drive per una directory che deve evolvere in modo indipendente.
• Le letture a freddo possono essere più lente. Le letture con cache hit e le scritture operano alla velocità NVMe, mentre i cache miss che accedono allo storage durevole no.
• L’eliminazione è definitiva. Vercel descrive drive.delete() come permanente. Il Drive non dovrebbe essere l’unico backup.

Esiste inoltre una contraddizione nella documentazione disponibile. L’annuncio del 23 settembre afferma che le sandbox con Drive montati non possono usare regioni di failover; la pagina sulle regioni, datata 22 settembre, sostiene invece che il failover può caricare un Drive tra regioni con una latenza di lettura superiore. Finché Vercel non chiarirà la discrepanza, considera il failover del Drive non supportato nella tua architettura e ripeti il test prima di farvi affidamento.

Se il tuo job ha bisogno soltanto di più spazio temporaneo durante una singola esecuzione, un Drive non è la prima soluzione da adottare. Consulta la guida complementare sul disco scratch più capiente di Vercel Sandbox e lascia la persistenza fuori dall’architettura.

L’azione da fare lunedì

La prossima settimana scegli un workflow per agenti con molti riavvii. Sposta su un solo Drive esclusivamente i file di progetto e la cache delle dipendenze, mantieni un unico processo di scrittura ed esegui le quattro verifiche descritte sopra. Registra i tempi di configurazione prima e dopo; separa inoltre storage del Drive, letture, scritture, CPU attiva e memoria. Estendi questo schema solo se la riduzione dei tempi di riavvio giustifica il costo aggiuntivo dello storage e la regola di coordinamento.

Se vuoi progettare e misurare un workspace persistente per agenti pronto per la produzione, realizzo sistemi AI per la produzione.