Come eseguire sandboxd in proprio su un VPS

Che cos'è sandboxd e cosa si ottiene eseguendolo in proprio

Per eseguire sandboxd in proprio servono un server Linux con Docker e un nome di dominio. Si invia un prompt, un agente di coding crea un'applicazione reale all'interno di un container isolato e l'applicazione diventa disponibile al relativo URL di anteprima. I builder che trasformano un prompt in un'applicazione sono la categoria hosted più visibile del 2026; sandboxd è la soluzione eseguita sul proprio VPS, con licenza MIT e codice generato archiviato sul proprio disco.

Il design è volutamente essenziale. Un control plane scritto in Go gestisce Docker, Traefik v3 instrada ogni hostname di anteprima, SQLite conserva lo stato e ogni app viene eseguita all'interno di un container. Non sono presenti Kubernetes né un server di database separato. Per questo può funzionare anche su un server con 2 vCPU.

L'intero modello si basa su quattro oggetti. Una app è il progetto persistente e contiene il nome, i metadati git e i secret. Un sandbox è il container Docker in cui viene eseguita l'app; un'app punta a un solo sandbox alla volta. Un workspace contiene i file dell'app, archiviati sull'host e conservati anche dopo la rimozione del container. Un task è un singolo prompt inviato all'agente all'interno del sandbox. Arrestare un sandbox libera memoria e conserva i file. Eliminarlo rimuove il container e l'app può avviarne uno nuovo.

In che modo sandboxd differisce da Dify e OpenHands?

Questi tre strumenti vengono spesso confusi perché eseguono tutti un LLM (large language model) sul server, ma producono risultati diversi. Dify crea applicazioni LLM: interfacce di chat, pipeline di retrieval e workflow che chiamano un modello ogni volta che qualcuno li utilizza. Il modello fa parte del prodotto finito. OpenHands lavora su un repository già esistente: lo si indirizza al codice, quindi legge i file, esegue comandi e propone modifiche. sandboxd parte da zero. Crea la struttura di un progetto a partire da un preset, lo compila in un container vuoto e fornisce un URL da consultare. Il risultato è una normale applicazione React o FastAPI che non richiede alcun modello per funzionare.

La scelta dipende quindi dal risultato finale desiderato. sandboxd serve per partire da una frase e conservare il codice prodotto. Gli altri due strumenti servono quando il repository o il prodotto basato sul modello esistono già.

L'altra differenza riguarda l'età del progetto. È l'aspetto da valutare prima di basarci sopra qualcosa di realmente operativo.

[
  {
    "tool": "sandboxd",
    "github_stars": "875",
    "forks": "50"
  },
  {
    "tool": "OpenHands",
    "github_stars": "83,091",
    "forks": "10,711"
  },
  {
    "tool": "Dify",
    "github_stars": "151,320",
    "forks": "23,886"
  }
]

sandboxd ha 875 stelle, rispetto alle 83,091 di OpenHands e alle 151,320 di Dify. Il repository è stato creato il 3 giugno 2026, quindi ad agosto 2026 ha due mesi, mentre OpenHands risale a marzo 2024 e Dify ad aprile 2023. La release v0.1.0 è stata pubblicata il 6 giugno 2026 e la v0.3.6 il 1 agosto 2026. Il progetto si definisce beta e specifica che le release 0.x possono introdurre modifiche incompatibili. Questi numeri indicano il rischio legato alle dipendenze, non esprimono un giudizio sulla qualità: un progetto vecchio di due mesi ha avuto soltanto due mesi perché altre persone ne individuassero i bug.

Cosa richiede il server e cosa si rompe quando le risorse sono insufficienti

Il progetto indica 2 vCPU e 4 GB di RAM come requisiti sufficienti per iniziare. È corretto per il control plane e una sandbox di piccole dimensioni, ma non basta se due persone eseguono build contemporaneamente. Suddividi la memoria disponibile per componente. Traefik e il control plane Go occupano poca memoria. Ogni sandbox in esecuzione include una toolchain completa per Node o Python e il picco si verifica durante un npm install seguito da una build di produzione. Prevedi 8 GB per un server che deve mantenere attive alcune applicazioni e considera la swap una rete di sicurezza, non una riserva di capacità: una build che usa la swap richiede minuti invece di secondi.

Quando la memoria si esaurisce si verificano due errori diversi, che hanno un aspetto completamente differente. All'interno di una sandbox, il container raggiunge il limite rigido di --memory impostato da sandboxd e il kernel termina il processo più grande; la build si interrompe senza un messaggio utile da parte dell'agent. docker ps -a mostra il codice di uscita 137 per quel container e docker inspect restituisce "OOMKilled": true. Una build Node che termina in questo modo spesso stampa prima JavaScript heap out of memory.

Il secondo errore si verifica sull'host. sandboxd esegue un pressure reaper che arresta le sandbox quando la memoria dell'host scende troppo; su un server con risorse limitate, quindi, una sandbox può scomparire mentre osservi la relativa anteprima. I file sono al sicuro e la richiesta successiva all'URL dell'anteprima la riattiva, ma un'attività in esecuzione quando il container viene arrestato non riprende.

Il disco è il problema meno evidente. Ogni applicazione mantiene il proprio workspace sull'host e un progetto JavaScript contiene una struttura node_modules delle dimensioni di centinaia di megabyte. Dieci applicazioni occupano diversi gigabyte di dipendenze, senza contare le immagini. Inizia con 40 GB e controlla l'utilizzo:

docker system df
sudo du -sh /var/lib/sandboxed/workspaces

In v0.3.6, la release fissata da questa guida, la directory dati predefinita è /var/lib/sandboxed, scritta con la e aggiuntiva. Digitare /var/lib/sandboxd in quel percorso non produce alcun risultato e porta a perdere cinque minuti in modo fuorviante. Questo è cambiato in v0.3.9 (25 August 2026). Gli installer più recenti collocano le nuove installazioni in /var/lib/sandboxd e mantengono /var/lib/sandboxed soltanto per un'installazione che si trova già in quel percorso. Su un server configurato inizialmente con una release successiva, usa il percorso senza e in ogni comando riportato di seguito.

Installare una release fissata di sandboxd

Docker Engine con il plugin Compose e git devono essere già installati sul server. La guida Installare Docker su un VPS descrive questa procedura.

docker compose version
git --version

Entrambi i comandi devono restituire una versione. docker: 'compose' is not a docker command indica che il plugin Compose v2 non è installato. L’installer preferisce il plugin, ma usa come alternativa un binario docker-compose autonomo, se disponibile, e si interrompe con Docker Compose not found solo quando non trova nessuna delle due opzioni. I comandi di questa guida usano docker compose, quindi installare il plugin è la soluzione più semplice.

L’installer è uno script shell scaricato dalla rete. Leggilo prima di eseguirlo e fissa la versione.

curl -fsSL https://raw.githubusercontent.com/tastyeffectco/sandboxd/v0.3.6/install.sh -o install-sandboxd.sh
less install-sandboxd.sh
SANDBOXD_REF=v0.3.6 bash install-sandboxd.sh

SANDBOXD_REF è il riferimento Git che l’installer effettua il checkout in $HOME/.sandboxd/src e, per impostazione predefinita, usa main. Se non lo imposti, l’installazione corrisponde a ciò che è stato integrato quella mattina. Questo è importante in un progetto che ha pubblicato sei release soltanto a luglio 2026. Fissa la versione e aggiorna solo intenzionalmente, dopo aver letto il changelog. Al 12 ottobre 2026, la release più recente è v0.3.22, ovvero sedici release successive alla v0.3.6 fissata qui.

Lo script clona il codice sorgente, compila le immagini, avvia lo stack con docker compose up -d e, al termine, stampa l’URL della console e un token API. Salva il token in un luogo sicuro. È la credenziale per un’API che controlla Docker con privilegi root.

curl http://127.0.0.1:9090/healthz

Quando il control plane è attivo, il comando stampa ok. Se non stampa nulla, lo stack non è stato avviato: esegui docker compose ps da ~/.sandboxd/src per verificare quale servizio è arrestato, quindi docker compose logs sandboxd per determinarne la causa.

Accesso alla console su un server remoto

La console è pubblicata tramite Traefik su HTTP_PORT, che per impostazione predefinita è 80, usando il nome host http://console.localhost. Traefik instrada le richieste in base al nome host. Se inserisci nel browser l'indirizzo IP del server, nessuna regola corrisponde e viene restituito un errore 404. Fino a quando non configuri un dominio reale, inoltra la porta e mantieni il nome host:

ssh -L 8080:127.0.0.1:80 you@your-vps

Quindi apri http://console.localhost:8080 sul laptop. Su Linux e macOS, qualsiasi nome che termina con .localhost viene risolto in 127.0.0.1. La richiesta passa quindi attraverso il tunnel con l'header Host corretto. Imposta la password della console al primo accesso.

Assegna un modello all’agente

Nell’immagine di base sono inclusi due agenti di codifica: OpenCode e Claude Code. SANDBOXD_DEFAULT_AGENT determina quale agente esegue un’attività che non ne specifica uno e, per impostazione predefinita, usa opencode. Se non colleghi alcuna chiave, le attività vengono eseguite sui modelli gratuiti senza chiave di OpenCode Zen. In questo modo la prima build non ha costi e puoi testare l’intero flusso prima di sostenere una spesa.

Collega una tua chiave quando vuoi usare un modello più potente. Le chiavi vengono inviate al control plane e non entrano mai nella sandbox: sono archiviate in forma crittografata nella directory dei dati e inserite nelle richieste da un credential proxy. Di conseguenza, né l’agente né il codice che scrive possono leggerle.

export API=http://127.0.0.1:9090
export SANDBOXD_TOKEN=sk_...                       # printed by the installer
export AUTH="Authorization: Bearer $SANDBOXD_TOKEN"

curl -s -XPOST $API/v1/agents/claude-code/api-key -H "$AUTH" \
  -H 'content-type: application/json' \
  -d '{"api_key":"sk-ant-..."}'

La console offre la stessa configurazione in Settings, AI Agents e include un flusso OAuth guidato, se vuoi usare un abbonamento Claude invece di una chiave API. Il modello predefinito per ogni agente si trova nello stesso pannello e una singola attività può sostituirlo.

Crea una piccola applicazione dall’inizio alla fine

Crea l’applicazione, avvia il relativo sandbox, quindi invia un prompt. Gli identificativi vengono restituiti in formato JSON e il quickstart li estrae con sed, quindi non è necessario installare jq.

APP=$(curl -s -XPOST $API/v1/apps -H "$AUTH" \
  -H 'content-type: application/json' \
  -d '{"name":"todo","runtime_preset":"react-vite"}' \
  | sed -E 's/.*"id":"([^"]+)".*/\1/')

SB=$(curl -s -XPOST $API/v1/apps/$APP/sandbox -H "$AUTH" \
  -H 'content-type: application/json' -d '{"ports":[3000]}' \
  | sed -E 's/.*"id":"([^"]+)".*/\1/')

echo "app=$APP sandbox=$SB"

Entrambe le variabili devono contenere un identificativo. Un $SB vuoto indica che il sandbox non è mai stato avviato. Le cause più comuni sono che l’immagine di base è ancora in fase di build oppure che sull’host non è disponibile memoria sufficiente. Un 401 al posto di un identificativo indica che il bearer token non è corretto.

curl -s -XPOST $API/v1/sandboxes/$SB/tasks -H "$AUTH" \
  -H 'content-type: application/json' \
  -d '{"prompt":"Add a todo list with a text input, an add button, and a delete button on each row. Keep the list in localStorage.","agent":"opencode"}'

La risposta contiene un task id. GET /v1/sandboxes/$SB/tasks/<task id> ne restituisce il risultato, mentre il percorso /events relativo allo stesso task è uno stream SSE (server sent events) in tempo reale che mostra le attività dell’agente. La console visualizza lo stesso stream come chat.

L’applicazione è quindi disponibile all’indirizzo http://s-<sandbox id>-3000.preview.localhost, dove 3000 è la porta richiesta. Se il sandbox era inattivo, la prima richiesta raggiunge il catch-all di Traefik. sandboxd avvia il container, attende che la porta risponda e visualizza una breve pagina di avvio che si aggiorna automaticamente e apre l’applicazione. Un’anteprima che rimane su quella pagina indica che il processo interno non è in ascolto sulla porta dichiarata nel sandbox.yaml dell’applicazione.

Pubblicare le anteprime su un dominio reale con HTTPS

Ogni sandbox riceve il proprio hostname, quindi un unico record DNS wildcard copre tutte le sandbox. Puntare *.preview.yourdomain.com all'indirizzo IP del server con un record A. Impostare quindi le variabili delle anteprime in .env in ~/.sandboxd/src:

PREVIEW_DOMAIN=yourdomain.com
PREVIEW_ENTRYPOINT=websecure
PREVIEW_TLS=true
SANDBOXD_API_AUTH_DISABLED=false

Traefik richiede la configurazione corrispondente: abilitare l'entrypoint websecure in traefik/traefik.yml e aggiungere un resolver dei certificati. Usare la challenge DNS-01, perché un unico certificato wildcard copre tutti gli hostname delle anteprime. Con HTTP-01, ogni nuova sandbox richiederebbe una propria emissione; un pomeriggio intenso di build può così raggiungere rapidamente i limiti di frequenza di Let's Encrypt. Certificati wildcard tramite la challenge DNS-01 illustra la configurazione DNS.

cd ~/.sandboxd/src
docker compose up -d

Gli URL delle anteprime diventano https://s-<id>-3000.preview.yourdomain.com. Aprire le porte 80 e 443 nel firewall e lasciare la porta 9090 chiusa verso Internet: vedere regole firewall di base per ufw. Chiunque riesca a indovinare un hostname di anteprima può caricare l'applicazione, quindi trattare le anteprime come pubbliche.

Se si preferisce evitare completamente dominio, DNS e certificati, i manutentori ora offrono sandboxd Cloud. Il servizio assegna al server un indirizzo HTTPS pubblico sotto sandboxd.io al costo di 9.99 dollari per server al mese, oppure 4.99 con lo sconto di lancio, a ottobre 2026. Prima di farvi affidamento, verificare quale release richiede bloccandola alla versione v0.3.6.

Dove vengono salvati i codici generati e si possono esportare?

Sul server host, nella directory dei dati. Ogni workspace è una directory normale in /var/lib/sandboxed/workspaces/<id>/ in un'installazione v0.3.6, montata nel container tramite bind mount; i file dell'applicazione si trovano in /home/sandbox/workspace/app all'interno della sandbox. Lo stato del control plane è contenuto in un unico file SQLite in state/sandboxd.db, mentre le credenziali crittografate degli agenti si trovano in agent-auth/. Nulla è nascosto in un layer del container, quindi un backup consiste nella copia della directory e di quel file di database. backup restic su un VPS gestisce entrambi.

sudo ls /var/lib/sandboxed/workspaces
sudo du -sh /var/lib/sandboxed/workspaces/*

L'esportazione Git è integrata, non aggiunta separatamente. L'API espone lo stato e il diff per la lettura, quindi consente di eseguire commit e push:

curl -s $API/v1/apps/$APP/git/status -H "$AUTH"

curl -s -XPOST $API/v1/apps/$APP/git/commit -H "$AUTH" \
  -H 'content-type: application/json' \
  -d '{"message":"todo list, first pass"}'

curl -s -XPOST $API/v1/apps/$APP/git/push -H "$AUTH" \
  -H 'content-type: application/json' -d '{"branch":"todo-first-pass"}'

Il push viene sempre eseguito su un nuovo branch. Se si omette branch, viene usato il valore predefinito sandboxd/<slug>-<shortsha>. main, master e il branch da cui è stato eseguito l'import vengono rifiutati, quindi il merge va eseguito sul repository remoto.

Un repository remoto privato richiede un personal access token, da impostare una sola volta nella console, in Settings, Git credentials. Il token viene archiviato in forma crittografata e resta fuori dalla sandbox, quindi l'agent non può leggerlo né usarlo per eseguire push senza autorizzazione. Eseguire il push spesso e fin dalle prime modifiche. Fino a quel momento, la directory del workspace è l'unica copia del codice e DELETE /v1/apps/<id> la elimina senza possibilità di recupero.

Quanto costa una build in token del modello?

sandboxd non misura la spesa, quindi il dato rilevante è disponibile nella console del provider. I modelli gratuiti OpenCode Zen non hanno costi, ma sono più lenti e meno efficaci rispetto a un modello a pagamento. La differenza si nota dal numero maggiore di cicli di correzione necessari per qualsiasi progetto più complesso di un'applicazione di prova.

L'importo dipende dal funzionamento del ciclo dell'agente. A ogni turno viene reinviato il contesto necessario, quindi il costo dipende dal numero di turni, non dal numero di applicazioni. Un prompt che produce subito il risultato costa poco. Quindici cicli con richieste come "ora correggi la spaziatura" su un progetto con cinquanta file costano invece molto di più, perché il contenuto dei file viene trasmesso ogni volta. I token di input e output hanno prezzi diversi, e quanto costa un agente di coding per sessione fornisce un intervallo realistico. Imposta un limite di spesa rigido nella console del provider prima di affidare le credenziali a un ciclo eseguito senza supervisione.

Pulizia delle sandbox obsolete

Il processo di pulizia delle sandbox inattive arresta ogni sandbox rimasta inattiva oltre SANDBOXD_IDLE_THRESHOLD_SECONDS, che per impostazione predefinita corrisponde a 2100 secondi, ovvero 35 minuti. In questo modo libera la RAM ma conserva i file; la richiesta successiva all’URL di anteprima riattiva il container. Imposta un valore inferiore sui server con poche risorse, perché 35 minuti di container inattivi equivalgono a 35 minuti di memoria non disponibile.

Arrestare una sandbox non significa eliminarla, ed è in questa fase che i dischi si riempiono senza segnali evidenti. Una sandbox arrestata conserva il proprio workspace e il proprio container. La rimozione della sandbox mantenendo l’applicazione è un DELETE sulla sandbox e rimuove sia il container sia il workspace. La rimozione dell’applicazione elimina tutto in modo permanente.

curl -s -XPOST $API/v1/sandboxes/$SB/stop -H "$AUTH"     # frees RAM, keeps files
curl -s -XDELETE $API/v1/sandboxes/$SB -H "$AUTH"        # container and workspace gone
curl -s -XDELETE $API/v1/apps/$APP -H "$AUTH"            # app and everything under it

Dopo alcune settimane di esperimenti, docker system df mostrerà più spazio recuperabile dalle immagini di quanto previsto, perché ogni applicazione che ha scaricato il proprio toolchain ha lasciato dei layer. docker image prune rimuove quelli dangling. Controlla prima GET /v1/apps, perché un’immagine ancora utilizzata da una sandbox inattiva non è garbage.

Cosa offre e cosa non offre il confine del container

Ogni sandbox viene eseguita da un utente senza privilegi, con un filesystem root in sola lettura, tutte le capability Linux rimosse, no-new-privileges impostato, un limite superiore per la memoria e un limite per i processi. Il progetto dichiara apertamente questo limite: un container Linux con kernel condiviso è un forte confine di isolamento, ma un debole confine di sicurezza. Un bug del kernel può compromettere l'host.

Due aspetti richiedono un intervento. Nel build self-hosted, il traffico in uscita dalla sandbox è aperto. Il codice generato può quindi raggiungere Internet, la rete locale e gli endpoint dei metadati cloud. Nel codice sorgente esiste un sottosistema nftables per il traffico in uscita, ma è disabilitato nella build portabile Docker Compose. I limiti devono quindi essere applicati dal firewall dell'host. Inoltre, l'API del control plane equivale di fatto a root sull'host, perché controlla il socket Docker. Per impostazione predefinita è in ascolto su 127.0.0.1:9090; SANDBOXD_API_AUTH_DISABLED deve rimanere false e l'API non deve mai essere pubblicata su Internet.

Se prevedi di consentire ad altre persone di inviare prompt al tuo server, questo modello non è sufficiente da solo. Il progetto indica gVisor con SANDBOXD_RUNTIME=runsc, che inserisce un kernel in userspace tra la sandbox e l'host. Secondo le misurazioni del progetto, questa configurazione rende le installazioni dei pacchetti circa 1.7 volte più lente e le attività con uso intensivo delle syscall circa 4 volte più lente. La soluzione con isolamento più forte consiste nell'assegnare una macchina a ogni tenant, seguendo lo stesso principio di eseguire gli agenti di coding in una VM usa e getta.

Conviene basarsi su un progetto che ha due mesi?

Per un ambiente di build personale, sì, adottando le precauzioni necessarie: blocca SANDBOXD_REF, esegui il backup della directory dei dati (/var/lib/sandboxed su v0.3.6, /var/lib/sandboxd su una nuova installazione di v0.3.9 o versioni successive) e invia ogni applicazione importante a un repository remoto Git. Per qualsiasi applicazione utilizzata da un cliente, attendi la versione 1.0 oppure prevedi possibili malfunzionamenti, perché i manutentori dichiarano chiaramente che la versione 0.x può cambiare senza preavviso. I manutentori offrono anche un'installazione gestita: 199 dollari per la configurazione e 79 dollari al mese per l'esecuzione, alla data di ottobre 2026. Questo elemento è utile per valutare se il progetto abbia prospettive sufficienti per continuare a essere mantenuto.

Il rischio è accettabile soprattutto per il risultato ottenuto. sandboxd produce un'applicazione ordinaria in un normale repository Git. Se lo sviluppo del progetto si arresta, conservi quindi il codice e perdi soltanto il wrapper. È una posizione molto più favorevole rispetto a un builder ospitato che mantiene il controllo del progetto. Per una panoramica più ampia di ciò che merita un posto sul tuo server quest'anno, consulta cosa vale la pena ospitare autonomamente nel 2026.

FAQ

Quali sono le specifiche minime del server per sandboxd?

Il progetto indica che 2 vCPU e 4 GB di RAM sono sufficienti per iniziare. Questa configurazione copre il control plane, Traefik e un sandbox di piccole dimensioni. Usa 8 GB di RAM e 40 GB di spazio su disco se vuoi mantenere attive più applicazioni contemporaneamente, perché ogni sandbox in esecuzione contiene una toolchain completa per Node o Python e ogni workspace conserva su disco il proprio albero delle dipendenze. Quando le risorse dell'host non sono sufficienti, il pressure reaper di sandboxd arresta i sandbox per liberare memoria. Una build che supera il limite di memoria del proprio container viene terminata dal kernel: docker ps -a ne mostra il codice di uscita 137.

Qual è la differenza tra sandboxd, Dify e OpenHands?

Producono artefatti diversi. Dify crea applicazioni che chiamano un modello durante l'esecuzione, ad esempio interfacce di chat e pipeline di retrieval. OpenHands modifica un repository già esistente, eseguendo comandi e proponendo modifiche al codice presente. sandboxd crea lo scheletro di un progetto completamente nuovo a partire da un prompt, lo compila nel proprio container e lo pubblica su un URL di anteprima. Il risultato è una normale applicazione web che non ha bisogno di un modello per funzionare.

Dove si trova effettivamente il codice scritto dall'agente?

Nel filesystem dell'host, non all'interno di un'immagine del container. In un'installazione v0.3.6 ogni applicazione riceve una directory in /var/lib/sandboxed/workspaces/<id>/ (/var/lib/sandboxd/workspaces/<id>/ in una nuova installazione di v0.3.9 o versioni successive), che viene montata nel relativo sandbox tramite bind mount. I file sono quindi disponibili in /home/sandbox/workspace/app all'interno del sandbox. Lo stato del control plane è contenuto in un unico file SQLite in state/, nella stessa directory dei dati. Dalla scheda Git della console puoi eseguire il commit e il push verso un nuovo branch su un repository git remoto. Puoi eseguire le stesse operazioni anche tramite gli endpoint /v1/apps/<id>/git/commit e /git/push. Un token per i repository remoti privati viene memorizzato dal control plane in forma cifrata, invece di essere passato al sandbox.

È sicuro esporre sandboxd su Internet?

Esponi gli URL di anteprima e la console, ma non l'API del control plane. Questa API controlla Docker sull'host, quindi equivale a root. Per questo motivo, per impostazione predefinita è in ascolto su 127.0.0.1:9090. Nel build self-hosted i sandbox hanno inoltre accesso alla rete in uscita senza restrizioni. Il codice scritto dall'agente può quindi raggiungere la rete locale e gli endpoint dei metadati cloud. Aggiungi regole al firewall dell'host se il server si trova su una rete con altri sistemi da proteggere. Per i prompt inviati da persone non affidabili, usa un host separato per ogni tenant invece di fare affidamento soltanto sul confine del container.