Come sandboxed abilita piattaforme AI multi-tenant con ambienti di sviluppo isolati

Cosa fa sandboxed

sandboxed è il motore open‑source che fornisce a ogni utente un ambiente sandboxed isolato – un container Linux privato con un proprio filesystem, limiti di memoria e hardening di sicurezza. Una richiesta HTTP crea il sandbox, esegue al suo interno un agente di codifica AI (OpenCode o Claude Code) ed espone un URL di anteprima live.

I sandbox entrano in stato di sleep quando sono inattivi, liberando memoria, ma i workspace persistono su disco. La richiesta successiva risveglia automaticamente il container e serve l'app. Questa densità consente a un singolo host di gestire molti tenant senza aver bisogno di VM sempre accese.

Il control plane è un singolo binario Go che comanda Docker tramite CLI, con Traefik per il routing e TLS, e SQLite per lo stato persistente – niente Kubernetes, database separato o coda di messaggi.

Usalo se stai costruendo un builder di app AI multi‑tenant, un playground di codifica o una piattaforma di anteprima per utente. Lascialo perdere se hai bisogno solo di uno o due container – uno script shell o docker run sono più semplici.

Installazione

Hai bisogno di un host Linux con Docker Engine e il plugin Compose. Lo script di installazione verifica Docker, compila l'immagine base del sandbox e il control plane, quindi avvia l'intero stack.

Clona il repository:
git clone https://github.com/tastyeffectco/sandboxes.git 2. Entra nella directory ed esegui l'installer:
cd sandboxes && ./install.sh 3. Verifica che l'API sia attiva:
curl http://127.0.0.1:9090/healthz → ok

Lo script scrive un file .env con i valori predefiniti. Al termine, l'API del control plane è pronta su http://127.0.0.1:9090.

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

# Verify
curl http://127.0.0.1:9090/healthz
# → ok

Workflow di base

1. Crea un sandbox – specifica le porte di cui ha bisogno la tua app (es. {"ports":[3000]}). L'API restituisce un ULID univoco.
2. Esegui un agente di codifica – invia una POST con un task, un prompt e un nome agente (opencode o claude). L'agente lavora in ~/workspace/app.
3. Segui il progresso in streaming – gli eventi Server‑Sent (SSE) ti permettono di osservare l'output dell'agente in tempo reale.
4. Apri l'anteprima – L'app è immediatamente raggiungibile all'indirizzo http://s-<id>-3000.preview.localhost. Per domini di produzione, HTTPS è disponibile dopo la configurazione TLS.

Puoi iniettare chiavi API al momento della creazione tramite il campo env (es. ANTHROPIC_API_KEY). Puoi anche eseguire direttamente qualsiasi comando con POST /sandbox/{id}/exec e ottenere un link di anteprima.

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

# Run a coding agent
curl -s -XPOST $API/v1/sandboxes/$ID/tasks -H 'content-type: application/json' \
  -d '{"prompt":"create a Vite app that shows a todo list and run it on port 3000","agent":"opencode"}'

# Stream events (replace <taskId>)
# curl -N $API/v1/sandboxes/$ID/tasks/<taskId>/events

# Preview URL: http://s-$ID-3000.preview.localhost

Panoramica API e configurazione

L'API è in esecuzione su http://127.0.0.1:9090. L'autenticazione è disabilitata per impostazione predefinita; abilitala in produzione con SANDBOXD_API_AUTH_DISABLED=false e definisci i token.

Endpoint principali:

• POST /sandbox – crea un nuovo sandbox
• POST /sandbox/{id}/exec – esegui un comando
• POST /v1/sandboxes/{id}/tasks – avvia un agente di codifica
• GET /v1/sandboxes/{id}/tasks/{taskId}/events – flusso di eventi SSE
• DELETE /sandbox/{id} – arresta / pulisci

Le impostazioni si trovano nel file .env (template .env.example). Variabili importanti:

• PREVIEW_DOMAIN – dominio per gli URL di anteprima
• HTTP_PORT – porta HTTP di Traefik
• SANDBOXED_DATA_DIR – directory di archiviazione dei workspace
• SANDBOXD_API_AUTH_DISABLED – abilita/disabilita l'autenticazione
• SANDBOXD_API_TOKENS – coppie nome:secret

Per il TLS di produzione, punta *.preview.yourdomain.com all'host, imposta PREVIEW_TLS=true e configura un certificato wildcard Let's Encrypt.

Vincoli e best practices

Limitazioni principali (qualità beta):

• Isolamento a livello di container, non VM – non è adatto per eseguire codice sconosciuto in sicurezza; aggiungi gVisor o Firecracker se necessario.
• Autenticazione API disabilitata di default – deve essere abilitata prima di esporre il sistema pubblicamente.
• I link di anteprima sono pubblici; non è presente un controllo di accesso integrato.
• Nessuna quota disco, egress aperto, solo host singolo, control plane con privilegi equivalenti a root.
• Il sistema è beta; potresti incontrare spigolature.

Best practices:

• Inizia con i valori predefiniti locali per lo sviluppo.
• Abilita l'autenticazione API prima di andare live – imposta token robusti.
• Per la produzione, configura TLS con un certificato wildcard Let's Encrypt.
• Inietta le chiavi API alla creazione del sandbox, non nell'immagine base.
• Mantieni l'host sicuro; il control plane ha accesso al socket Docker.
• Quando devi scalare, dai priorità a un isolamento più forte e a un piano multi‑nodo.
• Leggi il codice sorgente – il binario Go e SQLite sono volutamente piccoli.

Procedure degne di nota

• Disinstallazione: ./uninstall.sh arresta lo stack; aggiungere --images per rimuovere le immagini Docker, --data per eliminare tutte le aree di lavoro (con conferma) oppure --all per una pulizia completa.
  Vengono interessati solo gli oggetti gestiti.
• Sospensione per inattività / risveglio su richiesta: Dopo un periodo di inattività, i sandbox vengono arrestati ma le aree di lavoro persistono.
  La successiva richiesta di anteprima riavvia il contenitore in modo trasparente, mostra una pagina di riscaldamento e poi serve l’app.
• Riconciliazione all’avvio: All’avvio, il piano di controllo riconcilia lo stato SQLite con Docker, riavviando i sandbox desiderati e ripulendo gli orfani.
  Un riavvio dell’host non fa perdere definizioni o rotte.
• Esecuzione agenti: L’immagine del sandbox include le CLI OpenCode e Claude Code.
  Una richiesta POST di task esegue l’agente in modalità headless, trasmette l’output e cattura il risultato.
  Passare le chiavi API del provider tramite variabili d’ambiente al momento della creazione.