Scegliere un ambiente sandbox

Confronta le opzioni di sandbox di Claude Code: lo strumento Bash sandboxed integrato, il runtime sandbox, i dev container, Docker e le VM. Scegli l'isolamento giusto per il tuo modello di minaccia.

L'isolamento di Claude Code limita ciò che una sessione può leggere, scrivere e raggiungere sulla rete. Questo è particolarmente importante quando consenti a Claude di lavorare con meno prompt di autorizzazione, lo esegui in modo automatico o lo punti verso codice di cui non sei completamente sicuro.

Claude Code può essere eseguito in diversi tipi di ambienti isolati, che vanno da una sandbox leggera per comando a una macchina virtuale completamente separata. Questa pagina confronta gli ambienti in base a ciò che isolano e a cosa richiedono, ti aiuta a sceglierne uno per il tuo modello di minaccia e mostra come applicare tale scelta in tutta l'organizzazione.

Confrontare gli approcci di sandboxing

I primi due approcci nella tabella sottostante vengono eseguiti sul sistema operativo host senza container. Gli altri posizionano Claude Code all'interno di un container o di una macchina virtuale.

Lo sandboxed Bash tool è integrato in Claude Code e limita i comandi Bash. I file tools integrati, i server MCP e gli hooks vengono comunque eseguiti direttamente sul tuo host. Ogni altro approccio nella tabella posiziona l'intero processo Claude Code all'interno del confine di isolamento, quindi i file tools, i server MCP e gli hooks sono anch'essi limitati.

Scegliere un approccio

Abbina il tuo obiettivo a una riga sottostante, quindi leggi la sezione di dettaglio che segue.

Come l'isolamento si relaziona alle modalità di autorizzazione

Le modalità di autorizzazione decidono se una chiamata di strumento viene eseguita e se sei richiesto per primo. L'isolamento limita ciò che un comando può accedere una volta eseguito. I due lavorano insieme: quando una modalità di autorizzazione consente l'esecuzione di azioni senza chiederti, un confine di isolamento limita ciò che quelle azioni possono raggiungere.

Quando passi --dangerously-skip-permissions, Claude agisce senza chiederti per primo. Le azioni che nessuna modalità auto-approva si applicano ancora.

Senza prompt per catturare gli errori, il confine di isolamento che scegli è ciò che protegge il tuo sistema. Esegui sempre le sessioni --dangerously-skip-permissions all'interno di un container, una VM, o il sandbox runtime, in modo che i file tools, i server MCP e gli hooks siano anch'essi all'interno del confine. Su Linux e macOS, Claude Code rifiuta di avviarsi con questo flag quando viene eseguito come root, quindi esegui il container, la VM, o il sandbox runtime come utente non-root.

La modalità auto sostituisce il prompt con un classificatore che esamina le azioni. Il classificatore è un controllo per azione, non un confine di isolamento, quindi un confine di isolamento aggiunge comunque difesa in profondità per esecuzioni automatiche, e non è richiesto come lo è per --dangerously-skip-permissions.

Lo sandboxed Bash tool da solo vincola solo Bash, quindi non è sufficiente per esecuzioni completamente automatiche in nessuna delle due modalità. Puoi stratificare gli approcci: eseguire lo sandboxed Bash tool all'interno di un container o VM ti dà restrizioni di comando a livello di SO in cima al confine dell'ambiente esterno. Per come la sandbox Bash stessa interagisce con le regole di autorizzazione e le modalità di autorizzazione, vedi Come il sandboxing si relaziona alle autorizzazioni e alle modalità di autorizzazione.

Sandboxed Bash tool

Lo sandboxed Bash tool è integrato in Claude Code. Utilizza primitive del sistema operativo per limitare l'accesso al filesystem e alla rete di ogni comando Bash che Claude esegue.

Esegui il comando /sandbox per aprire il pannello sandbox e scegliere una modalità. La guida Sandboxing copre le modalità di approvazione, il confine predefinito, e come ampliarlo o restringerlo.

La sandbox per comando non copre tutto ciò che viene eseguito in una sessione:

• Altri strumenti integrati come Read, Edit e WebFetch vengono eseguiti all'interno del processo Claude Code e non generano codice arbitrario. Le regole di autorizzazione per percorso o dominio le controllano invece.
• I server MCP e gli hooks di comando sono processi separati che vengono eseguiti senza vincoli sull'host.

Per mettere i file tools, i server MCP e gli hooks tutti dietro un confine di SO, esegui l'intero processo Claude Code all'interno del sandbox runtime, del dev container, o di un custom container.

Sandbox runtime

Il pacchetto @anthropic-ai/sandbox-runtime avvolge un intero processo nello stesso isolamento Seatbelt o bubblewrap che la sandbox Bash integrata utilizza. Eseguire Claude Code attraverso il runtime vincola ogni strumento, hook e server MCP nella sessione, non solo Bash. Il runtime è un'anteprima di ricerca beta, e il suo formato di configurazione potrebbe cambiare man mano che il pacchetto evolve.

Questa sezione copre ciò che configuri e ciò che il runtime applica da solo. Per distribuire il runtime nelle applicazioni Agent SDK, consulta la guida alla distribuzione sicura.

Set up and launch the runtime

Su Linux e WSL2, il runtime si basa sugli stessi pacchetti bubblewrap e socat della sandbox integrata, più ripgrep, che Claude Code raggruppa ma il runtime autonomo risolve dal tuo PATH. Installa bubblewrap e socat come descritto in Set up Linux and WSL2, e ripgrep dal gestore di pacchetti della tua distribuzione. Su macOS non hai bisogno di pacchetti aggiuntivi. Il runtime utilizza la sandbox Seatbelt integrata lì.

Per impostazione predefinita il runtime nega l'accesso di rete e limita le scritture a un piccolo insieme di percorsi runtime integrati, quindi configuralo prima di lanciare Claude Code attraverso di esso. Metti la tua configurazione in ~/.srt-settings.json, o in un file che passi con --settings. Il README del pacchetto documenta lo schema di configurazione completo.

Consenti l'accesso in scrittura ad almeno:

• La tua directory di progetto.
• I percorsi di configurazione di Claude Code ~/.claude e ~/.claude.json.
• /tmp, dove Claude Code scrive i file runtime.

Consenti i domini di rete di cui la tua sessione ha bisogno:

• api.anthropic.com, o l'endpoint del tuo provider configurato. Su un provider di terze parti, mantieni anche api.anthropic.com: il controllo di sicurezza del dominio WebFetch lo chiama comunque per impostazione predefinita a meno che tu non imposti skipWebFetchPreflight: true.
• claude.ai e platform.claude.com, che OAuth sign-in e token refresh richiedono. Le esecuzioni autenticate con una chiave API possono eliminare questi due.

Su Linux e WSL2, il runtime applica i permessi di scrittura solo ai percorsi che già esistono. In un ambiente nuovo, crea i percorsi di configurazione di Claude Code prima del primo avvio:

mkdir -p ~/.claude && echo '{}' > ~/.claude.json

Una volta che il file di impostazioni è in posizione, avvia Claude Code con npx e passa claude come comando da avvolgere:

npx @anthropic-ai/sandbox-runtime claude

Claude Code si avvia all'interno della sandbox con i confini di filesystem e di rete che hai configurato. Lo stesso comando funziona per il sandboxing di server MCP autonomi o altri processi di supporto.

What the runtime blocks on its own

Il runtime blocca le scritture a rischio più elevato senza alcuna configurazione da parte tua:

• denyWrite ha la precedenza su allowWrite.
• Alla radice del progetto, il runtime nega .git/hooks, nega .git/config a meno che tu non imposti filesystem.allowGitConfig: true, e nega .mcp.json, .claude/commands, .claude/agents, e i file di avvio della shell.
• Su macOS, questi dinieghi vengono controllati quando avviene una scrittura, quindi coprono anche i file annidati e i repository creati durante la sessione.
• Su Linux e WSL2, il runtime costruisce l'elenco di diniego una volta all'avvio. Copre in modo affidabile la radice del progetto, esegue una scansione superficiale nel migliore dei casi per le copie annidate che esistono in quel momento, e non copre nulla che la sessione crea in seguito, come git init, git clone, o scaffolding. La sezione mandatoryDenySearchDepth del README descrive la semantica esatta della scansione.
• Senza un ~/.srt-settings.json valido, il runtime si avvia comunque, blocca l'accesso di rete, e limita le scritture ai percorsi runtime integrati come /tmp/claude, ~/.npm/_logs, e ~/.claude/debug. Non prendere un avvio pulito come prova che le tue impostazioni sono state caricate.
• Quando passi --settings, il runtime rifiuta di avviarsi se il file non riesce a caricarsi.

I tuoi permessi di scrittura includono ancora altri percorsi da cui Claude Code carica la configurazione, quindi nega quelli con denyWrite. Una sessione in sandbox che può scriverli può persistere hook, regole di permesso, o server MCP che vengono eseguiti senza sandbox la prossima volta che avvii Claude Code.

After unattended runs

Rivedi i percorsi che hai mantenuto scrivibili. Su Linux e WSL2, rivedi anche tutto ciò che la sessione ha creato.

Dev containers

Un dev container esegue Claude Code all'interno di un container Docker che VS Code o un editor compatibile gestisce, con il tuo progetto montato. Puoi definire il tuo con una directory .devcontainer/ nel tuo repository.

Il repository claude-code pubblica un esempio di dev container con un firewall iptables default-deny come punto di partenza. Copialo nel tuo repository e regola la whitelist del firewall, l'immagine di base e la versione di Claude Code fissata per adattarsi al tuo ambiente. Poiché il firewall blocca l'uscita non approvata, una configurazione come questa supporta l'esecuzione di Claude Code con --dangerously-skip-permissions per il lavoro automatico.

Custom container

Puoi eseguire Claude Code in qualsiasi immagine container Docker o OCI con le tue politiche di rete, volumi montati e profili seccomp. Questo è il percorso più comune per le organizzazioni con infrastruttura container esistente o runner CI.

Diversi servizi di sandbox gestiti e di esecuzione remota possono ospitare il container per te. La stessa checklist si applica come per qualsiasi container che gestisci: rivedi cosa è montato in scrittura, quali credenziali e token sono raggiungibili all'interno, e cosa consente la politica di uscita di rete.

Puoi stratificare la sandbox Bash integrata all'interno del container per restrizioni per comando. I container senza privilegi hanno bisogno dell'impostazione nested-sandbox descritta in Sandboxing troubleshooting.

Virtual machine

Una macchina virtuale dedicata fornisce la separazione più forte, con il suo kernel e, nei deployment cloud o microVM, il suo hardware virtualizzato. Le opzioni includono istanze cloud, hypervisor locali e microVM come Firecracker. Usa questo approccio quando stai valutando codice non attendibile, quando la tua politica di sicurezza richiede separazione a livello di kernel tra l'agente e l'host, o quando nessun approccio a livello di host soddisfa i tuoi requisiti di conformità.

Docker Sandboxes fornisce una microVM con il suo daemon Docker e sincronizzazione dell'area di lavoro, che può eseguire Claude Code su qualsiasi host con Docker Sandboxes installato. È un prodotto gratuito e autonomo di Docker che non richiede Docker Desktop.

Claude Code on the web

Claude Code on the web esegue ogni sessione in una macchina virtuale isolata gestita da Anthropic. Un proxy di rete applica una whitelist predefinita, e un proxy separato tiene il tuo token GitHub al di fuori della sandbox mentre emette credenziali scoped per l'accesso al repository all'interno di essa. Le sessioni che la vostra organizzazione instrada a un ambiente self-hosted vengono eseguite su infrastruttura che voi stessi provisionate, dove l'isolamento, il controllo dell'egress e le credenziali git sono responsabilità della vostra distribuzione.

Utilizzate questo approccio quando desiderate l'isolamento completo della VM senza provisioning dell'infrastruttura da soli, o quando state delegando attività da un dispositivo che non dispone di un ambiente di sviluppo locale. Richiede un abbonamento Claude. Quando avviate una sessione dall'interfaccia web, avete anche bisogno di un account GitHub connesso affinché la sandbox possa clonare il vostro repository. Quando avviate dalla CLI con --cloud, Claude Code può raggruppare e caricare il vostro repository locale invece. Consultate Claude Code on the web per la disponibilità del piano e le opzioni di autenticazione GitHub.

Applicare l'isolamento in un'organizzazione

I singoli sviluppatori possono optare per qualsiasi approccio di sandboxing su questa pagina. Ciò che un'organizzazione può applicare, e con quali strumenti, dipende dall'approccio:

• Built-in Bash sandbox: l'unico approccio che Claude Code applica da solo. Fornisci le chiavi di impostazioni sandbox attraverso managed settings, sia come file gestito dal tuo MDM che attraverso server-managed settings su Claude.ai. Vedi Enforce sandboxing with managed settings per le chiavi da distribuire e come impedire agli sviluppatori di ampliare la politica.
• Dev containers: esegui il commit dell'esempio di dev container nei tuoi repository per standardizzare l'ambiente in un team. Questa è una convenzione piuttosto che un confine di applicazione, perché Claude Code non richiede un container. Se gli sviluppatori non dovrebbero essere in grado di eseguire Claude Code al di fuori di esso, applica ciò con gli strumenti di gestione dei dispositivi della tua organizzazione o di allowlisting del software.
• Custom containers e VMs: distribuisci Claude Code attraverso l'immagine approvata e usa gli strumenti di gestione dei dispositivi della tua organizzazione o di allowlisting del software per prevenire l'installazione al di fuori di essa.

Vedi anche

Queste pagine coprono i dettagli di configurazione e politica per gli approcci di sandboxing su questa pagina.

• Sandboxing: configura lo sandboxed Bash tool integrato
• Dev container: il container di sviluppo Docker preconfigurato
• Security: il modello di sicurezza completo di Claude Code
• Secure deployment: guida all'isolamento per le applicazioni Agent SDK
• Settings: tutte le chiavi di configurazione sandbox, inclusa la consegna di managed settings