Docker Sandboxes: la guida pratica per eseguire agenti AI in isolamento con sbx

Cos'è Docker Sandboxes

Docker Sandboxes è una funzionalità che permette di eseguire agenti di coding AI, come Claude Code, Codex, Copilot, Cursor o Gemini, all'interno di microVM isolate. Ogni sandbox ottiene un proprio daemon Docker, un proprio filesystem e una propria rete: l'agente può quindi creare container, installare pacchetti e modificare file senza toccare il sistema host.

Lo strumento con cui si interagisce con questa funzionalità è la CLI sbx. Non è richiesta l'installazione di Docker Desktop per utilizzarla.

Prerequisiti

I requisiti variano in base al sistema operativo.

• macOS Sonoma (versione 14) o successiva, con chip Apple silicon
• Windows 11 a 64 bit (Intel o AMD), con Windows Hypervisor Platform abilitato
• Linux Ubuntu 24.04 o successivo a 64 bit, con virtualizzazione hardware KVM abilitata

Su Windows, per abilitare l'hypervisor è necessario eseguire questo comando da PowerShell come amministratore.

Enable-WindowsOptionalFeature -Online -FeatureName HypervisorPlatform -All

Su Linux è necessario verificare che KVM sia disponibile e aggiungere il proprio utente al gruppo kvm.

lsmod | grep kvm
sudo usermod -aG kvm $USER
newgrp kvm

Serve inoltre una chiave API o un metodo di autenticazione per il provider del modello che si intende usare (Anthropic, OpenAI, Google e altri).

Installazione e accesso

L'installazione della CLI cambia a seconda del sistema operativo.

macOS

brew install docker/tap/sbx
sbx login

Windows

winget install -h Docker.sbx
sbx login

Linux (Ubuntu)

curl -fsSL https://get.docker.com | sudo REPO_ONLY=1 sh
sudo apt-get install docker-sbx
sbx login

Il comando sbx login apre il browser per l'autenticazione OAuth con Docker. Al primo accesso viene chiesto di scegliere una policy di rete predefinita per le sandbox.

Balanced è un buon punto di partenza: consente il traffico verso i servizi di sviluppo più comuni bloccando il resto. Le singole regole possono essere modificate in seguito.

Autenticare l'agente

Ogni agente necessita di credenziali per il proprio provider di modelli. Per Claude Code con un abbonamento Claude (Max, Team o Enterprise) non serve alcuna configurazione preventiva: si usa il comando /login direttamente dentro la sandbox per autenticarsi via OAuth.

Per gli agenti che usano chiavi API, la chiave va salvata prima di avviare la sandbox.

sbx secret set -g anthropic

Il comando chiede il valore del secret e lo salva nel keychain del sistema operativo. Un proxy sull'host inietta la chiave nelle richieste in uscita, così non è mai esposta dentro la sandbox.

Per dare all'agente accesso a GitHub, ad esempio per creare pull request.

sbx secret set -g github -t "$(gh auth token)"

Avviare la prima sandbox

Ci si posiziona nella cartella del progetto e si avvia un agente con sbx run.

cd ~/my-project
sbx run --name my-sandbox claude

claude può essere sostituito con qualsiasi altro agente supportato (codex, copilot, cursor, droid, gemini, kiro, opencode, e altri). Il primo avvio richiede più tempo perché l'immagine dell'agente viene scaricata; gli avvii successivi riutilizzano la cache.

Per verificare le sandbox attive in qualsiasi momento.

sbx ls

Lanciando sbx senza argomenti si apre una dashboard interattiva da terminale, con lo stato delle sandbox, l'uso di CPU e memoria, e i controlli per la gestione della rete.

Gestione delle sandbox

Il flusso di lavoro base si basa su quattro comandi.

sbx run claude                    # avvia un agente
sbx ls                            # verifica cosa è in esecuzione
sbx stop my-sandbox               # mette in pausa
sbx rm my-sandbox                 # elimina definitivamente

Per ottenere una shell all'interno di una sandbox in esecuzione, utile per ispezionare l'ambiente o installare qualcosa manualmente.

sbx exec -it my-sandbox bash

Le sandbox persistono dopo l'uscita dell'agente: pacchetti installati, immagini Docker e configurazioni restano invariati tra un riavvio e l'altro. Eseguendo nuovamente il comando sullo stesso percorso di lavoro ci si riconnette alla sandbox esistente invece di crearne una nuova.

sbx run claude ~/my-project  # crea la sandbox
sbx run claude ~/my-project  # si riconnette alla stessa sandbox

Modalità diretta e clone mode

Quando la cartella di lavoro è un repository Git, ci sono due modi per condividerla con la sandbox.

In modalità diretta (predefinita), l'agente ha accesso in lettura e scrittura alla working tree e le modifiche appaiono immediatamente sull'host.

In clone mode, l'agente lavora su un clone Git privato dentro la microVM, mentre il repository host viene montato in sola lettura. La sandbox espone il proprio clone come remote Git sull'host, con nome sandbox-<nome-sandbox>.

sbx rm my-sandbox
sbx run --clone --name my-sandbox claude

Le modifiche dell'agente si recuperano come da un qualsiasi altro remote Git.

git fetch sandbox-my-sandbox
git log sandbox-my-sandbox/main
git diff main..sandbox-my-sandbox/main

Per creare una pull request a partire dal lavoro dell'agente.

git checkout -b my-feature sandbox-my-sandbox/main
git push -u origin my-feature
gh pr create

La clone mode è particolarmente utile quando si eseguono più agenti sullo stesso repository in parallelo, poiché ognuno lavora nel proprio clone isolato senza interferire con la working tree host.

Gestione della rete

La policy di rete stabilisce cosa la sandbox può raggiungere. Se un agente non riesce a connettersi a un servizio, è probabile che la policy lo blocchi.

Per verificare le regole attive.

sbx policy ls

Per consentire l'accesso a un host specifico.

sbx policy allow network registry.npmjs.org

Con la policy Locked Down, anche l'API del provider del modello è bloccata finché non viene autorizzata esplicitamente. Con Balanced, i servizi di sviluppo più comuni sono consentiti di default.

Esporre un servizio della sandbox

Le sandbox sono isolate a livello di rete: il browser o i tool locali sull'host non possono raggiungere un server in esecuzione al loro interno per impostazione predefinita. Si utilizza sbx ports per inoltrare il traffico dall'host verso la sandbox.

sbx ports my-sandbox --publish 8080:3000
open http://localhost:8080

Perché il servizio sia raggiungibile, deve essere in ascolto su tutte le interfacce dentro la sandbox (0.0.0.0 per IPv4), non solo su 127.0.0.1. La maggior parte dei dev server richiede un flag come --host 0.0.0.0 per questo comportamento.

Per interrompere l'inoltro di una porta.

sbx ports my-sandbox --unpublish 8080:3000

Raggiungere servizi dell'host dalla sandbox

I servizi in esecuzione sull'host sono raggiungibili dall'interno di una sandbox tramite l'hostname host.docker.internal, al posto di 127.0.0.1 o dell'indirizzo IP locale della macchina.

Poiché il proxy della sandbox traduce questo hostname in localhost, è necessario aggiungere l'indirizzo con la porta specifica alla policy di rete.

sbx policy allow network localhost:11434
curl http://host.docker.internal:11434

Copiare file tra host e sandbox

Per copiare file o cartelle che non fanno parte di una workspace montata, come output generati, log o file di setup, si usa sbx cp.

sbx cp ./config.json my-sandbox:/home/user/
sbx cp my-sandbox:/home/user/output.log ./
sbx cp ./src/ my-sandbox:/home/user/src

Workspace multiple

È possibile montare cartelle aggiuntive in una sandbox oltre alla workspace principale. Il primo percorso indicato è la workspace primaria, mentre le altre vengono montate direttamente. Aggiungendo :ro si monta una cartella in sola lettura.

sbx run claude ~/project-a ~/shared-libs:ro ~/docs:ro

Pulizia

Per interrompere una sandbox senza eliminarla.

sbx stop my-sandbox

Quando non serve più, la si rimuove per liberare spazio su disco.

sbx rm my-sandbox

La rimozione di una sandbox elimina tutto ciò che contiene: pacchetti installati, immagini Docker e, se si è usata la clone mode, il clone Git interno. I file sulla working tree dell'host non vengono toccati.

Conclusione

Docker Sandboxes offre un modo pratico per far lavorare gli agenti di coding AI in un ambiente isolato, senza rischi per il sistema host. Il flusso di base con sbx run, sbx ls, sbx stop e sbx rm copre la maggior parte dei casi d'uso quotidiani, mentre la clone mode e le policy di rete permettono di gestire scenari più complessi, come l'esecuzione parallela di più agenti sullo stesso repository.