Dev sandbox auto-ospitate: creare ambienti di preview con Docker e Go

Le URL di preview sembrano una funzionalità minima: avvii la porta 3000 dentro un container, dai un link all’utente, fatto. In pratica, una dev sandbox auto-ospitata tira dentro in fretta collisioni di porte, routing di domini, recycling dei container, persistenza dei file e orchestrazione guidata da API. I prodotti di coding con IA ci sbattono molto presto: dopo che l’agente ha scritto il codice, l’utente non vuole i log. Vuole cliccare sul risultato.

Un solo docker run non basta qui. Un design più stabile separa quattro pezzi: un host Linux, Docker per i container, un control plane Go per il ciclo di vita, Traefik per i domini di preview e SQLite per lo stato. Questo setup va bene per team fidati e validazione di prodotto early. Se intendi eseguire codice arbitrario di utenti sconosciuti, i container sono solo il primo strato. Dovresti pensare a microVM, host dedicati o Kubernetes.

Per molti ambienti effimeri, non per due container personali

Per un progetto personale, due container, due porte e docker compose up -d di solito bastano. Una dev sandbox inizia a guadagnarsi il posto quando il numero di ambienti cresce, il ciclo di vita si accorcia e un sistema esterno deve creare ogni ambiente in modo programmatico.

Molti sviluppatori chiederanno prima perché l’agente non possa semplicemente scrivere uno script shell. Domanda legittima. Uno script risolve «avviare un container». Non risolve «tenere vivi 50 ambienti, fermare quelli inattivi, risvegliarli alla richiesta successiva, conservare i file, dare a ogni ambiente una URL stabile e far pilotare tutto a un backend SaaS via API». Quando questi requisiti si accumulano, lo script inizia a diventare un control plane.

L’architettura più piccola: control plane Go, Docker, Traefik e SQLite

Il design di tastyeffectco/sandboxes è deliberatamente piccolo: un programma Go chiamato sandboxd invia comandi Docker, Traefik instrada dinamicamente tramite i label dei container, SQLite salva lo stato e i workspace vivono su disco. Niente Kubernetes, niente server di database separato, niente message queue.

browser
  |
  v
Traefik  ---->  sandbox container  ----> dev server :3000
  ^                    ^
  |                    |
sandboxd --------------+
  |
  +-- SQLite: stato delle sandbox, porte, task
  +-- workspaces/: una directory persistente per sandbox
  +-- reaper: idle stop / memory pressure stop

Vale la pena separare quattro oggetti.

Il control plane non è il container dell’applicazione

Il control plane Go dovrebbe gestire solo il ciclo di vita: creare una sandbox, fermarla, distruggerla, eseguire un comando, inviare un task di agente e leggere o scrivere file. Tienilo sottile. Non seppellirci tutta la logica di build. I comportamenti più complessi possono vivere nell’immagine base della sandbox, in una task queue o nel layer applicativo sopra.

Una URL di preview non è una porta casuale

Ogni sandbox può esporre un indirizzo come s-<id>-3000.preview.localhost. Traefik legge i label Docker, scopre il container e la porta target, poi inoltra le richieste tramite una Host rule. Gli utenti vedono un link stabile invece di «la tua porta è 30017; cerca di non collidere con qualcuno».

Railway - Piattaforma di deploy moderna, senza operazioni complesse, online in pochi minuti

Inizia ora →Pubbl.

SQLite è l’ancora di stato di un piccolo sistema

I container si riavviano. Gli host si riavviano. Traefik può ricaricare. SQLite registra ID delle sandbox, porte, stato, task e posizioni dei workspace. All’avvio del control plane può riconciliare lo stato reale di Docker con quel database. SQLite va bene per un prodotto early su singolo host, purché tu accetti il confine e faccia backup.

Farlo girare in locale: valida prima API, porte e risoluzione del dominio

Non correre a collegare un agente. Conferma prima che il control plane possa avviare container, che Traefik possa inoltrare e che la URL di preview si apra. Il quick start del README di sandboxes è diretto:

git clone https://github.com/tastyeffectco/sandboxes.git
cd sandboxes
./install.sh

API=http://127.0.0.1:9090
curl "$API/healthz"

Dopo che l’health check passa, crea una sandbox che serve sulla porta 3000:

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

curl -s -XPOST "$API/sandbox/$ID/exec" \
  -H 'content-type: application/json' \
  -d '{"cmd":["bash","-lc","cd ~/workspace && python3 -m http.server 3000"]}'

Poi apri:

http://s-<id>-3000.preview.localhost

*.localhost si risolve sulla tua macchina locale nei browser moderni, utile per test locali senza DNS. Per un dominio reale, punta *.preview.yourdomain.com all’host e lascia che Traefik gestisca TLS. Non esporre un’API locale come 127.0.0.1:9090 direttamente su internet pubblico. Come minimo, attiva l’autenticazione a token in produzione e tieni la porta del control plane dietro un firewall o un gateway privato.

Le URL di preview sono difficili per routing, risvegli e persistenza

Il port forwarding di base risponde solo a «come accedo al container mentre gira?». Una dev sandbox deve rispondere anche a «cosa succede quando il container dorme?», «dove vivono i file?» e «lo stesso utente può tornare più tardi?». Queste tre domande decidono se il sistema passa da demo a beta.

Routing: usare il dominio come identità dell’ambiente

Una porta è la prospettiva della macchina. Un dominio è la prospettiva del prodotto. s-<id>-3000.preview.example.com contiene l’ID della sandbox e la porta target, così l’applicazione può mostrare il link direttamente all’utente. Il provider Docker di Traefik legge i label del container e inoltra la Host rule al container giusto.

Fai il debug in quest’ordine:

• DNS: il dominio wildcard punta all’host, o usi *.localhost in locale?
• Traefik: il container ha i label giusti ed è sulla stessa rete Docker?
• Porta: l’app ascolta davvero su 0.0.0.0:3000, non solo su 127.0.0.1?
• Readiness: hai una pagina di attesa o una strategia di retry mentre l’app si avvia?
• TLS: il dominio reale usa un certificato wildcard, e gli entrypoint HTTP e HTTPS sono coerenti?

Risveglio: l’idle stop non è l’eliminazione dell’ambiente

Una sandbox inattiva può essere fermata con docker stop, liberando memoria ma mantenendo il workspace su disco. La prossima volta che un utente apre la URL di preview, una route catch-all a bassa priorità può inviare la richiesta al control plane. Il control plane avvia il container, aspetta che la porta sia pronta e poi lascia entrare il browser nell’app reale.

Questo meccanismo usa meno risorse di «tenere tutto acceso per sempre» e sembra più da prodotto di «eliminare l’ambiente quando si zittisce». Il compromesso è la latenza di cold start, quindi la pagina dovrebbe mostrare uno stato di warming invece di lasciare l’utente a fissare un 502.

Persistenza: i bind mount sono utili, ma conosci il confine

La documentazione di Docker tratta i bind mount come comuni per condividere codice sorgente e artefatti di build. Una dev sandbox fa spesso lo stesso: una directory host per sandbox, montata nel workspace del container. Il vantaggio: il codice sopravvive all’eliminazione del container. Lo svantaggio: i percorsi host e i permessi diventano parte del design del sistema.

Vultr - Cloud server NVMe ad alte prestazioni, 32 location globali, deploy Docker con un clic

Vedi prezzi →Pubbl.

Prima di una beta, fissa almeno tre regole: tieni le directory di workspace separate dalla configurazione del control plane; rendi «eliminare il container» ed «eliminare il workspace» due operazioni distinte; fai il backup di workspace e SQLite, non solo dei layer dei container.

Basi multi-tenant: limiti di risorse, Docker socket, auth dell’API e cache delle immagini

La documentazione di Docker sui limiti di risorse è schietta: i container non hanno vincoli di risorse per impostazione predefinita e possono usare CPU e memoria quanto lo scheduler del kernel host consente. In un setup multi-tenant è un rischio. Il npm install, il build o il loop infinito di un utente può rallentare l’intera macchina.

Parti da questa checklist:

• Imposta limiti di memoria, CPU e PID per ogni sandbox.
• Tieni l’API del control plane su localhost o una rete privata per impostazione predefinita; richiedi autenticazione per qualsiasi entrypoint pubblico.
• Tratta i link di preview come condivisibili per impostazione predefinita. Aggiungi forward-auth quando contengono contenuti sensibili.
• Preinstalla gli strumenti comuni nell’immagine base così che ogni sandbox non debba riscaricare tutto.
• Docker Hub ha rate limit ufficiali e regole di fair use. In produzione accedi, prepara una cache di immagini o usa un registry privato.
• Monta i workspace delle sandbox separatamente e non dare mai /var/run/docker.sock ai container utente.
• Registra creazione, arresto, distruzione, esecuzione di comandi e task di agente.

Un esempio di limiti di risorse in Compose può apparire così:

services:
  sandbox-app:
    image: your-sandbox-base:latest
    deploy:
      resources:
        limits:
          cpus: "1.00"
          memory: 1G
          pids: 256

Il tema di sicurezza più grande è il Docker socket. Se sandboxd monta il Docker socket dell’host, ha alta autorità sull’host. Può essere accettabile quando mantieni tu il control plane e gli utenti entrano solo nei container di sandbox che crea. Se gli utenti possono influenzare il container del control plane o ottenere il Docker socket, il rischio supera il normale isolamento dei container.

Quando passare a microVM, Kubernetes o una piattaforma gestita

Il vantaggio di Docker su singolo host è costo, leggibilità e velocità di modifica. Lo svantaggio è altrettanto chiaro: un host ha capacità limitata, il confine di sicurezza dipende molto dall’isolamento dei container e dalla governance dell’host, e lo scheduling è più debole di un cluster.

Il modello di sicurezza ufficiale di Docker Sandboxes è un punto di riferimento utile: mette l’agente IA dentro una microVM, dà a ogni sandbox il proprio daemon Docker, filesystem e rete, e tiene il daemon Docker host lontano dalla sandbox. Costa più risorse, ma il confine di isolamento è più chiaro.

Parti quindi da un setup su singolo host per imparare il loop di prodotto: creare un ambiente, far scrivere codice all’agente, aprire la preview, riciclare le sandbox inattive e conservare i file. Quando arrivano utenti reali, alza il livello di isolamento secondo il rischio effettivo. Non il contrario: non trascinare il team nella manutenzione del cluster prima che il problema di scala esista.

Una checklist pratica dall’MVP alla beta

Puoi procedere in quest’ordine senza costruire tutto in una volta:

1. Scegli un host Linux pulito che esegua solo servizi legati alla sandbox. Non collocarci database, CI runner o applicazioni di produzione.
2. Configura un dominio di preview wildcard come *.preview.example.com. Valida prima in locale con *.localhost.
3. Valida l’API del control plane: create, exec, stop, destroy e healthz.
4. Preinstalla Node.js, Python, Git, i package manager comuni e le CLI di agente che supporti nell’immagine base della sandbox.
5. Aggiungi limiti di risorse, recycling degli inattivi, persistenza del workspace e policy di distruzione per ogni sandbox.
6. Abilita l’autenticazione dell’API e aggiungi il controllo degli accessi ai link di preview quando il business lo richiede.
7. Registra eventi di audit. Monitora memoria dell’host, disco, numero di container, tempo di cold start e tasso di 502.
8. Prova backup e ripristino per SQLite, le directory di workspace, .env e gli script di build dell’immagine base.

Se il tuo prossimo passo è collegare le preview del codice alla CI, leggi GitHub Actions Self-Hosted Runner: la guida completa al deployment in ambiente privato. Se vuoi ospitare a lungo termine l’app Next.js generata, Lasciare Vercel: la guida completa al self-hosting di Next.js con Docker è più vicina alla seconda metà del percorso. Per domini pubblici e protezione dell’origine, continua con l’allowlisting dell’IP di origine di Cloudflare.

🔥 Non sprecare mesi su prodotti senza domanda! Valida i punti di forza del tuo SaaS con Adsterra e un piccolo budget ➡️

Testa ora →Pubbl.

FAQ

In cosa differisce una Dev Sandbox da Docker Compose?

Compose è più vicino a «dichiaro un gruppo di servizi, poi li avvio». Una Dev Sandbox è più vicina a «il backend del prodotto crea, ferma, risveglia e distrugge ambienti su richiesta, e ogni ambiente ottiene una URL». Se gli ambienti sono pochi e duraturi, Compose basta. Se sono dinamici per utente, branch o task di agente, serve un control plane.

Perché non usare Kubernetes?

Se hai già cluster, ingress, registry di immagini, permessi e monitoraggio, Kubernetes è una base solida per ambienti standardizzati. Il problema è che molti team early vogliono solo validare un AI app builder o un ambiente di preview interno, e mantenere il cluster può diventare più pesante del prodotto stesso. Docker su singolo host non sostituisce Kubernetes; tiene leggera la prima fase.

L’isolamento dei container può eseguire codice di utenti sconosciuti?

Non lo farei direttamente. I container vanno bene per team fidati, utenti interni o demo a basso rischio. Il codice arbitrario di utenti sconosciuti dovrebbe girare in un isolamento più forte: microVM, VM dedicate, gVisor, Kata, Firecracker, o almeno host separati per tenant.

Ogni URL di preview ha bisogno di HTTPS?

I preview locali *.localhost possono partire in HTTP. Per un dominio pubblico reale usa HTTPS, soprattutto quando gli utenti inseriscono token, form o dati di business. Un certificato wildcard riduce la fatica di emettere un certificato separato per ogni sandbox.

I file spariscono dopo un idle stop?

Finché il workspace è una directory persistente, docker stop non cancella i file. La parte delicata è la differenza tra destroy e purge: una rimuove solo il container, l’altra anche il workspace. Rendi chiara questa distinzione nell’UI del prodotto e nei nomi dell’API.

I rate limit di Docker Hub possono influenzare questo sistema?

Sì. Quando molti ambienti avviano, buildano e scaricano immagini di frequente, il registry pubblico può diventare una dipendenza instabile. In produzione accedi a Docker Hub, prepara un registry privato o una cache di immagini e integra le dipendenze comuni nell’immagine base.

Conclusione

Una dev sandbox auto-ospitata vale la pena, ma non è solo un docker run avanzato. È una piccola piattaforma: il control plane possiede il ciclo di vita, il reverse proxy possiede le URL, lo state store possiede il ripristino, e i limiti di risorse più la policy di sicurezza impediscono a un ambiente di mettere in ginocchio l’host.

Il percorso stabile è costruire prima il loop di prodotto con Docker su singolo host, poi alzare il livello secondo il rischio reale. Quando gli utenti sono pochi, il codice è fidato e il team accetta un confine su singolo host, Go + Docker + Traefik + SQLite basta. Quando entrano utenti sconosciuti, isolamento più forte, scheduling multi-host o governance di conformità, metti microVM, Kubernetes o una piattaforma gestita sul tavolo.

Risorse

• tastyeffectco/sandboxes
• Docker Resource constraints
• Docker Engine security
• Docker Hub usage and limits
• Docker Sandboxes security model
• Traefik Docker provider