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 o Gemini CLI, 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.

Agent supportati

Docker Sandboxes esegue nativamente questi agent. Il comando indicato crea ed avvia una sandbox nella cartella corrente con l'agent scelto.

shell è un caso speciale: avvia una sandbox senza alcun agent preinstallato, utile per esplorazione manuale, test o per installare un agent non presente in questa lista, come descritto più avanti nell'articolo.

Autenticare l'agente

Ogni agent 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 agent 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'agent 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 agent con sbx run.

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

Il primo avvio richiede più tempo perché l'immagine dell'agent 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

Una sandbox è una VM persistente: continua a esistere anche dopo che l'agent si è fermato o che il terminale è stato chiuso, finché non viene rimossa esplicitamente. Questa sezione riassume tutte le operazioni comuni.

Entrare nella console bash della VM

Per ottenere una shell bash reale dentro una sandbox, indipendentemente dall'agent con cui è stata creata.

sbx exec -it my-sandbox bash

Questo comando funziona anche se la sandbox è stata creata con shell e non ha alcun agent installato.

Entrare nell'agent a partire dalla console bash

Una volta dentro la shell bash della sandbox, si lancia l'agent semplicemente digitando il nome del suo comando.

claude
codex
opencode

Sostituire con il comando corrispondente all'agent installato in quella sandbox (vedi la tabella degli agent supportati).

Uscire dall'agent e tornare alla console bash

Dentro l'interfaccia interattiva dell'agent, premere Ctrl+C due volte, oppure usare il comando di uscita specifico dell'agent (ad esempio /exit per Claude Code). Si torna così al prompt bash della sandbox, senza fermare la sandbox stessa.

Rientrare nella sandbox se il terminale è stato chiuso

Se la finestra del terminale viene chiusa, la sandbox continua a girare in background: non viene fermata né cancellata. Per rientrare ci sono due strade.

Rientrare direttamente nell'agent con cui la sandbox era stata avviata.

sbx run --name my-sandbox

Oppure entrare nella shell bash e lanciare l'agent manualmente da lì.

sbx exec -it my-sandbox bash
claude

Per verificare prima quali sandbox esistono e il loro stato (in esecuzione o fermate).

sbx ls

Fermare e riavviare una sandbox

Per fermare una sandbox senza eliminarla, liberando le risorse della VM.

sbx stop my-sandbox

Non esiste un comando start separato: per riavviarla si usa di nuovo sbx run puntando allo stesso nome. Tutto ciò che è stato installato o configurato in precedenza viene mantenuto, comprese le variabili scritte in /etc/sandbox-persistent.sh.

sbx run --name my-sandbox claude

Eliminare una sandbox

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

sbx rm my-sandbox

La rimozione elimina tutto ciò che la sandbox contiene: pacchetti installati, immagini Docker interne e variabili configurate. A quel punto va ricreata da zero. I file sulla working tree dell'host non vengono toccati.

Gestione specifica: Claude Code

Creazione ed avvio.

sbx run --name claude-1 claude

Entrare nella console bash e poi avviare Claude Code manualmente.

sbx exec -it claude-1 bash
claude

Uscire dall'interfaccia di Claude Code: Ctrl+C due volte, oppure /exit.

Rientrare dopo aver chiuso il terminale.

sbx run --name claude-1

Gestione specifica: Codex

Creazione ed avvio.

sbx run --name codex-1 codex

Entrare nella console bash e poi avviare Codex manualmente.

sbx exec -it codex-1 bash
codex

Uscire dall'interfaccia di Codex: Ctrl+C due volte, oppure /quit.

Rientrare dopo aver chiuso il terminale.

sbx run --name codex-1

Gestione specifica: OpenCode

Creazione ed avvio.

sbx run --name opencode-1 opencode

Entrare nella console bash e poi avviare OpenCode manualmente.

sbx exec -it opencode-1 bash
opencode

Uscire dall'interfaccia di OpenCode: Ctrl+C due volte, oppure /exit.

Rientrare dopo aver chiuso il terminale.

sbx run --name opencode-1

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'agent ha accesso in lettura e scrittura alla working tree e le modifiche appaiono immediatamente sull'host.

In clone mode, l'agent 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'agent 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'agent.

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ù agent 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 agent 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

Installare un agent non supportato (esempio: Pi Coding Agent)

Non tutti gli agent sono presenti nella lista nativa. Un esempio è Pi Coding Agent, un agent da terminale open source disponibile su pi.dev. Ci sono due modi per farlo girare in una sandbox.

Metodo rapido: installazione manuale in una sandbox shell

shell avvia una sandbox pulita senza alcun agent preinstallato: da lì si installa Pi manualmente.

sbx run shell --name pi-sandbox

Dentro la sandbox.

curl -fsSL https://pi.dev/install.sh | sh
pi

Se lo script di installazione o Pi vengono bloccati dalla policy di rete, va consentito il dominio necessario.

sbx policy allow network pi.dev

Il limite di questo approccio è che ogni volta che la sandbox viene ricreata, Pi va reinstallato da zero.

Metodo persistente: un kit custom

Per non reinstallare l'agent a ogni avvio, si può definire un kit: un file di specifica dichiarativo che estende un template esistente (in questo caso shell) con passi di installazione eseguiti alla creazione della sandbox.

schemaVersion: "1"
kind: sandbox
name: pi-sandbox
sandbox:
  image: "docker/sandbox-templates:shell-docker"
entrypoint:
  run: ["pi"]
commands:
  install:
    - command: "curl -fsSL https://pi.dev/install.sh -o /tmp/pi-install.sh && sh /tmp/pi-install.sh"

Si scarica prima lo script e poi lo si esegue, invece di usare curl | sh direttamente: se il download viene bloccato dalla rete, in questo modo il passaggio di installazione fallisce visibilmente invece di segnalare un falso successo.

Si avvia la sandbox indicando il kit con --kit.

sbx run pi-sandbox --kit ./pi-sandbox/

Questo dà una sandbox riutilizzabile con Pi già pronto a ogni creazione, senza reinstallarlo manualmente.

Preinstallare strumenti di sviluppo (PHP, Composer, ecc.)

Lo stesso meccanismo dei kit permette di preinstallare qualsiasi programma di cui l'agent avrà bisogno per eseguire comandi, come PHP e Composer, così da non doverli installare al volo durante la sessione di lavoro.

schemaVersion: "1"
kind: sandbox
name: php-agent
sandbox:
  image: "docker/sandbox-templates:claude-code-docker"
commands:
  install:
    - command: "apt-get update && apt-get install -y php-cli php-mbstring php-xml unzip"
      user: "root"
    - command: "curl -fsSL https://getcomposer.org/installer -o /tmp/composer-setup.php && php /tmp/composer-setup.php --install-dir=/usr/local/bin --filename=composer"
      user: "root"

Alcuni domini usati dagli installer, come getcomposer.org o i repository archive.ubuntu.com e security.ubuntu.com per apt-get, potrebbero non essere già consentiti dalla policy di rete e vanno aggiunti esplicitamente.

sbx policy allow network getcomposer.org
sbx policy allow network archive.ubuntu.com
sbx policy allow network security.ubuntu.com

Si avvia poi la sandbox con il kit, usando come base l'agent che si preferisce, ad esempio Claude Code.

sbx run php-agent --kit ./php-agent/ claude

Da quel momento l'agent trova php e composer già disponibili nel PATH, senza doverli installare durante la sessione.

Usare Claude Code con un provider API alternativo

Claude Code non richiede necessariamente un account Claude: può essere puntato verso qualsiasi endpoint compatibile con il formato dell'API Anthropic, come un gateway o un provider terzo (ad esempio un endpoint del tipo https://api.synterolink.com). In questo caso non si usa sbx secret set anthropic, perché quel meccanismo inietta una chiave reale solo nelle richieste dirette verso api.anthropic.com: un endpoint diverso va configurato come variabile d'ambiente personalizzata.

Passo 1 — creare la sandbox senza avviare subito l'agent

cd ~/my-project
sbx create claude --name my-sandbox .

Passo 2 — scrivere le variabili nel file persistente

Le variabili non legate a un servizio supportato da sbx secret vanno scritte in /etc/sandbox-persistent.sh dentro la sandbox: questo file viene letto a ogni avvio di shell o di agent, quindi le variabili restano valide per tutta la vita della sandbox. Il modo più affidabile è entrare prima nella shell della sandbox ed editare il file da lì, evitando problemi di escaping delle virgolette tipici quando si passano comandi complessi da un terminale Windows.

sbx exec -it my-sandbox bash

Dentro la sandbox.

cat > /etc/sandbox-persistent.sh << 'EOF'
export ANTHROPIC_BASE_URL=https://api.synterolink.com
export ANTHROPIC_AUTH_TOKEN=il-tuo-token
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
export CLAUDE_CODE_ATTRIBUTION_HEADER=0
EOF
source /etc/sandbox-persistent.sh

I valori non vanno racchiusi tra virgolette, dato che URL e token non contengono spazi: aggiungerle farebbe sì che le virgolette diventino parte del valore della variabile, causando poi errori di autenticazione.

Passo 3 — consentire l'accesso di rete al dominio del provider

Con la policy predefinita (Balanced), i domini sconosciuti sono bloccati, quindi il traffico verso il provider custom andrebbe consentito esplicitamente.

sbx policy allow network api.synterolink.com

Passo 4 — avviare la sandbox

sbx run --name my-sandbox

Risoluzione problemi comuni

Se Claude Code continua a chiedere /login anche con le variabili impostate, verificare quanto segue.

• Le variabili sono state effettivamente lette: echo $ANTHROPIC_BASE_URL dentro la sandbox non deve restituire valori con virgolette incluse.
• Non è presente una variabile ANTHROPIC_API_KEY in conflitto: se impostata insieme a ANTHROPIC_AUTH_TOKEN, può avere la precedenza a seconda della versione del client.
• Non esistono credenziali OAuth salvate in precedenza che il client prova a usare per prime, ad esempio un file di credenziali residuo da un login effettuato in passato con un vero account Claude.

Conclusione

Docker Sandboxes offre un modo pratico per far lavorare gli agent 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 kit personalizzati, clone mode, policy di rete e provider API alternativi permettono di adattare l'ambiente a scenari più specifici, dall'uso di agent non ufficialmente supportati fino a configurazioni aziendali con endpoint dedicati.