Configurare lo strumento Bash in sandbox

Limita i file e gli host di rete che i comandi shell di Claude Code possono raggiungere con la sandbox integrata. Attivala, imposta il perimetro e risolvi ciò che interrompe.

La sandbox di Bash è un perimetro che il sistema operativo applica attorno ai comandi shell che Claude esegue sulla tua macchina. Sei tu a stabilire quali file e domini di rete quei comandi possono raggiungere, e i limiti si applicano ai comandi Bash, PowerShell e Monitor e ai processi che avviano. Poiché è il sistema operativo ad applicare i limiti mentre un comando è in esecuzione, Claude Code può eseguire i comandi in sandbox senza chiederti di approvarli uno per uno.

La sandbox copre solo i comandi shell. Gli strumenti per i file di Claude, i server MCP e gli hook vengono eseguiti al di fuori di essa.

La sandbox funziona su macOS, Linux e WSL2. Su Windows nativo, Claude Code esegue i comandi senza sandbox. Per usare la sandbox su una macchina Windows, esegui Claude Code all'interno di una distribuzione WSL2.

Cosa limita la sandbox

Quando la sandbox è attiva, i comandi della shell eseguiti da Claude partono all'interno dei suoi confini, così come i processi che essi avviano. La sandbox è disattivata per impostazione predefinita. Per attivarla, esegui /sandbox in una sessione, come mostrato in Iniziare, oppure imposta sandbox.enabled su true in un file di impostazioni come ~/.claude/settings.json.

La tabella mostra cosa può raggiungere per impostazione predefinita un comando eseguito nella sandbox e le impostazioni che modificano ciascun valore predefinito.

Accesso	Predefinito	Modificalo con
Scritture	La directory di lavoro, una directory temporanea per utente e le directory che hai aggiunto. I percorsi protetti restano negati in scrittura	`filesystem.allowWrite`, `filesystem.denyWrite`
Letture	La maggior parte della macchina, inclusi i file di credenziali come `~/.ssh` e `~/.aws/credentials`	`filesystem.denyRead`, `credentials`
Rete	Nessun percorso diretto verso l'esterno. Le connessioni passano attraverso un proxy sulla tua macchina che controlla ogni host rispetto ai tuoi domini consentiti, che inizialmente sono vuoti. La tua modalità di permesso decide cosa succede agli altri host	`network.allowedDomains`, `network.deniedDomains`
Variabili d'ambiente	Ereditate da Claude Code, inclusi eventuali segreti presenti nel suo ambiente	`credentials`, `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`

Claude Code crea la sandbox a partire dal pacchetto open source @anthropic-ai/sandbox-runtime.

Cosa viene eseguito al di fuori della sandbox

La sandbox avvolge i comandi della shell. Questi strumenti e processi vengono eseguiti al di fuori di essa:

Strumenti integrati per file e web: strumenti come Read, Edit, Write, WebFetch e WebSearch seguono invece le regole di permesso. Una voce denyRead non blocca lo strumento Read e allowedDomains non limita WebFetch
Altri processi avviati da Claude Code: gli hook di tipo comando, i server MCP locali, i monitor dei plugin, i server LSP e i comandi di supporto come il comando della tua riga di stato e apiKeyHelper vengono eseguiti con il tuo accesso completo

Anche alcuni comandi della shell vengono eseguiti al di fuori della sandbox, a seconda delle tue impostazioni:

Comandi che digiti tu stesso: un comando che inserisci al prompt della modalità shell ! viene eseguito fuori dalla sandbox nella maggior parte delle sessioni. La modalità sandbox rigorosa elenca le sessioni in cui un comando che digiti viene eseguito nella sandbox
Comandi esclusi: i comandi che corrispondono a excludedCommands vengono eseguiti fuori dalla sandbox
Nuovi tentativi fuori dalla sandbox: Claude può chiedere di eseguire un comando fuori dalla sandbox, di solito dopo che non è riuscito nella sandbox

Per porre gli strumenti, i processi e i comandi di questa sezione dietro un unico confine, esegui il processo stesso di Claude Code in un container, una macchina virtuale o il runtime della sandbox.

Inizia

La sandbox è integrata in Claude Code. Cosa installare dipende dalla tua piattaforma:

macOS: il sandboxing usa il framework integrato Seatbelt, quindi puoi passare direttamente ai passaggi
Linux e WSL2: la sandbox si basa su bubblewrap e socat, trattati in Configurare Linux e WSL2. Anche se non li hai ancora installati, puoi iniziare con /sandbox, perché il suo pannello mostra se manca qualcosa

Esegui /sandbox

Avvia una sessione di Claude Code ed esegui il comando /sandbox:

/sandbox

Si apre il pannello della sandbox con tre schede, più una scheda Dependencies su Linux quando manca il filtro seccomp opzionale:

Mode: scegli come vengono approvati i comandi in sandbox, argomento del passaggio successivo
Overrides: scegli se i comandi che falliscono nella sandbox possono ripiegare sull'esecuzione fuori dalla sandbox. Questa è l'impostazione allowUnsandboxedCommands
Config: visualizza le impostazioni della sandbox risolte

Se il pannello mostra solo una scheda Dependencies, manca un pacchetto richiesto. Installalo come descritto in Configurare Linux e WSL2, riavvia Claude Code ed esegui di nuovo /sandbox.

Scegli una modalità

Nella scheda Mode, seleziona auto-allow o permessi regolari. Auto-allow esegue i comandi in sandbox senza chiedere, mentre i permessi regolari mantengono le normali richieste di permesso anche quando i comandi sono in sandbox. Consulta Modalità della sandbox per sapere quali comandi richiedono ancora conferma in modalità auto-allow.

Esegui un comando Bash

Chiedi a Claude di eseguire un comando, come una build o una suite di test. Per impostazione predefinita, i comandi all'interno della sandbox possono scrivere nella directory di lavoro, in una directory temporanea per utente e in qualsiasi directory che hai aggiunto con --add-dir, /add-dir o permissions.additionalDirectories.

La prima volta che un comando ha bisogno di un nuovo dominio di rete, Claude Code chiede l'approvazione; in modalità auto, Claude invece indica gli host di cui un comando ha bisogno sul comando stesso, affinché il classificatore li esamini insieme al comando.

Per ampliare o restringere ciò che la sandbox consente, consulta Configurare il sandboxing.

Se i comandi in sandbox falliscono con Operation not permitted all'interno di un container, consulta Bubblewrap non si avvia all'interno di un container.

Quando selezioni una modalità nel pannello, Claude Code la salva nelle impostazioni locali del tuo progetto in .claude/settings.local.json, che si applicano al progetto corrente. Claude Code aggiunge quel file al tuo gitignore globale quando vi salva un'impostazione. Per abilitare la sandbox in tutti i tuoi progetti, imposta sandbox.enabled su true nelle tue impostazioni utente in ~/.claude/settings.json. Per imporre il sandboxing a ogni sviluppatore di un'organizzazione, usa le impostazioni gestite.

Per modificare la sandbox per una sola sessione senza scrivere in un file di impostazioni, avvia Claude Code con --settings. Ad esempio, questo comando avvia una sessione in sandbox in cui Claude non può riprovare un comando bloccato fuori dalla sandbox:

claude --settings '{"sandbox": {"enabled": true, "allowUnsandboxedCommands": false}}'

Verificare che i comandi vengano eseguiti nella sandbox

Per verificare che la sandbox funzioni, chiedi a Claude di eseguire ciascuna riga della tabella. Ciò che digiti nel prompt ! di solito viene eseguito fuori dalla sandbox, quindi digitare tu stesso una riga non la mette alla prova.

Comando	Risultato all'interno della sandbox
`touch ~/sandbox-probe`	Fallisce con `Operation not permitted` su macOS, oppure `Read-only file system` su Linux e WSL2
`curl --noproxy '*' https://example.com`	Fallisce con `Could not resolve host`, perché il comando non ha alcun percorso che aggiri il proxy della sandbox

Se Claude chiede di riprovare un comando fallito fuori dalla sandbox, rifiuta il nuovo tentativo. Se touch riesce e la tua directory home non è una delle directory in cui la sandbox consente ai comandi di scrivere, elimina ~/sandbox-probe. Poi esegui /sandbox per verificare che la sandbox sia attiva e che le sue dipendenze siano installate.

Configurare Linux e WSL2

Su Linux e WSL2, la sandbox si basa su questi pacchetti:

bubblewrap: lo strumento di sandboxing non privilegiato che applica l'isolamento del filesystem
socat: il relay usato per instradare il traffico di rete attraverso il proxy della sandbox

Installali con il gestore di pacchetti della tua distribuzione:

sudo apt-get install bubblewrap socat

sudo dnf install bubblewrap socat

Quando manca una dipendenza, la scheda Dependencies in /sandbox elenca quali tra ripgrep, bubblewrap, socat e il filtro seccomp mancano alla tua piattaforma. Se non vedi la scheda dopo aver installato e riavviato Claude Code, tutte le dipendenze sono presenti.

Ripgrep è incluso nel binario nativo di Claude Code. Il filtro seccomp è opzionale e aggiunge il blocco dei socket di dominio Unix. Se manca, installalo con npm install -g @anthropic-ai/sandbox-runtime.

Quando manca una dipendenza richiesta, la scheda Dependencies è l'unica mostrata finché non la installi. Quando manca solo il filtro seccomp opzionale, la scheda Dependencies appare insieme alle altre schede. Il controllo delle dipendenze viene eseguito all'avvio, quindi riavvia Claude Code dopo aver installato i pacchetti affinché /sandbox li rilevi.

Su Ubuntu 24.04 e successivi, la policy AppArmor predefinita impedisce a bubblewrap di creare gli user namespace di cui ha bisogno per l'isolamento.

Per verificare se il tuo ambiente applica questa restrizione, anche all'interno di WSL2, esegui `sysctl kernel.apparmor_restrict_unprivileged_userns`. Se il comando restituisce `0`, salta questo passaggio. Se stampa un errore `No such file or directory`, la chiave non esiste e puoi saltare questo passaggio. Se restituisce `1`, aggiungi un profilo AppArmor che conceda a `bwrap` questa capacità:

```bash theme={null}
sudo tee /etc/apparmor.d/bwrap > /dev/null <<'EOF'
abi <abi/4.0>,
include <tunables/global>

profile bwrap /usr/bin/bwrap flags=(unconfined) {
  userns,
  include if exists <local/bwrap>
}
EOF
```

Il profilo si applica solo a `bwrap` stesso, non ai comandi che esegue all'interno della sandbox. Ricarica AppArmor per applicarlo:

```bash theme={null}
sudo systemctl reload apparmor
```

Note su WSL2

Controlla la tua versione di WSL con wsl -l -v da PowerShell. Se vedi Sandboxing requires WSL2, la tua distribuzione sta eseguendo WSL1. Aggiornala a WSL2 oppure esegui Claude Code senza sandboxing.

Su WSL2, WSL passa l'avvio di un binario Windows come cmd.exe, powershell.exe o qualsiasi cosa in /mnt/c/ all'host Windows tramite un socket Unix, quindi la possibilità che un comando in sandbox ne avvii uno dipende dalle impostazioni dei socket Unix della sandbox: il filtro seccomp opzionale deve essere installato perché il socket venga bloccato. Per consentire questi avvii, imposta allowAllUnixSockets, che apre ogni socket Unix ai comandi in sandbox.

Modalità della sandbox

Claude Code offre due modalità della sandbox. In entrambe, la sandbox applica le stesse restrizioni su filesystem e rete; la differenza sta solo nel fatto che i comandi in sandbox vengano approvati automaticamente o richiedano un permesso esplicito.

Modalità auto-allow

Claude Code approva automaticamente un comando, senza chiedere, quando il comando viene eseguito all'interno della sandbox. Un comando segue il normale flusso dei permessi quando viene eseguito fuori dalla sandbox perché corrisponde a excludedCommands o perché Claude lo riprova fuori dalla sandbox.

Un comando in sandbox che si connette a un host che non hai consentito resta nella sandbox. Host al di fuori dei tuoi domini consentiti spiega chi decide se la connessione viene stabilita.

Anche in modalità auto-allow, continuano ad applicarsi i seguenti punti:

Le regole di negazione esplicite vengono sempre rispettate
I comandi rm o rmdir che hanno come destinazione un percorso critico seguono comunque il normale flusso dei permessi
Le regole ask limitate a un contenuto, come Bash(git push *), forzano comunque una richiesta di conferma anche per i comandi in sandbox
Una regola ask Bash semplice, o la forma equivalente Bash(*), viene ignorata per i comandi eseguiti in sandbox; si applica comunque ai comandi che ricadono nel normale flusso dei permessi. Nel plan mode, la regola non viene ignorata: chiede conferma anche per i comandi in sandbox, compresi quelli di sola lettura

Info

La modalità auto-allow funziona indipendentemente dall'impostazione della modalità di permesso, con tre eccezioni: il plan mode, un comando in modalità auto che include domini consentiti per comando e la revisione lato server da parte del classificatore dei comandi in sandbox in modalità auto. Anche se non sei in modalità "accept edits", i comandi Bash in sandbox vengono eseguiti automaticamente quando auto-allow è abilitato. Ciò significa che i comandi Bash che modificano file entro i confini della sandbox vengono eseguiti senza chiedere, anche in modalità Manual, in cui gli strumenti di modifica dei file chiederebbero conferma.

Nel plan mode, auto-allow non amplia le approvazioni; consulta plan mode per sapere come Claude Code controlla i comandi mentre pianifichi.

Modalità permessi regolari

Tutti i comandi Bash seguono il normale flusso dei permessi, anche quando sono in sandbox. Questo offre più controllo ma richiede più approvazioni.

La via di fuga del nuovo tentativo fuori dalla sandbox

Il nuovo tentativo fuori dalla sandbox è una via di fuga per i comandi che falliscono all'interno della sandbox, come gli strumenti incompatibili con essa. Quando la sandbox blocca una connessione di rete, Claude Code indica l'host negato nel risultato del comando, così Claude vede cosa è stato bloccato. Claude analizza l'errore e può riprovare il comando con il parametro dangerouslyDisableSandbox.

Il comando riprovato viene eseguito fuori dalla sandbox. In una sessione interattiva nel terminale, chi lo approva dipende dalla tua modalità di permesso:

Modalità bypassPermissions: il nuovo tentativo viene eseguito senza richiesta di conferma
Modalità Manual e modalità acceptEdits: ricevi una richiesta di conferma intitolata "Bash command (unsandboxed)"
Modalità auto: un modello classificatore separato valuta il comando sottostante
Modalità dontAsk: Claude Code nega il nuovo tentativo
Plan mode: consulta come Claude Code controlla i comandi mentre pianifichi

Queste regole e impostazioni cambiano chi approva il nuovo tentativo:

Una regola allow corrispondente: se una regola allow come Bash(curl *) corrisponde al comando, approva anche il nuovo tentativo, quindi il comando viene eseguito fuori dalla sandbox senza richiesta di conferma
Una regola ask per il parametro: aggiungi una regola ask per Bash(dangerouslyDisableSandbox:true) per ricevere una richiesta di conferma sui nuovi tentativi Bash. Ricevi la richiesta anche in modalità auto e in modalità bypassPermissions, e la regola ha la precedenza su una regola allow corrispondente
permissions.blockReadsOutsideWorkingDirectories: Azioni che nessuna modalità approva automaticamente descrive i nuovi tentativi che chiedono conferma mentre è attiva

Disattivare il nuovo tentativo con la modalità sandbox rigorosa

Puoi disabilitare il nuovo tentativo fuori dalla sandbox impostando "allowUnsandboxedCommands": false nelle tue impostazioni della sandbox. Con il nuovo tentativo disabilitato, Claude Code ignora il parametro dangerouslyDisableSandbox. Mentre la sandbox è in esecuzione, i comandi eseguiti da Claude vengono quindi eseguiti in sandbox, a meno che non corrispondano a una voce di excludedCommands. Per impedire a Claude Code di eseguire comandi fuori dalla sandbox quando la sandbox non può avviarsi, imposta anche failIfUnavailable. La scheda Overrides di /sandbox mostra questa impostazione come Strict sandbox mode.

Un valore false nelle tue impostazioni utente, in --settings o nelle impostazioni gestite resta valido anche quando le impostazioni di un progetto impostano true. Un valore false nelle tue impostazioni utente non rende la sandbox richiesta dall'amministratore, quindi le altre impostazioni della sandbox di un progetto continuano ad applicarsi. Prima della v2.1.285, un true di un progetto sovrascriveva un false nelle tue impostazioni utente.

Se tu o il tuo amministratore disabilitate il nuovo tentativo nelle impostazioni gestite o con il flag --settings, la sandbox diventa richiesta dall'amministratore. Claude Code ignora quindi le impostazioni nei file di un repository che allentano la sandbox, comprese le voci di excludedCommands. Impostazioni del repository con una sandbox richiesta dall'amministratore le elenca.

La modalità sandbox rigorosa si applica ai comandi eseguiti da Claude. I comandi che digiti tu stesso nel prompt della modalità shell ! vengono eseguiti fuori dalla sandbox, a meno che la sessione non sia una di queste:

Una sessione in background: la modalità sandbox rigorosa copre anche i comandi in modalità shell
Una sessione Linux con CLAUDE_CODE_SUBPROCESS_ENV_SCRUB impostata: ogni comando viene eseguito in sandbox, compresi i comandi in modalità shell

Prima della v2.1.260, la modalità sandbox rigorosa eseguiva in sandbox i comandi in modalità shell in ogni sessione.

Directory temporanee

Per impostazione predefinita, una directory temporanea per utente è scrivibile all'interno della sandbox, insieme alla directory di lavoro. A meno che tu non disabiliti l'isolamento del filesystem, Claude Code imposta $TMPDIR su questa directory per i comandi in sandbox, così gli strumenti che scrivono file temporanei funzionano senza configurazione aggiuntiva.

I comandi fuori dalla sandbox ereditano il $TMPDIR della tua shell quando è impostato, quindi mentre l'isolamento del filesystem è attivo, i comandi in sandbox e quelli fuori dalla sandbox risolvono $TMPDIR in directory diverse. Se la tua shell lascia $TMPDIR non impostato o vuoto, un comando fuori dalla sandbox che fa riferimento a $TMPDIR riceve il tuo override CLAUDE_CODE_TMPDIR, oppure la directory temporanea del sistema operativo quando non ne hai impostato uno o l'override è un percorso lungo, così la variabile non si espande in una stringa vuota. Per passare file temporanei tra i due, scrivili invece nella directory di lavoro.

Configurare il sandboxing

Personalizza il comportamento della sandbox tramite il file settings.json. Consulta Impostazioni per il riferimento completo della configurazione.

Per impostazione predefinita, i comandi in sandbox possono scrivere nella directory di lavoro corrente, nella directory temporanea per utente e in qualsiasi directory che hai aggiunto con --add-dir, /add-dir o permissions.additionalDirectories. Se comandi eseguiti come sottoprocessi, come kubectl, terraform o npm, devono scrivere al di fuori di quelle directory, usa sandbox.filesystem.allowWrite per concedere l'accesso a percorsi specifici:

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "allowWrite": ["~/.kube", "/tmp/build"]
    }
  }
}

Questi percorsi vengono applicati a livello di sistema operativo, quindi tutti i comandi eseguiti all'interno della sandbox, inclusi i loro processi figli, li rispettano. Questo è l'approccio consigliato quando uno strumento ha bisogno dell'accesso in scrittura a una posizione specifica, anziché escludere completamente lo strumento dalla sandbox con excludedCommands.

Quando definisci lo stesso array del filesystem in più ambiti di impostazioni, Claude Code ne esegue il merge, combinando i percorsi anziché sostituire l'array di un ambito con quello di un altro. Claude Code esclude una voce dal merge quando è coperta da un blocco descritto in Impedire agli sviluppatori di ampliare la policy.

Se escludi un'origine con --setting-sources nella CLI o con settingSources nell'Agent SDK, Claude Code ignora le sue voci sandbox.filesystem, le sue regole di permesso Edit e le sue regole di negazione Read durante la creazione della configurazione della sandbox. Richiede Claude Code v2.1.246 o successivo.

Quando modifichi questi elenchi del filesystem durante una sessione, Claude Code applica la modifica alla sessione in corso, quindi il successivo comando in sandbox viene eseguito con i nuovi percorsi.

I percorsi del filesystem della sandbox usano le convenzioni standard: /tmp/build è assoluto e ~/.kube è relativo alla tua directory home. Questa sintassi è diversa da quella delle regole di permesso Read e Edit, che usano //path per i percorsi assoluti e /path per quelli relativi al progetto. Per i percorsi relativi, le barre finali e i caratteri jolly, consulta Prefissi dei percorsi della sandbox.

Puoi anche negare l'accesso in scrittura o in lettura usando sandbox.filesystem.denyWrite e sandbox.filesystem.denyRead, e consentire di nuovo percorsi specifici all'interno di un'area negata usando sandbox.filesystem.allowRead. Quando le regole di lettura si sovrappongono, si applica la regola con il percorso più ristretto:

Regole di esempio	Risultato
`"denyRead": ["~/"]` con `"allowRead": ["~/projects"]`	`~/projects` è leggibile e il resto della directory home resta bloccato. Il permesso più ristretto riapre quella parte dell'area negata
`"allowRead": ["~/"]` con `"denyRead": ["~/.env"]`	`~/.env` resta bloccato e il resto della directory home è leggibile. La negazione resta valida all'interno di un permesso più ampio, quindi un permesso esteso non può esporre di nuovo silenziosamente un segreto
`"allowRead": ["~/"]` con `"denyRead": ["~/**/.env"]`	Ogni `.env` sotto la directory home resta bloccato e il resto è leggibile. Una negazione con carattere jolly resta valida all'interno di un permesso più ampio allo stesso modo di un percorso esatto

L'esempio seguente blocca la lettura dall'intera directory home pur consentendo la lettura dal progetto corrente. Inseriscilo nel file .claude/settings.json del tuo progetto, perché il percorso relativo . si risolve nella radice del progetto solo quando la configurazione si trova nelle impostazioni di progetto:

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "denyRead": ["~/"],
      "allowRead": ["."]
    }
  }
}

Se inserissi la stessa configurazione in ~/.claude/settings.json, . si risolverebbe invece in ~/.claude e i file del progetto resterebbero bloccati dalla regola denyRead.

Per negare ai comandi in sandbox l'accesso in lettura alle directory home e ai volumi montati mantenendo leggibili le directory di lavoro, imposta permissions.blockReadsOutsideWorkingDirectories invece di scrivere regole sui percorsi.

Eseguire comandi al di fuori della sandbox con `excludedCommands`

Elenca un pattern di comando in sandbox.excludedCommands per eseguire i comandi corrispondenti al di fuori della sandbox, il che significa nessuna restrizione del filesystem e nessun proxy di rete. Usalo per uno strumento che non può funzionare all'interno della sandbox e a cui affidi il tuo accesso completo. Uno strumento che ha bisogno di una directory o di un host in più potrebbe funzionare con allowWrite o allowedDomains, che mantengono il comando in sandbox.

Questo esempio porta i comandi docker compose fuori dalla sandbox. Salvalo in ~/.claude/settings.json per applicarlo a tutti i tuoi progetti:

{
  "sandbox": {
    "enabled": true,
    "excludedCommands": ["docker compose *"]
  }
}

Claude Code confronta le tue voci con ogni chiamata Bash e Monitor. Una chiamata è l'intera riga di comando che Claude invia, che può concatenare più comandi. Le seguenti regole decidono se una chiamata esce dalla sandbox:

Termina il pattern con *: le voci usano la stessa sintassi di una regola di permesso Bash(...), in cui un pattern senza carattere jolly è una corrispondenza esatta. docker corrisponde solo a docker senza argomenti. docker * corrisponde a docker con o senza argomenti
Ogni comando nella chiamata deve corrispondere: npm ci && docker compose build resta in sandbox a meno che un'altra voce non copra npm ci
Claude Code confronta il testo della chiamata: uno script o un target make che chiama docker internamente non corrisponde, e nemmeno /usr/local/bin/docker
Alcune chiamate restano in sandbox: un reindirizzamento a un file, un cd o una sostituzione di comando come $(...) mantiene in sandbox l'intera chiamata. La voce di riferimento elenca altre chiamate che restano in sandbox
Il punto in cui salvi la voce può fare la differenza: quando la sandbox è richiesta dall'amministratore, Claude Code ignora le voci in .claude/settings.json e .claude/settings.local.json

Un comando escluso segue il normale flusso dei permessi:

I comandi di sola lettura e i comandi coperti dalle tue regole di autorizzazione vengono eseguiti senza richiesta di conferma
In modalità auto, il classificatore esamina gli altri comandi esclusi
In modalità bypassPermissions, un comando escluso viene eseguito senza richiesta di conferma a meno che non corrisponda a una regola ask

Per verificare che una voce corrisponda, passa alla modalità Manual e chiedi a Claude di eseguire un comando corrispondente che modifichi qualcosa, come docker compose up -d. La richiesta di permesso ha il titolo "Bash command (unsandboxed)".

Disattivare l'isolamento del filesystem

Imposta sandbox.filesystem.disabled su true per saltare l'isolamento del filesystem mantenendo l'isolamento di rete. L'esempio seguente disattiva l'isolamento del filesystem mantenendo un'allowlist di domini di rete:

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "disabled": true
    },
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org"]
    }
  }
}

La sandbox ha due livelli indipendenti: l'isolamento del filesystem controlla quali percorsi i comandi in sandbox possono leggere e scrivere, e l'isolamento di rete controlla quali domini possono raggiungere. Con il livello del filesystem disattivato, i comandi in sandbox ottengono accesso illimitato in lettura e scrittura al filesystem dell'host, mentre il loro traffico di rete in uscita resta limitato ai domini consentiti. Disattiva questo livello quando usi la sandbox per controllare dove si connettono i comandi anziché cosa scrivono.

sandbox.filesystem.disabled ha false come valore predefinito. Richiede Claude Code v2.1.216 o successivo.

Quali impostazioni possono disattivarlo

Poiché disattivare l'isolamento del filesystem amplia ciò che i comandi in sandbox possono fare, Claude Code rispetta filesystem.disabled solo da queste origini di impostazioni:

Le impostazioni utente, le impostazioni gestite e il flag CLI --settings possono impostarlo. Le impostazioni di progetto in .claude/settings.json e .claude/settings.local.json non possono, quindi un progetto scaricato non può disattivare l'isolamento del filesystem.
Quando le impostazioni gestite configurano sandbox.filesystem in qualsiasi modo, o elencano una qualsiasi voce sandbox.credentials.files con "mode": "deny", solo le impostazioni gestite possono impostare la chiave. Questo mantiene in vigore le restrizioni del filesystem distribuite dall'amministratore; per allentare tale distribuzione, imposta "disabled": true nelle impostazioni gestite.
Quando CLAUDE_CODE_SUBPROCESS_ENV_SCRUB è impostata, Claude Code ignora filesystem.disabled da ogni origine, incluse le impostazioni gestite, e mantiene attivo l'isolamento del filesystem.

Una voce mask valida non blocca la chiave, anche quando Claude Code ripiega su deny per essa all'avvio. Elenca un percorso che non può essere mascherato, come una directory di credenziali, come voce deny esplicita nelle impostazioni gestite, che blocca la chiave.

Cosa cambia quando l'isolamento del filesystem è disattivato

L'impostazione di filesystem.disabled rimuove le protezioni applicate dal livello del filesystem stesso. Le protezioni applicate da altri livelli continuano a valere:

Protezione	Con l'isolamento del filesystem disattivato
Blocchi di lettura `filesystem.denyRead` e `deny` di `credentials.files`	Non applicati. Entrambi sono applicati dal livello del filesystem
Voci `deny` e `mask` di `credentials.envVars`	Applicate. La rimozione delle variabili d'ambiente è indipendente dal livello del filesystem
Voci `mask` di `credentials.files` applicate come maschere	Applicate: il mascheramento è indipendente dal livello del filesystem. Una voce ripiegata su `deny` non viene applicata, come qualsiasi voce `deny`

Cambiano altre due cose:

I comandi in sandbox ereditano il $TMPDIR della tua shell invece della directory temporanea per utente, perché ogni directory temporanea è scrivibile e Claude Code non reindirizza più i comandi a quella per utente.

Su Linux la variabile spesso non è impostata nella shell padre. Le indicazioni dello strumento Bash dicono a Claude di creare directory temporanee con mktemp -d invece di affidarsi a $TMPDIR.
autoAllowBashIfSandboxed ha ancora true come valore predefinito, quindi i comandi in sandbox continuano a essere eseguiti senza richiesta di conferma. Impostalo su false per chiedere conferma per i comandi in sandbox.

Proteggere le credenziali

L'impostazione sandbox.credentials dichiara i file di credenziali e le variabili d'ambiente da proteggere dai comandi in sandbox. Ogni voce indica un percorso di file o una variabile d'ambiente e un mode. Il blocco dedicato credentials mantiene le regole sulle credenziali raggruppate e separate dalle regole generali del filesystem.

Per le voci con "mode": "deny", ai percorsi dei file viene negata la lettura all'interno della sandbox, la stessa restrizione applicata da filesystem.denyRead, e le variabili d'ambiente vengono rimosse prima dell'esecuzione di ogni comando in sandbox. La protezione dei file fa parte del livello del filesystem, quindi non si applica se disattivi l'isolamento del filesystem; la protezione delle variabili d'ambiente invece sì.

L'esempio seguente blocca la lettura del file delle credenziali AWS e della directory SSH e rimuove GITHUB_TOKEN e NPM_TOKEN dall'ambiente dei comandi in sandbox:

{
  "sandbox": {
    "enabled": true,
    "credentials": {
      "files": [
        { "path": "~/.aws/credentials", "mode": "deny" },
        { "path": "~/.ssh", "mode": "deny" }
      ],
      "envVars": [
        { "name": "GITHUB_TOKEN", "mode": "deny" },
        { "name": "NPM_TOKEN", "mode": "deny" }
      ]
    }
  }
}

Le voci delle variabili d'ambiente e dei file accettano anche "mode": "mask", descritto in Mascherare le credenziali.

I percorsi dei file seguono le stesse regole sui prefissi delle impostazioni sandbox.filesystem.*.

Claude Code combina le voci deny di ogni ambito di impostazioni caricato dalla sessione. Una voce deny restringe sempre e solo l'accesso, quindi qualsiasi ambito può aggiungerne una, ma nessun ambito può rimuoverne una aggiunta da un altro ambito.

Quando escludi un'origine di impostazioni:

Impostazioni di progetto o locali: Claude Code non applica nessuna delle loro voci credentials. Richiede Claude Code v2.1.246 o successivo.
Impostazioni utente: Claude Code applica comunque le voci deny in ~/.claude/settings.json e mantiene le sue voci mask dei file come restrizioni che non autorizzano più il proxy a sostituire il valore reale, ma scarta le sue voci mask delle variabili d'ambiente.

Non esiste un elenco integrato di credenziali negate, quindi sono limitati solo i file e le variabili che elenchi.

sandbox.credentials riguarda solo i comandi Bash in sandbox. Per rimuovere le credenziali da tutti i sottoprocessi indipendentemente dal sandboxing, imposta CLAUDE_CODE_SUBPROCESS_ENV_SCRUB.

Mascherare le credenziali

Quando mascheri una credenziale, Claude Code mostra ai comandi in sandbox un segnaposto valido per la sessione, chiamato sentinella, e il proxy della sandbox sostituisce il valore reale nelle richieste in uscita verso gli host che consenti. Una voce deny descritta in Proteggere le credenziali blocca invece la credenziale. Per i file su macOS, Claude Code blocca il file invece di mascherarlo.

Il mascheramento delle variabili d'ambiente richiede Claude Code v2.1.199 o successivo. Il riferimento di sandbox.credentials elenca tutti i campi.

Il mascheramento richiede quanto segue:

Terminazione TLS: il proxy sostituisce il valore reale all'interno del contenuto delle richieste, quindi deve poterlo vedere. Imposta network.tlsTerminate in modo che il proxy termini direttamente il TLS. Senza di esso, il mascheramento fallisce senza esporre nulla: il comando vede comunque solo la sentinella, ma la sentinella raggiunge il server invariata e l'autenticazione fallisce. Claude Code segnala questa configurazione errata all'avvio.
Una destinazione consentita: ogni voce mask può elencare injectHosts, gli host che il valore reale può raggiungere. Il proxy inserisce le credenziali solo nelle connessioni ammesse dall'allowlist dei domini, quindi ogni host injectHosts deve essere raggiungibile anche tramite network.allowedDomains. Per una voce mask senza injectHosts, il proxy sostituisce il valore reale nelle richieste verso ogni host in network.allowedDomains.
Un ambito di impostazioni attendibile: il mascheramento autorizza il proxy a inviare la tua credenziale reale altrove, quindi Claude Code rispetta le voci mask, network.tlsTerminate, credentials.allowPlaintextInject, awsPairs e sigv4 solo dalle impostazioni utente, dalle impostazioni gestite e dal flag --settings. Li ignora nei file .claude/settings.json o .claude/settings.local.json di un repository. Quando il tuo amministratore distribuisce voci mask, network.tlsTerminate o credentials.allowPlaintextInject tramite impostazioni gestite dal server, queste vengono considerate impostazioni che richiedono approvazione.

Mascherare le variabili d'ambiente

Per mascherare una variabile d'ambiente, imposta "mode": "mask" sulla sua voce credentials.envVars. Il comando e tutto ciò che registra nei log non contengono mai la credenziale reale, ma le sue richieste vengono comunque autenticate. Quando la stessa variabile è elencata con deny in qualsiasi ambito, deny ha la precedenza.

L'esempio seguente maschera due token. GH_TOKEN viene sostituito solo nelle richieste verso api.github.com, mentre NPM_TOKEN non ha injectHosts e viene sostituito nelle richieste verso ogni host in network.allowedDomains:

{
  "sandbox": {
    "enabled": true,
    "network": {
      "tlsTerminate": {},
      "allowedDomains": ["*.github.com", "registry.npmjs.org"]
    },
    "credentials": {
      "envVars": [
        { "name": "GH_TOKEN", "mode": "mask", "injectHosts": ["api.github.com"] },
        { "name": "NPM_TOKEN", "mode": "mask" }
      ]
    }
  }
}

Per impostazione predefinita il mascheramento sostituisce l'intero valore. Per un valore strutturato, come una stringa di connessione DATABASE_URL o un JWT, usa i campi extract, decode, maskClaims e onExtractNoMatch in modo che gli strumenti che analizzano il valore continuino a funzionare.

Per una destinazione IPv6, scrivi l'indirizzo in modo diverso nei due elenchi:

network.allowedDomains: la forma tra parentesi quadre, come "[::1]"
injectHosts: l'indirizzo senza parentesi nella sua forma compressa canonica, come "::1"

Il proxy confronta ogni voce injectHosts con l'indirizzo di destinazione senza parentesi della connessione, ignorando le porte, quindi una scrittura tra parentesi, con ID di zona o compressa in modo diverso non corrisponde mai. claude doctor segnala le voci che non possono mai corrispondere con l'avviso Sandbox credential injectHosts entries can never match their destination. Questo controllo richiede Claude Code v2.1.229 o successivo.

Firmare di nuovo le richieste AWS

Le richieste AWS contengono firme SigV4 calcolate sul contenuto della richiesta, quindi maschera AWS_ACCESS_KEY_ID e AWS_SECRET_ACCESS_KEY insieme. Il proxy rileva una richiesta SigV4 tramite la sentinella della chiave di accesso e firma di nuovo la richiesta con i valori reali, il che richiede Claude Code v2.1.221 o successivo. Se mascheri solo il segreto, le richieste vengono firmate con un segnaposto che il proxy non può rilevare, quindi falliscono su AWS.

Claude Code collega automaticamente le variabili convenzionali AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY e AWS_SESSION_TOKEN in un'unica credenziale quando ne mascheri l'intero valore. Se la tua credenziale AWS si trova in variabili con altri nomi, raggruppale con credentials.awsPairs, che richiede Claude Code v2.1.224 o successivo.

I caricamenti in streaming, gli URL prefirmati e le richieste SigV4A contengono firme che il proxy non può ricalcolare. Quando una di queste richieste è firmata con il segnaposto di una coppia mascherata, il proxy la fa fallire anziché inoltrare una firma non valida. Le richieste firmate con credenziali non mascherate non sono interessate. Usa credentials.sigv4, che richiede Claude Code v2.1.224 o successivo, per inoltrare invece una di queste forme di richiesta. AWS rifiuta comunque la richiesta, quindi lo strumento chiamante riceve la risposta di rifiuto di AWS invece di un errore del proxy.

Mascherare i file di credenziali

Per mascherare un file di credenziali, imposta "mode": "mask" sulla sua voce credentials.files. Il mascheramento dei file richiede Claude Code v2.1.221 o successivo. Ciò che vede un comando in sandbox dipende dalla piattaforma:

Linux e WSL2: i comandi in sandbox leggono una copia sentinella del file, e il proxy sostituisce il valore reale nelle richieste in uscita.
macOS: i comandi in sandbox non possono leggere affatto il file. Claude Code non crea alcuna copia sentinella, quindi gli strumenti che si autenticano con il file non funzionano all'interno della sandbox, lo stesso effetto di deny. Il blocco della lettura resta valido anche quando disattivi l'isolamento del filesystem.

L'esempio seguente maschera un token GitHub memorizzato in ~/.config/gh/hosts.yml. Il pattern extract indica quale parte del file è il segreto, quindi su Linux e WSL2 gh analizza ancora il resto della sua configurazione:

{
  "sandbox": {
    "enabled": true,
    "network": {
      "tlsTerminate": {},
      "allowedDomains": ["*.github.com"]
    },
    "credentials": {
      "files": [
        {
          "path": "~/.config/gh/hosts.yml",
          "mode": "mask",
          "extract": "oauth_token:\\s*(\\S+)",
          "injectHosts": ["api.github.com"]
        }
      ]
    }
  }
}

Per verificare che la maschera sia attiva, chiedi a Claude di eseguire cat ~/.config/gh/hosts.yml in un comando in sandbox. Su Linux e WSL2 l'output mostra una sentinella al posto del token, mentre su macOS la lettura fallisce.

Senza extract o decode, Claude Code sostituisce l'intero file con un'unica sentinella, il che è adatto a un file che contiene un singolo segreto semplice. Usa i campi extract, decode, maskClaims, onExtractNoMatch e maskDuplicates per controllare il mascheramento parziale e cosa succede quando il pattern non trova corrispondenze.

mask si applica a un singolo file, quindi elenca ogni file di credenziali singolarmente. Claude Code ripiega su deny per una voce mask che non può mascherare in modo sicuro: un percorso di directory, un pattern glob, un file più grande di 8 MiB o un file che non è testo UTF-8.

Come funziona il sandboxing

Isolamento del filesystem

Lo strumento Bash in sandbox limita l'accesso al file system a directory specifiche:

Comportamento di scrittura predefinito: accesso in lettura e scrittura alla directory di lavoro corrente e alle sue sottodirectory, a tutte le directory che hai aggiunto con --add-dir, /add-dir o permissions.additionalDirectories, oltre alla directory temporanea per utente a cui punta $TMPDIR
Comportamento di lettura predefinito: accesso in lettura all'intero computer, eccetto alcune directory negate. Questa impostazione predefinita consente comunque la lettura dei file di credenziali, quindi proteggi le credenziali che non vuoi che i comandi leggano.
Blocco della lettura: con permissions.blockReadsOutsideWorkingDirectories attivo, i comandi in sandbox perdono anche l'accesso in lettura alla tua directory home e alle altre directory che contengono file utente, a parte i percorsi elencati in Comandi in sandbox sotto il blocco. Quella sezione indica anche quando questa parte del blocco non si applica.
Worktree Git: quando la directory di lavoro è un worktree git collegato, la sandbox consente anche le scritture nella directory .git condivisa del repository principale, in modo che comandi come git commit possano aggiornare i ref e l'indice. Le scritture in hooks/ e config all'interno di quella directory restano negate.

Per saltare completamente l'isolamento del filesystem mantenendo l'isolamento di rete, imposta sandbox.filesystem.disabled.

Percorsi protetti

All'interno delle directory in cui i comandi in sandbox possono scrivere, la sandbox nega comunque le scritture nei file da cui Claude Code carica configurazione e codice. Un comando in grado di modificare quei file potrebbe concedersi dei permessi, oppure aggiungere un hook o un server MCP che Claude Code esegue fuori dalla sandbox. Il sistema dei permessi ha i propri percorsi protetti, che controllano cosa Claude Code approva prima che uno strumento venga eseguito; l'elenco della sandbox si applica a un comando già in esecuzione. Copre quattro gruppi di percorsi:

Nella tua directory di lavoro e nelle directory superiori: i file di impostazioni .claude, le directory .claude/skills, .claude/agents, .claude/commands e .claude/hooks, .mcp.json e i file che Claude Code esegue autonomamente, come .claude/workflows e .claude/scheduled_tasks.json
Solo nella tua directory di lavoro: i file di avvio della shell come .bashrc e .zshrc, .gitconfig, le directory .vscode e .idea, e hooks e config all'interno di .git
File che trasformerebbero la tua directory di lavoro in un repository git bare: HEAD, objects e refs al livello superiore, più le voci config e hooks esistenti in quel punto quando accanto a esse si trova un HEAD. Un file chiamato config viene negato anche in assenza di HEAD. Su Linux e WSL2, la sandbox elimina un file HEAD o una directory objects o refs di livello superiore che compare mentre un comando in sandbox è in esecuzione
In ~/.claude, o nella directory a cui punta CLAUDE_CONFIG_DIR: la maggior parte del suo contenuto, più ~/.claude.json e l'archivio delle credenziali .credentials.json

Se durante la sessione compare un collegamento simbolico nel percorso di un file di impostazioni protetto, la sandbox nega anche le scritture nel file a cui punta, a partire dal comando successivo.

Non c'è modo di esentare uno di questi percorsi: una voce allowWrite o una regola di consenso Edit che copre il percorso non rimuove la protezione. L'unico modo per disattivare la protezione è filesystem.disabled, che disattiva l'isolamento del filesystem per ogni percorso. Per vedere la maggior parte di questi percorsi risolti per la tua macchina, esegui /sandbox e apri la scheda Config, che li elenca sotto Denied within allowed, insieme alle tue voci denyWrite.

Se git merge o git checkout non riesce con unable to unlink old su uno di questi percorsi, consulta Un comando git non riesce con unable to unlink old.

Isolamento di rete

Un comando in sandbox non ha un accesso diretto alla rete:

Linux e WSL2: il comando viene eseguito in un namespace di rete separato che non ha alcuna connessione alla tua rete
macOS: il framework sandbox Seatbelt blocca per impostazione predefinita le connessioni diverse da quella verso il proxy della sandbox

Claude Code esegue il proxy della sandbox sulla tua macchina, fuori dalla sandbox, e indirizza i comandi verso di esso con HTTP_PROXY, HTTPS_PROXY, ALL_PROXY e le variabili d'ambiente correlate. Il proxy confronta il nome host di ogni connessione con i tuoi domini consentiti e negati.

Ciò che uno strumento può raggiungere dipende dal fatto che utilizzi o meno il proxy:

Strumenti che leggono le variabili del proxy: curl, npm, git su HTTPS e strumenti simili si connettono una volta che il loro host è consentito. Una voce allowedDomains senza porta consente ogni porta su quell'host
Strumenti che ignorano le variabili del proxy: ssh semplice, la maggior parte dei driver di database e strumenti simili non possono connettersi, nemmeno a un host consentito. Consulta Un client di database o un altro strumento non HTTP non riesce a raggiungere un host consentito
Tutto ciò che non è TCP: UDP, HTTP/3 su QUIC e gli strumenti ICMP come ping non possono uscire dalla sandbox

Le seguenti impostazioni e comportamenti controllano quali host il proxy consente:

Restrizioni sui domini: i tuoi domini consentiti all'inizio sono vuoti. Host al di fuori dei tuoi domini consentiti descrive cosa succede la prima volta che un comando ha bisogno di un nuovo dominio.
Scelte di approvazione: se scegli Yes quando ti viene chiesto, Claude Code consente l'host per il resto della sessione corrente. Se scegli "Yes, and don't ask again", Claude Code salva una regola di consenso WebFetch(domain:...) nelle tue impostazioni locali, così l'host resta consentito nelle sessioni future. Mentre la sandbox è richiesta dall'amministratore, Claude Code salva la regola nelle tue impostazioni utente, dove si applica in ogni progetto.
Domini pre-consentiti: pre-consenti i domini con allowedDomains per evitare del tutto la richiesta di conferma. Claude Code pre-consente anche i domini provenienti dalle regole di consenso WebFetch(domain:...), come descritto in Regole di permesso.
Allowlist rigorosa: se imposti strictAllowlist su true nelle impostazioni utente, gestite o CLI --settings, Claude Code nega ai comandi in sandbox l'accesso a qualsiasi host al di fuori dell'allowlist invece di chiedere. L'allowlist è composta da allowedDomains più i domini delle regole di consenso WebFetch(domain:...), oppure solo dalle voci delle impostazioni gestite quando è impostato allowManagedDomainsOnly. Blocchi che si applicano senza una sandbox richiesta dall'amministratore descrive le voci di un repository. Claude Code applica questa impostazione solo ai comandi in sandbox; gli strumenti in-process come WebFetch seguono comunque le loro regole di permesso. Impostarla nel file .claude/settings.json o .claude/settings.local.json di un repository non ha alcun effetto. Richiede Claude Code v2.1.219 o successivo.
Blocco gestito: se allowManagedDomainsOnly è impostato nelle impostazioni gestite, i domini non consentiti vengono bloccati automaticamente invece di chiedere, e vengono rispettate solo le regole di consenso allowedDomains e WebFetch(domain:...) provenienti dalle impostazioni gestite.
Proxy aziendale: quando la tua rete richiede che il traffico in uscita passi attraverso un proxy aziendale, imposta HTTPS_PROXY, HTTP_PROXY e NO_PROXY come descritto in configurazione del proxy, nel blocco env delle tue impostazioni in modo che anche gli agenti in background le ricevano, oppure nell'ambiente da cui avvii Claude Code. Claude Code applica l'allowlist dei domini e poi instrada le connessioni consentite attraverso quel proxy upstream. Funzionano gli URL di proxy http:// e https://, con l'autenticazione di base nell'URL se ti serve.

In una regola WebFetch(domain:...), la sandbox rispetta due forme di carattere jolly: un *. iniziale, come *.example.com, e un * da solo. La forma * da solo richiede Claude Code v2.1.186 o successivo. Un carattere jolly in qualsiasi altra posizione, come WebFetch(domain:example.*), corrisponde comunque ai fetch ma non ha alcun effetto sui comandi in sandbox.

Host al di fuori dei tuoi domini consentiti

Quando un comando in sandbox si connette a un host che non è nei tuoi domini consentiti, il comando resta nella sandbox e attende una decisione. In una sessione interattiva nel terminale, la decisione dipende dalla tua modalità di permesso:

Modalità di permesso	Cosa succede alla connessione
Modalità `bypassPermissions` e plan mode con bypass dei permessi disponibile	Consentita senza richiesta di conferma
Modalità manuale, modalità `acceptEdits` e plan mode negli altri casi	Ricevi una richiesta di conferma
Modalità auto	Rifiutata a meno che il comando non abbia elencato l'host e il classificatore non abbia approvato l'elenco
Modalità `dontAsk`	Rifiutata

Con strictAllowlist o allowManagedDomainsOnly attivo, il proxy integrato della sandbox rifiuta la connessione in ogni modalità di permesso. In modalità bypassPermissions, gli host al di fuori dei tuoi domini consentiti sono consentiti a meno che una di queste impostazioni non sia attiva. La via di fuga del nuovo tentativo fuori dalla sandbox spiega quando un comando può uscire dalla sandbox in quella modalità. Anche una connessione a un host presente in deniedDomains viene rifiutata in ogni modalità di permesso.

Nomi host che si risolvono in indirizzi locali

Dopo che un nome host ha superato l'allowlist, il proxy della sandbox lo risolve e rifiuta la connessione quando il nome si risolve solo in indirizzi locali. Gli indirizzi locali includono gli indirizzi di loopback come 127.0.0.1, gli indirizzi link-local come l'endpoint dei metadati cloud 169.254.169.254 e gli indirizzi assegnati alla tua macchina. I nomi localhost e *.localhost possono risolversi in loopback.

Un nome host intranet consentito che si risolve in un intervallo privato come 10.0.0.0/8 si connette. Per consentire a un nome di risolversi in un indirizzo rifiutato, aggiungi quell'indirizzo IP a allowedDomains, ad esempio "127.0.0.1:8080".

Il controllo si applica ai nomi host. Per una connessione a un indirizzo IP decidono i tuoi domini consentiti e la modalità di permesso. Il proxy salta il controllo anche per le connessioni che invia attraverso un proxy aziendale upstream, perché è quel proxy a risolvere il nome.

Domini consentiti per comando in modalità auto

In modalità auto con il sandboxing attivo, Claude indica gli host di cui un comando ha bisogno sul comando stesso, invece di attivare un'approvazione di rete per ogni connessione. Ogni comando Bash, PowerShell o Monitor eseguito nella sandbox può includere un elenco di host oltre all'allowlist della sandbox: un dominio come registry.npmjs.org, un carattere jolly come *.pythonhosted.org o un indirizzo IP, ciascuno con un :port facoltativo. Il classificatore esamina gli host insieme al comando. Richiede Claude Code v2.1.271 o successivo.

Un elenco approvato apre quegli host solo per quel singolo comando, per tutta la durata della sua esecuzione. Non viene aggiunto nulla agli host consentiti della tua sessione né alle tue impostazioni; il comando successivo indica i propri host.

Un comando che include host viene inviato al classificatore invece di essere approvato da una regola di permesso o dalla modalità di consenso automatico della sandbox. Se una regola ask impone una richiesta di conferma per il comando, la finestra di dialogo dei permessi nel tuo terminale elenca gli host accanto a esso, e approvare lì copre entrambi.

Un elenco per comando amplia solo ciò che la sandbox nega per impostazione predefinita. Le voci di deniedDomains continuano a bloccare. Quando strictAllowlist o allowManagedDomainsOnly blocca l'allowlist, Claude Code rifiuta gli elenchi per comando.

Mentre si applicano gli elenchi per comando, Claude Code rifiuta una connessione a un host che nessun comando approvato ha elencato, senza richiesta di conferma né controllo del classificatore. Il rifiuto indica l'host nel risultato del comando, e Claude riesegue il comando con l'host aggiunto.

Indirizzi IPv6 negli elenchi di domini

Per far corrispondere un indirizzo IPv6 in allowedDomains, deniedDomains o in una regola WebFetch(domain:...), scrivi l'indirizzo tra parentesi quadre: "[::1]" corrisponde a quell'indirizzo su ogni porta, e "[::1]:443" corrisponde solo sulla porta 443. La forma tra parentesi quadre richiede Claude Code v2.1.229 o successivo.

Una voce senza parentesi come ::1:443 è ambigua tra un indirizzo e un indirizzo con una porta:

Elenchi di negazione: Claude Code nega ogni interpretazione in cui la voce può essere analizzata, quindi qualunque interpretazione intendessi viene bloccata. Per una voce senza alcuna interpretazione analizzabile, Claude Code non blocca nulla
Elenchi di consenso: Claude Code non consente mai più di quanto hai scritto. Riscrive una voce ambigua nella sua interpretazione host e porta quando tale interpretazione viene analizzata correttamente, e può eliminare completamente la voce anziché ampliare l'allowlist

Per trovare le voci ambigue, esegui claude doctor nel tuo terminale e cerca l'avviso Sandbox network domain entries have unreliable spellings. Riscrivi ciascuna voce ambigua nella forma tra parentesi quadre.

Applicazione a livello di sistema operativo

Lo strumento Bash in sandbox utilizza le primitive di sicurezza del sistema operativo:

macOS: utilizza Seatbelt per l'applicazione della sandbox
Linux: utilizza bubblewrap per l'isolamento
WSL2: utilizza bubblewrap, come Linux

Puoi anche eseguire il pacchetto @anthropic-ai/sandbox-runtime in modo autonomo per incapsulare il processo di Claude Code. Consulta Sandbox runtime.

Come il sandboxing si relaziona alle autorizzazioni e alle modalità di autorizzazione

Il sandboxing, le regole di autorizzazione, e le modalità di autorizzazione sono livelli complementari. Le sezioni seguenti spiegano come la sandbox interagisce con ciascuno.

Regole di autorizzazione

Le regole di autorizzazione e il sandboxing controllano cose diverse:

Le regole di autorizzazione controllano quali strumenti Claude Code può utilizzare e vengono valutate prima che qualsiasi strumento venga eseguito. Si applicano a ogni strumento: Bash, Read, Edit, WebFetch, MCP e altri, tranne per il fatto che una regola di negazione o richiesta non può bloccare EndConversation mentre rimane qualsiasi altro strumento.
Il sandboxing fornisce l'applicazione a livello del sistema operativo che limita ciò a cui i comandi della shell possono accedere a livello di filesystem e di rete. Si applica solo ai comandi Bash, PowerShell e Monitor e ai loro processi figlio.

I due livelli differiscono anche nel modo in cui vengono applicati. Claude Code valuta le decisioni di autorizzazione prima che un comando venga eseguito, in base alla stringa di comando e, in modalità automatica, al giudizio di un classificatore separato su se il comando è sicuro. Il sistema operativo applica il limite della sandbox al processo in esecuzione, quindi rimane indipendentemente da ciò che il modello ha scelto di eseguire e anche se un comando consentito fa più di quanto il suo nome suggerisca.

Le restrizioni del filesystem e della rete sono configurate sia attraverso le impostazioni della sandbox che attraverso le regole di autorizzazione:

Impostazione o regola	Cosa fa
`sandbox.filesystem.allowWrite`	Concede l'accesso in scrittura del sottoprocesso ai percorsi al di fuori della directory di lavoro
`sandbox.filesystem.denyWrite` e `sandbox.filesystem.denyRead`	Bloccano l'accesso del sottoprocesso a percorsi specifici
`sandbox.filesystem.allowRead`	Consente nuovamente la lettura di percorsi specifici all'interno di una regione `denyRead`
`sandbox.filesystem.disabled`	Disattiva completamente il livello del filesystem mantenendo l'isolamento della rete
Regole di autorizzazione `Edit`	Concedono l'accesso in scrittura a percorsi specifici, nello stesso modo in cui `sandbox.filesystem.allowWrite` fa
Regole di negazione `Read` e `Edit`	Bloccano l'accesso a file o directory specifici
Regole di autorizzazione e negazione `WebFetch(domain:...)`	Controllano l'accesso al dominio
`allowedDomains` della sandbox	Controlla quali domini i comandi Bash possono raggiungere
`deniedDomains` della sandbox	Blocca domini specifici anche quando un wildcard `allowedDomains` più ampio altrimenti li permetterebbe

I percorsi e i domini sia dalle impostazioni della sandbox che dalle regole di autorizzazione vengono uniti nella configurazione finale della sandbox.

La directory degli esempi del repository claude-code include configurazioni di impostazioni iniziali per scenari di distribuzione comuni, inclusi esempi specifici della sandbox. Utilizzate questi come punti di partenza e adattateli alle vostre esigenze.

Modalità di autorizzazione

/sandbox non è una modalità di autorizzazione. Le modalità di autorizzazione decidono se una chiamata di strumento viene eseguita e se siete richiesti per primo, mentre la sandbox limita ciò a cui un comando Bash può accedere una volta eseguito. Differiscono in ciò che controllano e cosa sostituisce il prompt per azione:

	Cosa controlla	Cosa sostituisce il prompt
`/sandbox`	Ciò a cui un comando Bash può accedere una volta eseguito	Il limite della sandbox stesso, in modalità auto-allow
Modalità automatica	Se ogni chiamata di strumento viene eseguita	Un classificatore che esamina le azioni
`--dangerously-skip-permissions`	Se ogni chiamata di strumento viene eseguita	Niente. I controlli del percorso protetto vengono anche saltati; le azioni che nessuna modalità auto-approva si applicano ancora

La modalità auto-allow della sandbox è separata dalla modalità automatica: auto-allow approva i comandi Bash perché il limite della sandbox li contiene, mentre la modalità automatica utilizza un classificatore per esaminare le azioni. I due funzionano indipendentemente e possono essere combinati, con le eccezioni elencate in Modalità sandbox. Per scegliere un limite di isolamento per esecuzioni incustodite, vedere Ambienti sandbox. Per una tabella degli accoppiamenti comuni di modalità di autorizzazione e sandbox con i flag che avviano ciascuno, vedere Configurazioni comuni.

Configura la sandbox per la tua organizzazione

Gli amministratori possono richiedere il sandboxing per ogni utente, impedire agli sviluppatori di ampliare la politica e instradare il traffico sandbox attraverso un proxy aziendale.

Applica il sandboxing con le impostazioni gestite

Per richiedere la sandbox per ogni sviluppatore, fornisci le chiavi sandbox tramite impostazioni gestite, sia come file gestito dal tuo MDM che tramite impostazioni gestite dal server su claude.ai.

La seguente configurazione di impostazioni gestite abilita la sandbox, rifiuta di avviare Claude Code quando la piattaforma non è supportata o manca una dipendenza e impedisce al modello di riprovare i comandi al di fuori della sandbox:

{
  "sandbox": {
    "enabled": true,
    "failIfUnavailable": true,
    "allowUnsandboxedCommands": false
  }
}

Le due chiavi oltre enabled controllano cosa succede quando la sandbox non può eseguire un comando:

failIfUnavailable: una dipendenza mancante come bubblewrap su Linux blocca l'avvio di Claude Code piuttosto che ricadere nell'esecuzione non sandboxata
allowUnsandboxedCommands: false: Claude Code ignora l'escape hatch dangerouslyDisableSandbox, quindi quando un comando fallisce sotto la sandbox, Claude non può riprovarlo senza sandbox

Valuta queste aggiunte insieme a loro:

Aggiungi excludedCommands per qualsiasi strumento approvato dall'organizzazione che deve essere eseguito senza isolamento, perché questa configurazione impedisce alle impostazioni di un repository di portare comandi fuori dalla sandbox
Aggiungi voci sandbox.credentials per directory di credenziali come ~/.aws e ~/.ssh e per variabili d'ambiente segrete, poiché la politica di lettura predefinita le consente comunque

Questa configurazione sandboxa i comandi che Claude esegue. Uno sviluppatore può comunque digitare un comando al prompt della modalità shell con ! ed eseguirlo al di fuori della sandbox, con lo stesso accesso che ha già in qualsiasi terminale al di fuori di Claude Code. Vedi la modalità sandbox rigorosa per le sessioni in cui i comandi digitati vengono eseguiti in sandbox.

La sandbox non viene eseguita su Windows nativo, quindi con failIfUnavailable impostato, Claude Code si chiude all'avvio su quelle macchine. Se la tua flotta include host Windows, puoi:

Distribuire la configurazione in base al sistema operativo: distribuiscila tramite il tuo MDM o come file di impostazioni gestite solo sulle macchine macOS e Linux. Le impostazioni gestite dal server si applicano a tutti gli utenti dell'organizzazione
Spostare gli utenti Windows in un ambiente supportato: fai in modo che eseguano Claude Code all'interno di WSL2 o di un container

Impedisci agli sviluppatori di ampliare la politica

Quando le impostazioni gestite impostano una chiave booleana come enabled o failIfUnavailable, Claude Code utilizza il valore gestito e ignora qualsiasi cosa uno sviluppatore imposti localmente. Per chiavi array come allowRead, Claude Code fa il merge delle voci dagli ambiti che la sessione carica, quindi uno sviluppatore può aggiungere voci che ampliano la politica a meno che un blocco non copra quella chiave.

A meno che non siano impostate dalle impostazioni gestite, le impostazioni utente di uno sviluppatore o --settings possono attivare le seguenti chiavi. Può farlo anche il .claude/settings.json di un repository, a meno che la sandbox non sia richiesta dall'amministratore. Ognuna indebolisce la sandbox, quindi impostala su false nelle impostazioni gestite se non vuoi che venga usata:

enableWeakerNestedSandbox
enableWeakerNetworkIsolation
network.allowAllUnixSockets
network.allowLocalBinding
allowAppleEvents, che un repository non può attivare

Imposta allowManagedReadPathsOnly su true nelle impostazioni gestite in modo che solo le voci allowRead dalle impostazioni gestite vengano rispettate. Questo impedisce agli sviluppatori di ampliare l'accesso in lettura oltre i percorsi approvati dall'organizzazione.

Per bloccare i domini di rete ai valori gestiti allo stesso modo, imposta allowManagedDomainsOnly. Con il blocco attivo, solo le impostazioni gestite possono impostare una porta proxy.

Quando le impostazioni gestite configurano sandbox.filesystem o elencano qualsiasi voce sandbox.credentials.files con "mode": "deny", solo le impostazioni gestite possono impostare filesystem.disabled, quindi gli sviluppatori non possono disattivare le restrizioni del filesystem distribuite dall'amministratore. Una voce mask valida non blocca la chiave. Vedi Quali impostazioni possono disabilitarla.

Impostazioni del repository con una sandbox richiesta dall'amministratore

La sandbox è richiesta dall'amministratore mentre è in vigore una di queste impostazioni:

allowUnsandboxedCommands impostato su false nelle impostazioni gestite, oppure con il flag --settings a meno che le impostazioni gestite non lo impostino su true
allowManagedDomainsOnly impostato su true nelle impostazioni gestite

Queste impostazioni non attivano la sandbox, quindi imposta anche enabled.

Mentre la sandbox è richiesta dall'amministratore, Claude Code accetta le impostazioni che la allentano solo dalle impostazioni gestite, dal flag --settings e dal ~/.claude/settings.json di ciascuno sviluppatore. Ignora queste impostazioni nei file .claude/settings.json e .claude/settings.local.json di un repository:

Impostazione del repository	Cosa ignora Claude Code
`excludedCommands`, `ignoreViolations`, `network.allowedDomains`, `network.allowUnixSockets`, `network.allowMachLookup`, `network.httpProxyPort`, `network.socksProxyPort`	Ogni voce
`filesystem.allowWrite`, regole di autorizzazione `Edit(...)`, `permissions.additionalDirectories`	L'accesso in scrittura che ogni voce concede ai comandi sandboxati. Gli strumenti per i file di Claude seguono comunque le regole `Edit(...)` e le directory aggiuntive
Regole di autorizzazione `WebFetch(domain:...)`	L'host che ogni regola aggiunge all'allowlist della sandbox. Lo strumento WebFetch segue comunque la regola
`enableWeakerNestedSandbox`, `enableWeakerNetworkIsolation`, `network.allowAllUnixSockets`, `network.allowLocalBinding`	`true`. Un `false` si applica comunque
`enabled`, `failIfUnavailable`	`false`, quando il `~/.claude/settings.json` dello sviluppatore imposta `true`
`filesystem.allowRead`	Una voce in corrispondenza o al di sotto di un percorso la cui lettura è negata dalle impostazioni gestite, da `--settings` o dalle impostazioni utente, oppure un glob che potrebbe corrispondere a uno di essi

Queste impostazioni si applicano comunque mentre la sandbox è richiesta dall'amministratore:

Nei file di un repository: le voci di negazione e il valore di autoAllowBashIfSandboxed. Imposta la chiave nelle impostazioni gestite per impedire a un repository di modificarla
Nelle impostazioni dello sviluppatore: le impostazioni nella tabella si applicano comunque da ~/.claude/settings.json o --settings, a meno che non siano coperte da un blocco solo gestito come allowManagedDomainsOnly. La maggior parte di esse, come excludedCommands e filesystem.allowWrite, non ha un blocco solo gestito

La configurazione in Applica il sandboxing con le impostazioni gestite rende la sandbox richiesta dall'amministratore. Aggiungi alle impostazioni gestite le voci excludedCommands, allowWrite e di socket di cui hanno bisogno i tuoi strumenti approvati, perché un repository non può fornirle.

Richiede Claude Code v2.1.285 o successivo. Dalla v2.1.282 alla v2.1.284, le stesse impostazioni facevano sì che Claude Code ignorasse le voci excludedCommands di un repository.

Blocchi che si applicano senza una sandbox richiesta dall'amministratore

Alcune impostazioni fanno sì che Claude Code ignori le chiavi del repository che sovrascrivono direttamente una restrizione, anche quando la sandbox non è richiesta dall'amministratore. Ognuna ha questo effetto solo quando la imposti in un file indicato nella sua riga, e le altre impostazioni sandbox del repository si applicano comunque. Richiede Claude Code v2.1.285 o successivo.

Impostazione	Dove la imposti	Cosa ignora Claude Code nelle impostazioni di un repository
`network.deniedDomains` o una regola di negazione `WebFetch(domain:...)`	Impostazioni gestite, `--settings`	`httpProxyPort` e `socksProxyPort`
`network.strictAllowlist`	Impostazioni gestite, `--settings`, impostazioni utente	Le porte proxy, `allowedDomains` e le regole di autorizzazione `WebFetch(domain:...)`
`filesystem.denyRead`, una regola di negazione `Read(...)` o una voce `credentials.files`	Impostazioni gestite, `--settings`	Una voce `allowRead`, `allowWrite`, di autorizzazione `Edit(...)` o `additionalDirectories` in corrispondenza o al di sotto di un percorso la cui lettura è negata dalle impostazioni gestite, da `--settings` o dalle impostazioni utente, oppure un glob che potrebbe corrispondere a uno di essi

Questi blocchi cambiano ciò che i comandi sandboxati possono raggiungere. Lo strumento WebFetch e gli strumenti per i file di Claude seguono comunque le regole e le directory aggiuntive di un repository.

Configurazione proxy personalizzata

Per ispezionare, filtrare o registrare il traffico della sandbox con i tuoi strumenti, sostituisci il proxy sandbox integrato con un proxy che esegui sulla stessa macchina.

Per instradare il traffico della sandbox attraverso un proxy aziendale altrove nella tua rete, imposta invece HTTPS_PROXY, come descritto dalla voce Proxy aziendale in Isolamento di rete. In questo modo, l'allowlist di Claude Code si applica comunque.

Per indirizzare i comandi sandboxati al tuo proxy, imposta le porte localhost su cui è in ascolto nelle impostazioni sandbox:

{
  "sandbox": {
    "network": {
      "httpProxyPort": 8080,
      "socksProxyPort": 8081
    }
  }
}

Se imposti una porta e imposti anche HTTPS_PROXY o HTTP_PROXY, Claude Code non inoltra ciò che i comandi sandboxati inviano al tuo proxy al proxy indicato da quelle variabili. Per raggiungere un proxy aziendale, configura il tuo proxy in modo che inoltri a esso.

Quali file possono impostare una porta dipende dalle tue altre impostazioni sandbox. Si applica il primo caso corrispondente:

allowManagedDomainsOnly è attivo: solo le impostazioni gestite
La sandbox è richiesta dall'amministratore, oppure si applica un blocco di rete più ristretto: impostazioni gestite, --settings e impostazioni utente
Altrimenti: qualsiasi file di impostazioni

Claude Code ignora una porta impostata altrove. Prima della v2.1.285, qualsiasi file di impostazioni poteva impostare una porta.

Risoluzione dei problemi

Alcuni comandi falliscono all'interno della sandbox anche se funzionano al di fuori di essa. Trova l'intestazione che corrisponde al tuo sintomo o messaggio di errore.

Se la sandbox della tua organizzazione è obbligatoria per l'amministratore, Claude Code ignora le impostazioni indicate da queste correzioni nei file di impostazioni di un progetto, quindi salvale in ~/.claude/settings.json, dove si applicano in ogni progetto. Se una correzione continua a non avere effetto, le impostazioni gestite della tua organizzazione potrebbero impostare quella chiave.

Una correzione che aggiunge un pattern a excludedCommands rimuove la sandbox dai comandi a cui corrisponde il pattern. Consulta cosa può fare un comando escluso.

I comandi falliscono con un errore host-not-allowed

Molti strumenti CLI devono raggiungere host specifici. Approva l'host quando ti viene chiesto, oppure aggiungilo a allowedDomains. Se la tua organizzazione blocca l'allowlist con allowManagedDomainsOnly, non viene mostrata alcuna richiesta, quindi chiedi al tuo amministratore di aggiungere l'host.

`jest` si blocca o fallisce

watchman è incompatibile con la sandbox. Esegui invece jest --no-watchman.

I CLI basati su Go falliscono la verifica TLS su macOS

Strumenti come gh, gcloud e terraform potrebbero fallire la verifica TLS sotto Seatbelt. Per eseguire questi strumenti al di fuori della sandbox, aggiungi un pattern per ciascuno strumento, come gh *, a excludedCommands. Lo strumento viene quindi eseguito con il tuo accesso completo e con le sue credenziali memorizzate. Se stai utilizzando httpProxyPort con un proxy MITM e una CA personalizzata, imposta invece enableWeakerNetworkIsolation su true.

`open`, `osascript` o i flussi di autenticazione basati su browser falliscono con errore `-600` su macOS

La sandbox blocca gli Apple Events per impostazione predefinita. Imposta allowAppleEvents su true nelle impostazioni utente, gestite o CLI per consentirli. Claude Code ignora questa chiave nelle impostazioni del progetto.

L'abilitazione di allowAppleEvents rimuove l'isolamento dell'esecuzione del codice, poiché i comandi sandboxati possono quindi avviare altre applicazioni non sandboxate senza alcuna richiesta all'utente e inviare comandi AppleScript alle applicazioni in esecuzione, soggetti alla richiesta di consenso per l'automazione di macOS (TCC). In alternativa, aggiungi un pattern come open * a excludedCommands. Ogni chiamata a open passa quindi attraverso il flusso dei permessi, e open può avviare qualsiasi file o app, inclusi quelli scritti da Claude.

I comandi `docker` falliscono

docker è incompatibile con la sandbox. Togli dalla sandbox i comandi docker di cui hai bisogno con un pattern in excludedCommands come docker compose *. Eseguire comandi al di fuori della sandbox con excludedCommands spiega cosa può raggiungere un comando docker escluso. Un pattern più ristretto toglie meno comandi dalla sandbox.

`pbcopy`, `xclip` o `wl-copy` non aggiorna gli appunti

Le utilità degli appunti pbcopy, xclip e wl-copy possono non riuscire a raggiungere gli appunti di sistema dall'interno della sandbox, nel qual caso il testo inviato loro tramite pipe non arriva.

Per mettere l'output di Claude negli appunti, chiedi a Claude di stamparlo nella sua risposta, quindi esegui /copy. /copy scrive negli appunti dal processo di Claude Code anziché da un comando sandboxato.

Quando Claude invia testo tramite pipe a uno di questi strumenti, aggiungere lo strumento a excludedCommands non toglie di per sé quella chiamata dalla sandbox.

Un comando git fallisce con `unable to unlink old`

git merge, git checkout e comandi simili falliscono con unable to unlink old quando devono sostituire un file su cui la sandbox nega la scrittura. Su Linux e WSL2 l'errore termina con Read-only file system. Il file può trovarsi in uno di questi punti:

Sotto un percorso protetto come .claude/skills
Sotto una delle tue voci denyWrite
Del tutto al di fuori delle directory in cui la sandbox consente ai comandi di scrivere

Dopo il fallimento, Claude potrebbe offrirsi di rieseguire il comando al di fuori della sandbox. Approva quel nuovo tentativo, oppure esegui tu stesso il comando git in un altro terminale. Se hai impostato allowUnsandboxedCommands su false, Claude non può offrire il nuovo tentativo, quindi esegui tu stesso il comando.

Bubblewrap non riesce ad avviarsi all'interno di un container

In un container senza privilegi, bubblewrap non può montare un nuovo filesystem /proc, quindi i comandi sandboxati falliscono con un errore bwrap come Can't mount proc on /newroot/proc: Operation not permitted. Imposta enableWeakerNestedSandbox su true in modo che la sandbox esegua invece il bind-mount del /proc esistente del container. Utilizza questa impostazione solo quando il container esterno fornisce già il confine di isolamento di cui hai bisogno, poiché l'impostazione espone ai comandi sandboxati informazioni sui processi che un nuovo mount di /proc nasconderebbe.

Compaiono file di sola lettura da 0 byte nei percorsi delle impostazioni `.claude`, e "Sì, e non chiedere più" non salva

Su Linux e WSL2, la sandbox mantiene un divieto di scrittura su un file che non esiste ancora creando in quel punto un placeholder di sola lettura da 0 byte mentre viene eseguito un comando sandboxato. La sandbox rimuove il placeholder in seguito. Se una sessione viene terminata prima che venga eseguita quella pulizia, ad esempio da SIGKILL, i placeholder rimangono. Le sessioni successive eseguono di nuovo il bind dei placeholder in sola lettura a ogni avvio, quindi una scrittura delle impostazioni, come il salvataggio di una scelta di permesso, fallisce in un percorso in cui rimane un placeholder.

Esegui claude doctor nel tuo terminale per elencare i file placeholder rimasti. L'avviso Stale sandbox mask files left by a killed session ne indica alcuni e conta i restanti. Elimina ciascun file con rm mentre nessun'altra sessione di Claude Code è in esecuzione in quel progetto. Prima della v2.1.257, Claude Code lasciava gli stessi placeholder senza segnalarli.

`git` su SSH fallisce con la sandbox attiva

Su macOS, git fetch, git pull e git push verso un remote SSH falliscono all'interno della sandbox anche quando l'host è consentito. Su Linux e WSL2, funzionano una volta consentito l'host. Claude Code incanala la connessione SSH di git attraverso il proxy della sandbox, e il tunnel di macOS non riesce ad autenticarsi con quel proxy.

Su Linux e WSL2, se la connessione continua a fallire, verifica quanto segue:

L'host è consentito sulla porta 22: una voce di allowedDomains senza porta, come "git.example.com", la copre
Il tuo proxy aziendale consente la porta 22: se la tua rete richiede un proxy upstream, anche il tunnel passa attraverso di esso
La chiave è leggibile come file: la sandbox può bloccare il socket di ssh-agent, e una voce denyRead o credentials per ~/.ssh nasconde i tuoi file di chiave

Su macOS, passa il remote a HTTPS, che richiede credenziali HTTPS come un personal access token:

git remote set-url origin https://git.example.com/example-org/example-repo.git

Se devi mantenere il remote SSH, togli i comandi di rete di git dalla sandbox con excludedCommands:

{
  "sandbox": {
    "excludedCommands": ["git fetch *", "git pull *", "git push *"]
  }
}

Queste voci corrispondono a git push origin main. Una chiamata che aggiunge un cd, usa git -C o contiene una sostituzione di comando resta nella sandbox. I comandi git esclusi possono raggiungere qualsiasi host, non solo quelli in allowedDomains.

I semplici ssh, scp e rsync su SSH falliscono per il motivo indicato nella voce sui client di database.

Un client di database o un altro strumento non HTTP non riesce a raggiungere un host consentito

Uno strumento che ignora le variabili d'ambiente del proxy non può connettersi dall'interno della sandbox, nemmeno a un host presente in allowedDomains. Un comando sandboxato non ha alcun percorso diretto verso la rete, quindi uno strumento che apre una propria connessione fallisce. La maggior parte dei driver di database, il semplice ssh e gli strumenti che usano UDP si comportano in questo modo.

Il fallimento si presenta come un errore di rete o di risoluzione dei nomi:

macOS: Operation not permitted, oppure un errore di risoluzione dei nomi come Could not resolve host
Linux e WSL2: Network is unreachable, oppure un errore di risoluzione dei nomi come Temporary failure in name resolution

Uno strumento che usa il proxy fallisce in modo diverso quando il suo host non è consentito. Ricevi una richiesta di rete, oppure lo strumento riceve una risposta 403 dal proxy.

Per consentire allo strumento di connettersi, esegui il comando che ne ha bisogno al di fuori della sandbox con excludedCommands. Questo esempio esclude uno script e aggiunge una regola ask in modo che tu approvi ogni esecuzione:

{
  "sandbox": {
    "excludedCommands": ["python scripts/load_orders.py *"]
  },
  "permissions": {
    "ask": ["Bash(python scripts/load_orders.py *)"]
  }
}

Lo script viene eseguito con il tuo accesso completo, e Claude può modificare uno script che si trova all'interno della tua directory di lavoro, quindi esaminalo quando compare la richiesta.

Un comando non riesce a raggiungere un server su localhost

Per impostazione predefinita, un comando sandboxato non può connettersi direttamente a un server in esecuzione sulla tua macchina al di fuori della sandbox, come un server di sviluppo o un database in un container. Cosa puoi modificare dipende dalla tua piattaforma:

macOS: imposta network.allowLocalBinding su true. I comandi sandboxati possono quindi restare in ascolto su porte di rete e connettersi a qualsiasi porta su localhost, il che include ogni altro servizio in ascolto lì. Un servizio su localhost che non richiede autenticazione, come un debugger, può quindi agire per conto del comando al di fuori della sandbox, e un comando in ascolto su un indirizzo non di loopback accetta connessioni da altre macchine
Linux e WSL2: il localhost di un comando sandboxato è privato per quel comando. Il comando può restare in ascolto su una porta e raggiungere i server che ha avviato esso stesso. Una connessione diretta a localhost o 127.0.0.1 non raggiunge i server sull'host, e allowLocalBinding non ha effetto. Esegui il comando che ha bisogno del server dell'host al di fuori della sandbox con excludedCommands, dove non ha limiti di filesystem o di rete. Per le connessioni che passano attraverso il proxy della sandbox, consulta Hostname che si risolvono in indirizzi locali

Questo esempio attiva l'impostazione per macOS:

{
  "sandbox": {
    "network": {
      "allowLocalBinding": true
    }
  }
}

Una voce di allowedDomains per localhost si applica alle connessioni che passano attraverso il proxy, quindi non modifica una connessione diretta. Claude Code imposta NO_PROXY per i comandi sandboxati in modo che si connettano a localhost direttamente anziché tramite il proxy. La voce espone inoltre ogni porta del localhost della tua macchina a un comando che usa il proxy. Per un hostname di sviluppo che punta a 127.0.0.1, consulta Un hostname consentito viene rifiutato con resolved to a loopback address.

Un hostname consentito viene rifiutato con `resolved to a loopback address`

Il proxy della sandbox rifiuta un hostname consentito che si risolve in un indirizzo locale, il che riguarda nomi di sviluppo come myapp.test che puntano a 127.0.0.1. Il comando riceve una risposta 403 il cui corpo indica il tipo di indirizzo, ad esempio Connection to myapp.test blocked: resolved to a loopback address.

Aggiungi l'indirizzo IP in cui si risolve il nome accanto all'hostname in allowedDomains, ciascuno con la porta su cui è in ascolto il tuo server:

{
  "sandbox": {
    "network": {
      "allowedDomains": ["myapp.test:3000", "127.0.0.1:3000"]
    }
  }
}

Una voce di indirizzo IP senza porta consente ai comandi sandboxati di raggiungere ogni servizio in ascolto su quell'indirizzo.

Prima della v2.1.284, il proxy si connetteva a qualsiasi indirizzo in cui si risolvesse un hostname consentito.

`/sandbox` fallisce con `Sandbox settings are overridden by a higher-priority configuration`

/sandbox stampa Error: Sandbox settings are overridden by a higher-priority configuration and cannot be changed locally. invece di aprire il suo pannello quando un livello di impostazioni superiore imposta sandbox.enabled, sandbox.autoAllowBashIfSandboxed o sandbox.allowUnsandboxedCommands. Il pannello salva le tue scelte in .claude/settings.local.json, e un valore salvato lì non può sovrascrivere quei livelli.

Le impostazioni gestite e --settings hanno priorità superiore rispetto alle impostazioni locali. Per vedere quali di esse sono state caricate in questa sessione, esegui /status e leggi la riga Setting sources:

Command line arguments: se hai avviato Claude Code con --settings, verifica se il file o il JSON che hai passato imposta una di quelle chiavi. In tal caso, modifica il valore lì, oppure avvia di nuovo Claude Code senza quelle chiavi.
Enterprise managed settings: sono caricate le impostazioni gestite della tua organizzazione. Se impostano una di quelle chiavi, non puoi modificare quella chiave da /sandbox né da alcun file di impostazioni sotto il tuo controllo, quindi rivolgiti al tuo amministratore.

Limitazioni

Il sandboxing riduce il rischio ma non è un confine di isolamento completo. Rivedi le limitazioni seguenti prima di fare affidamento su di esso come controllo di sicurezza rigido.

Limitazioni di sicurezza

Filtraggio della rete: la sandbox limita i domini a cui i processi possono connettersi. Per impostazione predefinita il proxy integrato non termina o ispeziona TLS sul traffico in uscita, quindi i contenuti delle connessioni crittografate non vengono esaminati. L'impostazione sperimentale network.tlsTerminate termina TLS al proxy per la sostituzione delle credenziali mask ma non aggiunge filtraggio dei contenuti. Sei responsabile di assicurarti che solo i domini affidabili siano consentiti nella tua politica.

Escalation dei privilegi tramite socket Unix: la configurazione allowUnixSockets può inavvertitamente concedere l'accesso a servizi di sistema che potrebbero portare a bypass della sandbox. Ad esempio, consentire l'accesso a /var/run/docker.sock concede effettivamente l'accesso al sistema host attraverso il socket Docker. Considera attentamente qualsiasi socket Unix che consenti attraverso la sandbox.
Escalation dei permessi del filesystem: i permessi di scrittura del filesystem eccessivamente ampi possono abilitare attacchi di escalation dei privilegi. Consentire scritture a directory contenenti eseguibili in $PATH, directory di configurazione di sistema o file di configurazione della shell dell'utente come .bashrc o .zshrc può portare all'esecuzione di codice in diversi contesti di sicurezza quando altri utenti o processi di sistema accedono a questi file.
Forza della sandbox Linux: l'implementazione Linux fornisce un forte isolamento del filesystem e della rete ma include una modalità enableWeakerNestedSandbox che le consente di funzionare all'interno di ambienti Docker senza namespace privilegiati. Questa opzione indebolisce considerevolmente la sicurezza e dovrebbe essere utilizzata solo quando l'isolamento aggiuntivo è altrimenti applicato.
Apple Events su macOS: la sandbox macOS blocca gli Apple Events per impostazione predefinita. L'impostazione allowAppleEvents rimuove questa restrizione in modo che strumenti come open e osascript funzionino, ma rimuove l'isolamento dell'esecuzione del codice: i comandi sandboxati possono avviare altre applicazioni senza sandbox senza alcun prompt dell'utente, e possono inviare comandi AppleScript alle applicazioni in esecuzione, soggetti al prompt di consenso per l'automazione macOS per app (TCC). È onorato solo dalle impostazioni utente, gestite o CLI. Le impostazioni del progetto non possono abilitarlo.

Ambito

La sandbox isola i comandi della shell e i loro processi figli. Cosa viene eseguito al di fuori della sandbox elenca gli strumenti e i processi ausiliari che non copre. L'utilizzo del computer e i subagent si rapportano alla sandbox come segue:

Utilizzo del computer: quando Claude apre app e controlla lo schermo, viene eseguito sul tuo desktop effettivo piuttosto che in un ambiente isolato. Le richieste di permesso per app controllano l'accesso a ogni applicazione. Vedi computer use nella CLI o computer use in Desktop.
Subagent: i subagent vengono eseguiti nello stesso processo della sessione padre e utilizzano la stessa configurazione sandbox. I comandi Bash all'interno di un subagent vengono sandboxati quando il sandboxing è abilitato nella sessione padre.
Mod: un mod è un plugin che esegue il proprio codice all'interno di Claude Code, e un processo avviato da un mod viene eseguito al di fuori della sandbox. Vedi Cosa può raggiungere un mod.

sandboxing.md +606 −307

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.3> Use this file to discover all available pages before exploring further.

4 4

~~5# Configura lo strumento Bash in sandbox~~5# Configurare lo strumento Bash in sandbox

6 6

~~7> Scopri come lo strumento Bash in sandbox di Claude Code fornisce isolamento del filesystem e della rete per un'esecuzione dell'agente più sicura e autonoma.~~7> Limita i file e gli host di rete che i comandi shell di Claude Code possono raggiungere con la sandbox integrata. Attivala, imposta il perimetro e risolvi ciò che interrompe.

8 8

9La sandbox Bash consente a Claude di eseguire la maggior parte dei comandi shell senza fermarsi per chiedere autorizzazione. Invece di approvare ogni comando, definisci quali file e domini di rete i comandi possono toccare, e il sistema operativo applica quel confine per ogni comando Bash, PowerShell o Monitor e i suoi processi figlio.9La sandbox di Bash è un perimetro che il sistema operativo applica attorno ai comandi shell che Claude esegue sulla tua macchina. Sei tu a stabilire quali file e domini di rete quei comandi possono raggiungere, e i limiti si applicano ai comandi Bash, PowerShell e Monitor e ai processi che avviano. Poiché è il sistema operativo ad applicare i limiti mentre un comando è in esecuzione, Claude Code può [eseguire i comandi in sandbox senza chiederti](#sandbox-modes) di approvarli uno per uno.

11La sandbox copre solo i comandi shell. Gli strumenti per i file di Claude, i server MCP e gli hook [vengono eseguiti al di fuori di essa](#what-runs-outside-the-sandbox).

13La sandbox funziona su macOS, Linux e WSL2. Su Windows nativo, Claude Code esegue i comandi senza sandbox. Per usare la sandbox su una macchina Windows, esegui Claude Code all'interno di una distribuzione WSL2.

10 14

11<Note>15<Note>

12 Per confrontare altri approcci di isolamento come dev container, container personalizzati e macchine virtuali, vedi [Ambienti sandbox](/docs/it/sandbox-environments). Per ridurre i prompt di autorizzazione per strumenti diversi da Bash, vedi [modalità di autorizzazione](/docs/it/permission-modes).16 Questa pagina tratta la sandbox attorno ai comandi shell sulla tua macchina. Altre pagine trattano argomenti correlati:

18 * Per scoprire come viene isolata una sessione cloud, consulta [Sicurezza e isolamento](/docs/it/claude-code-on-the-web#security-and-isolation)

19 * Per confrontare altri approcci di isolamento come dev container, container personalizzati e macchine virtuali, consulta [Ambienti sandbox](/docs/it/sandbox-environments)

20 * Per ridurre le richieste di permesso per strumenti diversi da Bash, consulta [modalità di permesso](/docs/it/permission-modes)

13</Note>21</Note>

14 22

23<h2 id="what-the-sandbox-restricts">

24 Cosa limita la sandbox

25</h2>

27Quando la sandbox è attiva, i comandi della shell eseguiti da Claude partono all'interno dei suoi confini, così come i processi che essi avviano. La sandbox è disattivata per impostazione predefinita. Per attivarla, esegui `/sandbox` in una sessione, come mostrato in [Iniziare](#get-started), oppure imposta [`sandbox.enabled`](/docs/it/settings-reference#sandbox-enabled) su `true` in un [file di impostazioni](/docs/it/settings) come `~/.claude/settings.json`.

29La tabella mostra cosa può raggiungere per impostazione predefinita un comando eseguito nella sandbox e le impostazioni che modificano ciascun valore predefinito.

31| Accesso | Predefinito | Modificalo con |

32| :- | :- | :- |

33| Scritture | La directory di lavoro, una directory temporanea per utente e le [directory che hai aggiunto](/docs/it/permissions#additional-directories-grant-file-access-not-configuration). I [percorsi protetti](#protected-paths) restano negati in scrittura | [`filesystem.allowWrite`](/docs/it/settings-reference#sandbox-filesystem-allowwrite), [`filesystem.denyWrite`](/docs/it/settings-reference#sandbox-filesystem-denywrite) |

34| Letture | La maggior parte della macchina, inclusi i file di credenziali come `~/.ssh` e `~/.aws/credentials` | [`filesystem.denyRead`](/docs/it/settings-reference#sandbox-filesystem-denyread), [`credentials`](#protect-credentials) |

35| Rete | Nessun percorso diretto verso l'esterno. Le connessioni passano attraverso un proxy sulla tua macchina che controlla ogni host rispetto ai tuoi domini consentiti, che inizialmente sono vuoti. La tua modalità di permesso decide [cosa succede agli altri host](#hosts-outside-your-allowed-domains) | [`network.allowedDomains`](/docs/it/settings-reference#sandbox-network-alloweddomains), [`network.deniedDomains`](/docs/it/settings-reference#sandbox-network-denieddomains) |

36| Variabili d'ambiente | Ereditate da Claude Code, inclusi eventuali segreti presenti nel suo ambiente | [`credentials`](#protect-credentials), [`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`](/docs/it/env-vars) |

38Claude Code crea la sandbox a partire dal pacchetto open source [`@anthropic-ai/sandbox-runtime`](https://github.com/anthropics/sandbox-runtime).

40<h3 id="what-runs-outside-the-sandbox">

41 Cosa viene eseguito al di fuori della sandbox

42</h3>

44La sandbox avvolge i comandi della shell. Questi strumenti e processi vengono eseguiti al di fuori di essa:

46* **Strumenti integrati per file e web**: strumenti come Read, Edit, Write, WebFetch e WebSearch seguono invece le [regole di permesso](/docs/it/permissions). Una voce `denyRead` non blocca lo strumento Read e `allowedDomains` non limita WebFetch

47* **Altri processi avviati da Claude Code**: gli [hook](/docs/it/hooks) di tipo comando, i [server MCP](/docs/it/mcp) locali, i [monitor dei plugin](/docs/it/plugins/components#monitors), i [server LSP](/docs/it/tools-reference#lsp-tool-behavior) e i comandi di supporto come il comando della tua [riga di stato](/docs/it/statusline) e `apiKeyHelper` vengono eseguiti con il tuo accesso completo

49Anche alcuni comandi della shell vengono eseguiti al di fuori della sandbox, a seconda delle tue impostazioni:

51* **Comandi che digiti tu stesso**: un comando che inserisci al [prompt della modalità shell `!`](/docs/it/interactive-mode#shell-mode-with-prefix) viene eseguito fuori dalla sandbox nella maggior parte delle sessioni. La [modalità sandbox rigorosa](#turn-off-the-retry-with-strict-sandbox-mode) elenca le sessioni in cui un comando che digiti viene eseguito nella sandbox

52* **Comandi esclusi**: i comandi che corrispondono a [`excludedCommands`](#run-commands-outside-the-sandbox-with-excludedcommands) vengono eseguiti fuori dalla sandbox

53* **Nuovi tentativi fuori dalla sandbox**: Claude può [chiedere di eseguire un comando fuori dalla sandbox](#the-unsandboxed-retry-escape-hatch), di solito dopo che non è riuscito nella sandbox

55Per porre gli strumenti, i processi e i comandi di questa sezione dietro un unico confine, esegui il processo stesso di Claude Code in un [container, una macchina virtuale o il runtime della sandbox](/docs/it/sandbox-environments).

15<h2 id="get-started">57<h2 id="get-started">

~~16 Get started~~58 Inizia

17</h2>59</h2>

18 60

~~19La sandbox è integrata in Claude Code e viene eseguita su macOS, Linux e WSL2. Windows nativo non è supportato. Su Windows, esegui Claude Code all'interno di una distribuzione WSL2.~~61La sandbox è integrata in Claude Code. Cosa installare dipende dalla tua piattaforma:

20 62

21Su macOS, non c'è nulla da installare: il sandboxing utilizza il framework Seatbelt integrato. Su Linux e WSL2, la sandbox si basa su due pacchetti, trattati in [Set up Linux and WSL2](#set-up-linux-and-wsl2). Anche se non li hai ancora installati, puoi iniziare con `/sandbox`, perché il suo pannello mostra se manca qualcosa.63* **macOS**: il sandboxing usa il framework integrato Seatbelt, quindi puoi passare direttamente ai passaggi

64* **Linux e WSL2**: la sandbox si basa su `bubblewrap` e `socat`, trattati in [Configurare Linux e WSL2](#set-up-linux-and-wsl2). Anche se non li hai ancora installati, puoi iniziare con `/sandbox`, perché il suo pannello mostra se manca qualcosa

22 65

23<Steps>66<Steps>

24 <Step title="Esegui /sandbox">67 <Step title="Esegui /sandbox">

28 /sandbox71 /sandbox

29 ```72 ```

30 73

~~31 Questo apre il pannello sandbox con tre schede, più una scheda Dependencies su Linux quando il filtro seccomp facoltativo è mancante:~~74 Si apre il pannello della sandbox con tre schede, più una scheda Dependencies su Linux quando manca il filtro seccomp opzionale:

32 75

~~33 * **Mode**: scegli come i comandi sandboxati vengono approvati, trattato nel passaggio successivo~~76 * **Mode**: scegli come vengono approvati i comandi in sandbox, argomento del passaggio successivo

34 * **Overrides**: scegli se i comandi che falliscono sotto la sandbox possono ricadere nell'esecuzione non sandboxata. Questa è l'impostazione [`allowUnsandboxedCommands`](/docs/it/settings-reference#sandbox-allowunsandboxedcommands)77 * **Overrides**: scegli se i comandi che falliscono nella sandbox possono ripiegare sull'esecuzione fuori dalla sandbox. Questa è l'impostazione [`allowUnsandboxedCommands`](/docs/it/settings-reference#sandbox-allowunsandboxedcommands)

~~35 * **Config**: visualizza le impostazioni sandbox risolte~~78 * **Config**: visualizza le impostazioni della sandbox risolte

36 79

37 Se il pannello mostra solo una scheda Dependencies, manca un pacchetto richiesto. Installalo come descritto in [Set up Linux and WSL2](#set-up-linux-and-wsl2), riavvia Claude Code ed esegui `/sandbox` di nuovo.80 Se il pannello mostra solo una scheda Dependencies, manca un pacchetto richiesto. Installalo come descritto in [Configurare Linux e WSL2](#set-up-linux-and-wsl2), riavvia Claude Code ed esegui di nuovo `/sandbox`.

38 </Step>81 </Step>

39 82

40 <Step title="Scegli una modalità">83 <Step title="Scegli una modalità">

41 Nella scheda Mode, seleziona auto-allow o autorizzazioni regolari. Auto-allow esegue i comandi sandboxati senza richiedere, e le autorizzazioni regolari mantengono i prompt di autorizzazione regolari anche quando i comandi sono sandboxati. Vedi [Sandbox modes](#sandbox-modes) per quali comandi richiedono comunque prompt in modalità auto-allow.84 Nella scheda Mode, seleziona auto-allow o permessi regolari. Auto-allow esegue i comandi in sandbox senza chiedere, mentre i permessi regolari mantengono le normali richieste di permesso anche quando i comandi sono in sandbox. Consulta [Modalità della sandbox](#sandbox-modes) per sapere quali comandi richiedono ancora conferma in modalità auto-allow.

42 </Step>85 </Step>

43 86

44 <Step title="Esegui un comando Bash">87 <Step title="Esegui un comando Bash">

45 Chiedi a Claude di eseguire un comando, come una build o una suite di test. Per impostazione predefinita, i comandi all'interno della sandbox possono scrivere nella directory di lavoro, in una [directory temporanea per utente](/docs/it/env-vars), e in qualsiasi [directory che hai aggiunto](/docs/it/permissions#additional-directories-grant-file-access-not-configuration) con `--add-dir`, `/add-dir` o `permissions.additionalDirectories`.88 Chiedi a Claude di eseguire un comando, come una build o una suite di test. Per impostazione predefinita, i comandi all'interno della sandbox possono scrivere nella directory di lavoro, in una [directory temporanea per utente](/docs/it/env-vars) e in qualsiasi [directory che hai aggiunto](/docs/it/permissions#additional-directories-grant-file-access-not-configuration) con `--add-dir`, `/add-dir` o `permissions.additionalDirectories`.

46 89

47 La prima volta che un comando ha bisogno di un nuovo dominio di rete, Claude Code richiede l'approvazione; in [modalità auto](/docs/it/permission-modes#eliminate-prompts-with-auto-mode), Claude invece nomina gli host di cui un comando ha bisogno [sul comando stesso](#per-command-allowed-domains-in-auto-mode) affinché il classificatore li esamini insieme ad esso.90 La prima volta che un comando ha bisogno di un nuovo dominio di rete, Claude Code chiede l'approvazione; in [modalità auto](/docs/it/permission-modes#eliminate-prompts-with-auto-mode), Claude invece indica gli host di cui un comando ha bisogno [sul comando stesso](#per-command-allowed-domains-in-auto-mode), affinché il classificatore li esamini insieme al comando.

48 91

49 I comandi che non possono essere eseguiti sandboxati ricadono nel flusso di autorizzazione regolare. Claude Code intitola il loro prompt di autorizzazione "Bash command (unsandboxed)" invece di "Bash command", così puoi dire quali comandi sono stati eseguiti al di fuori della sandbox. Per ampliare o restringere ciò che la sandbox consente, vedi [Configure sandboxing](#configure-sandboxing).92 Per ampliare o restringere ciò che la sandbox consente, consulta [Configurare il sandboxing](#configure-sandboxing).

50 93

~~51 Se i comandi sandboxati falliscono con `Operation not permitted` all'interno di un contenitore, vedi la voce Bubblewrap sotto [Troubleshooting](#troubleshooting).~~94 Se i comandi in sandbox falliscono con `Operation not permitted` all'interno di un container, consulta [Bubblewrap non si avvia all'interno di un container](#bubblewrap-fails-to-start-inside-a-container).

52 </Step>95 </Step>

53</Steps>96</Steps>

54 97

55Quando selezioni una modalità nel pannello, Claude Code la salva nelle impostazioni locali del tuo progetto in `.claude/settings.local.json`, che si applicano al progetto corrente. Claude Code aggiunge quel file al tuo gitignore globale quando salva un'impostazione lì. Per abilitare la sandbox in tutti i tuoi progetti, imposta [`sandbox.enabled`](/docs/it/settings-reference#sandbox-enabled) su `true` nelle impostazioni utente in `~/.claude/settings.json`. Per applicare il sandboxing per ogni sviluppatore in un'organizzazione, utilizza [impostazioni gestite](#enforce-sandboxing-with-managed-settings).98Quando selezioni una modalità nel pannello, Claude Code la salva nelle impostazioni locali del tuo progetto in `.claude/settings.local.json`, che si applicano al progetto corrente. Claude Code aggiunge quel file al tuo gitignore globale quando vi salva un'impostazione. Per abilitare la sandbox in tutti i tuoi progetti, imposta [`sandbox.enabled`](/docs/it/settings-reference#sandbox-enabled) su `true` nelle tue impostazioni utente in `~/.claude/settings.json`. Per imporre il sandboxing a ogni sviluppatore di un'organizzazione, usa le [impostazioni gestite](#enforce-sandboxing-with-managed-settings).

56 99

57Per modificare la sandbox per una sessione senza scrivere in un file di impostazioni, avvia Claude Code con [`--settings`](/docs/it/settings#change-a-setting-for-one-session). Ad esempio, questo comando avvia una sessione sandboxata in cui Claude non può riprovare un comando bloccato al di fuori della sandbox:100Per modificare la sandbox per una sola sessione senza scrivere in un file di impostazioni, avvia Claude Code con [`--settings`](/docs/it/settings#change-a-setting-for-one-session). Ad esempio, questo comando avvia una sessione in sandbox in cui Claude non può riprovare un comando bloccato fuori dalla sandbox:

58 101

59```bash theme={null}102```bash theme={null}

60claude --settings '{"sandbox": {"enabled": true, "allowUnsandboxedCommands": false}}'103claude --settings '{"sandbox": {"enabled": true, "allowUnsandboxedCommands": false}}'

61```104```

62 105

63<Warning>106<Warning>

64 Per impostazione predefinita, se la sandbox non può avviarsi perché mancano dipendenze o la piattaforma non è supportata, Claude Code mostra un avviso ed esegue i comandi senza sandboxing. Per rendere questo un errore grave, imposta [`sandbox.failIfUnavailable`](/docs/it/settings-reference#sandbox-failifunavailable) su `true`. Questo è destinato a distribuzioni gestite che richiedono il sandboxing come gate di sicurezza.107 Per impostazione predefinita, se la sandbox non può avviarsi perché manca una dipendenza o la piattaforma non è supportata, Claude Code esegue i comandi senza sandboxing. Per far sì che Claude Code termini invece all'avvio, imposta [`sandbox.failIfUnavailable`](/docs/it/settings-reference#sandbox-failifunavailable) su `true`. Le distribuzioni gestite che richiedono il sandboxing come barriera di sicurezza possono usare questa impostazione.

65</Warning>108</Warning>

66 109

110<h3 id="confirm-commands-run-inside-the-sandbox">

111 Verificare che i comandi vengano eseguiti nella sandbox

112</h3>

113

114Per verificare che la sandbox funzioni, chiedi a Claude di eseguire ciascuna riga della tabella. Ciò che digiti nel [prompt `!`](#what-runs-outside-the-sandbox) di solito viene eseguito fuori dalla sandbox, quindi digitare tu stesso una riga non la mette alla prova.

115

116| Comando | Risultato all'interno della sandbox |

117| :- | :- |

118| `touch ~/sandbox-probe` | Fallisce con `Operation not permitted` su macOS, oppure `Read-only file system` su Linux e WSL2 |

119| `curl --noproxy '*' https://example.com` | Fallisce con `Could not resolve host`, perché il comando non ha alcun percorso che aggiri il proxy della sandbox |

120

121Se Claude chiede di riprovare un comando fallito fuori dalla sandbox, rifiuta il nuovo tentativo. Se `touch` riesce e la tua directory home non è una delle directory in cui la sandbox consente ai comandi di scrivere, elimina `~/sandbox-probe`. Poi esegui `/sandbox` per verificare che la sandbox sia attiva e che le sue dipendenze siano installate.

122

67<h3 id="set-up-linux-and-wsl2">123<h3 id="set-up-linux-and-wsl2">

~~68 Set up Linux and WSL2~~124 Configurare Linux e WSL2

69</h3>125</h3>

70 126

~~71Su Linux e WSL2, la sandbox si basa su due pacchetti:~~127Su Linux e WSL2, la sandbox si basa su questi pacchetti:

72 128

~~73* [`bubblewrap`](https://github.com/containers/bubblewrap): lo strumento di sandboxing senza privilegi che applica l'isolamento del filesystem~~129* [`bubblewrap`](https://github.com/containers/bubblewrap): lo strumento di sandboxing non privilegiato che applica l'isolamento del filesystem

~~74* [`socat`](http://www.dest-unreach.org/socat/): il relay utilizzato per instradare il traffico di rete attraverso il proxy sandbox~~130* [`socat`](http://www.dest-unreach.org/socat/): il relay usato per instradare il traffico di rete attraverso il proxy della sandbox

75 131

76Installali con il gestore di pacchetti della tua distribuzione:132Installali con il gestore di pacchetti della tua distribuzione:

77 133

89 </Tab>145 </Tab>

90</Tabs>146</Tabs>

91 147

92Quando una dipendenza è mancante, la scheda Dependencies in `/sandbox` elenca quale tra `ripgrep`, `bubblewrap`, `socat` e il filtro seccomp la tua piattaforma manca. Se non vedi la scheda dopo l'installazione e il riavvio di Claude Code, tutte le dipendenze sono presenti.148Quando manca una dipendenza, la scheda Dependencies in `/sandbox` elenca quali tra `ripgrep`, `bubblewrap`, `socat` e il filtro seccomp mancano alla tua piattaforma. Se non vedi la scheda dopo aver installato e riavviato Claude Code, tutte le dipendenze sono presenti.

93 149

94Ripgrep è incluso nel binario nativo di Claude Code. Il filtro seccomp è facoltativo e aggiunge il blocco del socket di dominio Unix. Installalo con `npm install -g @anthropic-ai/sandbox-runtime` se è mancante.150Ripgrep è incluso nel binario nativo di Claude Code. Il filtro seccomp è opzionale e aggiunge il blocco dei socket di dominio Unix. Se manca, installalo con `npm install -g @anthropic-ai/sandbox-runtime`.

95 151

96Quando una dipendenza richiesta è mancante, la scheda Dependencies è l'unica scheda mostrata fino a quando non la installi. Quando solo il filtro seccomp facoltativo è mancante, la scheda Dependencies appare insieme alle altre schede. Il controllo delle dipendenze viene eseguito all'avvio, quindi riavvia Claude Code dopo l'installazione dei pacchetti affinché `/sandbox` li rilevi.152Quando manca una dipendenza richiesta, la scheda Dependencies è l'unica mostrata finché non la installi. Quando manca solo il filtro seccomp opzionale, la scheda Dependencies appare insieme alle altre schede. Il controllo delle dipendenze viene eseguito all'avvio, quindi riavvia Claude Code dopo aver installato i pacchetti affinché `/sandbox` li rilevi.

97 153

98<AccordionGroup>154<AccordionGroup>

~~99 <Accordion title="Ubuntu 24.04 e versioni successive: consenti a bubblewrap di creare spazi dei nomi utente">~~155 <Accordion title="Ubuntu 24.04 e successivi: consentire a bubblewrap di creare user namespace">

100 Su Ubuntu 24.04 e versioni successive, la politica AppArmor predefinita impedisce a bubblewrap di creare gli spazi dei nomi utente di cui ha bisogno per l'isolamento.156 Su Ubuntu 24.04 e successivi, la policy AppArmor predefinita impedisce a bubblewrap di creare gli user namespace di cui ha bisogno per l'isolamento.

101 157

102 Per verificare se il tuo ambiente applica questa restrizione, incluso all'interno di WSL2, esegui `sysctl kernel.apparmor_restrict_unprivileged_userns`. Se il comando restituisce `0`, salta questo passaggio. Se stampa un errore `No such file or directory`, la chiave non esiste e puoi saltare questo passaggio. Se restituisce `1`, aggiungi un profilo AppArmor che conceda a `bwrap` questa capacità:158 Per verificare se il tuo ambiente applica questa restrizione, anche all'interno di WSL2, esegui `sysctl kernel.apparmor_restrict_unprivileged_userns`. Se il comando restituisce `0`, salta questo passaggio. Se stampa un errore `No such file or directory`, la chiave non esiste e puoi saltare questo passaggio. Se restituisce `1`, aggiungi un profilo AppArmor che conceda a `bwrap` questa capacità:

103 159

104 ```bash theme={null}160 ```bash theme={null}

105 sudo tee /etc/apparmor.d/bwrap > /dev/null <<'EOF'161 sudo tee /etc/apparmor.d/bwrap > /dev/null <<'EOF'

121 </Accordion>177 </Accordion>

122 178

123 <Accordion title="Note su WSL2">179 <Accordion title="Note su WSL2">

124 Controlla la tua versione WSL con `wsl -l -v` da PowerShell. Se vedi `Sandboxing requires WSL2`, la tua distribuzione sta eseguendo WSL1. Aggiornala a WSL2 o esegui Claude Code senza sandboxing.180 Controlla la tua versione di WSL con `wsl -l -v` da PowerShell. Se vedi `Sandboxing requires WSL2`, la tua distribuzione sta eseguendo WSL1. Aggiornala a WSL2 oppure esegui Claude Code senza sandboxing.

125 181

126 Su WSL2, WSL passa il lancio di un binario Windows come `cmd.exe`, `powershell.exe` o qualsiasi cosa sotto `/mnt/c/` all'host Windows su un socket Unix, quindi se un comando sandboxato può lanciarne uno segue le [impostazioni Unix-socket](/docs/it/settings-reference#sandbox-network-allowunixsockets) della sandbox: il filtro seccomp facoltativo deve essere installato per bloccare il socket in primo luogo. Per consentire questi lanci, imposta `allowAllUnixSockets`; per tenerli completamente fuori dalla sandbox, aggiungi il comando a [`excludedCommands`](/docs/it/settings-reference#sandbox-excludedcommands).182 Su WSL2, WSL passa l'avvio di un binario Windows come `cmd.exe`, `powershell.exe` o qualsiasi cosa in `/mnt/c/` all'host Windows tramite un socket Unix, quindi la possibilità che un comando in sandbox ne avvii uno dipende dalle [impostazioni dei socket Unix](/docs/it/settings-reference#sandbox-network-allowunixsockets) della sandbox: il filtro seccomp opzionale deve essere installato perché il socket venga bloccato. Per consentire questi avvii, imposta `allowAllUnixSockets`, che apre ogni socket Unix ai comandi in sandbox.

127 </Accordion>183 </Accordion>

128</AccordionGroup>184</AccordionGroup>

129 185

130<h3 id="sandbox-modes">186<h3 id="sandbox-modes">

131 Sandbox modes187 Modalità della sandbox

132</h3>188</h3>

133 189

134Claude Code offre due modalità sandbox. In entrambe, la sandbox applica le stesse restrizioni di filesystem e rete; la differenza è solo se i comandi sandboxati sono auto-approvati o richiedono autorizzazione esplicita.190Claude Code offre due modalità della sandbox. In entrambe, la sandbox applica le stesse restrizioni su filesystem e rete; la differenza sta solo nel fatto che i comandi in sandbox vengano approvati automaticamente o richiedano un permesso esplicito.

135 191

136<h4 id="auto-allow-mode">192<h4 id="auto-allow-mode">

137 Auto-allow mode193 Modalità auto-allow

138</h4>194</h4>

139 195

140Quando un comando può essere sandboxato, Claude Code lo esegue all'interno della sandbox e lo approva automaticamente, senza chiedere il tuo permesso. I comandi che non possono essere sandboxati, come quelli che necessitano di accesso alla rete a host non consentiti, ricadono nel flusso di autorizzazione regolare, dove Claude Code controlla le tue [regole di autorizzazione](/docs/it/permissions) e blocca qualsiasi comando che quelle regole non consentono già, con un prompt in modalità Manual.196Claude Code approva automaticamente un comando, senza chiedere, quando il comando viene eseguito all'interno della sandbox. Un comando segue il normale [flusso dei permessi](/docs/it/permissions) quando viene eseguito fuori dalla sandbox perché corrisponde a [`excludedCommands`](#run-commands-outside-the-sandbox-with-excludedcommands) o perché Claude [lo riprova fuori dalla sandbox](#the-unsandboxed-retry-escape-hatch).

197

198Un comando in sandbox che si connette a un host che non hai consentito resta nella sandbox. [Host al di fuori dei tuoi domini consentiti](#hosts-outside-your-allowed-domains) spiega chi decide se la connessione viene stabilita.

141 199

142Anche in modalità auto-allow, si applicano i seguenti:200Anche in modalità auto-allow, continuano ad applicarsi i seguenti punti:

143 201

144* Le [regole di negazione](/docs/it/permissions) esplicite sono sempre rispettate202* Le [regole di negazione](/docs/it/permissions) esplicite vengono sempre rispettate

145* I comandi `rm` o `rmdir` che puntano a un [percorso critico](/docs/it/permission-modes#critical-paths) passano comunque attraverso il flusso di autorizzazione regolare203* I comandi `rm` o `rmdir` che hanno come destinazione un [percorso critico](/docs/it/permission-modes#critical-paths) seguono comunque il normale flusso dei permessi

146* Le [regole ask](/docs/it/permissions) con ambito di contenuto come `Bash(git push *)` forzano comunque un prompt anche per i comandi sandboxati204* Le [regole ask](/docs/it/permissions) limitate a un contenuto, come `Bash(git push *)`, forzano comunque una richiesta di conferma anche per i comandi in sandbox

147* Una regola ask `Bash` semplice, o la forma equivalente `Bash(*)`, viene saltata per i comandi che vengono eseguiti sandboxati; si applica comunque ai comandi che ricadono nel flusso di autorizzazione regolare. In [plan mode](/docs/it/permission-modes#analyze-before-you-edit-with-plan-mode), la regola non viene saltata: richiede per i comandi sandboxati anche, inclusi quelli di sola lettura. Prima della v2.1.212, il salto si applicava anche in plan mode205* Una regola ask `Bash` semplice, o la forma equivalente `Bash(*)`, viene ignorata per i comandi eseguiti in sandbox; si applica comunque ai comandi che ricadono nel normale flusso dei permessi. Nel [plan mode](/docs/it/permission-modes#analyze-before-you-edit-with-plan-mode), la regola non viene ignorata: chiede conferma anche per i comandi in sandbox, compresi quelli di sola lettura

148 206

149<Info>207<Info>

150 La modalità auto-allow funziona indipendentemente dall'impostazione della modalità di autorizzazione, con tre eccezioni: [plan mode](/docs/it/permission-modes#analyze-before-you-edit-with-plan-mode), un comando in modalità auto che porta [domini consentiti per comando](#per-command-allowed-domains-in-auto-mode), e [revisione del classificatore lato server](/docs/it/permission-modes#how-the-classifier-evaluates-actions) dei comandi sandboxati in modalità auto. Anche se non sei in modalità "accetta modifiche", i comandi Bash sandboxati vengono eseguiti automaticamente quando auto-allow è abilitato. Ciò significa che i comandi Bash che modificano file entro i confini della sandbox vengono eseguiti senza richiedere, anche in modalità Manual, dove gli strumenti di modifica dei file richiederebbero.208 La modalità auto-allow funziona indipendentemente dall'impostazione della modalità di permesso, con tre eccezioni: il [plan mode](/docs/it/permission-modes#analyze-before-you-edit-with-plan-mode), un comando in modalità auto che include [domini consentiti per comando](#per-command-allowed-domains-in-auto-mode) e la [revisione lato server da parte del classificatore](/docs/it/permission-modes#how-the-classifier-evaluates-actions) dei comandi in sandbox in modalità auto. Anche se non sei in modalità "accept edits", i comandi Bash in sandbox vengono eseguiti automaticamente quando auto-allow è abilitato. Ciò significa che i comandi Bash che modificano file entro i confini della sandbox vengono eseguiti senza chiedere, anche in modalità Manual, in cui gli strumenti di modifica dei file chiederebbero conferma.

151 209

152 In plan mode, auto-allow non amplia le approvazioni; vedi [plan mode](/docs/it/permission-modes#analyze-before-you-edit-with-plan-mode) per come Claude Code blocca i comandi mentre pianifichi. Prima della v2.1.212, auto-allow eseguiva i comandi sandboxati senza un prompt in plan mode anche.210 Nel plan mode, auto-allow non amplia le approvazioni; consulta [plan mode](/docs/it/permission-modes#analyze-before-you-edit-with-plan-mode) per sapere come Claude Code controlla i comandi mentre pianifichi.

153</Info>211</Info>

154 212

155<h4 id="regular-permissions-mode">213<h4 id="regular-permissions-mode">

156 Regular permissions mode214 Modalità permessi regolari

157</h4>215</h4>

158 216

159Tutti i comandi Bash passano attraverso il flusso di autorizzazione regolare, anche quando sandboxati. Questo fornisce più controllo ma richiede più approvazioni.217Tutti i comandi Bash seguono il normale flusso dei permessi, anche quando sono in sandbox. Questo offre più controllo ma richiede più approvazioni.

160 218

161<h4 id="the-unsandboxed-retry-escape-hatch">219<h4 id="the-unsandboxed-retry-escape-hatch">

162 The unsandboxed retry escape hatch220 La via di fuga del nuovo tentativo fuori dalla sandbox

221</h4>

222

223Il nuovo tentativo fuori dalla sandbox è una via di fuga per i comandi che falliscono all'interno della sandbox, come gli strumenti incompatibili con essa. Quando la sandbox blocca una connessione di rete, Claude Code indica l'host negato nel risultato del comando, così Claude vede cosa è stato bloccato. Claude analizza l'errore e può riprovare il comando con il parametro `dangerouslyDisableSandbox`.

224

225Il comando riprovato viene eseguito fuori dalla sandbox. In una sessione interattiva nel terminale, chi lo approva dipende dalla tua modalità di permesso:

226

227* **Modalità `bypassPermissions`**: il nuovo tentativo viene eseguito senza richiesta di conferma

228* **Modalità Manual e modalità `acceptEdits`**: ricevi una richiesta di conferma intitolata "Bash command (unsandboxed)"

229* **[Modalità auto](/docs/it/permission-modes#eliminate-prompts-with-auto-mode)**: un modello classificatore separato valuta il comando sottostante

230* **Modalità `dontAsk`**: Claude Code nega il nuovo tentativo

231* **Plan mode**: consulta [come Claude Code controlla i comandi mentre pianifichi](/docs/it/permission-modes#analyze-before-you-edit-with-plan-mode)

232

233Queste regole e impostazioni cambiano chi approva il nuovo tentativo:

234

235* **Una regola allow corrispondente**: se una regola allow come `Bash(curl *)` corrisponde al comando, approva anche il nuovo tentativo, quindi il comando viene eseguito fuori dalla sandbox senza richiesta di conferma

236* **Una regola ask per il parametro**: aggiungi una [regola ask](/docs/it/permissions#match-by-input-parameter) per `Bash(dangerouslyDisableSandbox:true)` per ricevere una richiesta di conferma sui nuovi tentativi Bash. Ricevi la richiesta anche in modalità auto e in modalità `bypassPermissions`, e la regola ha la precedenza su una regola allow corrispondente

237* **[`permissions.blockReadsOutsideWorkingDirectories`](/docs/it/settings-reference#permissions-blockreadsoutsideworkingdirectories)**: [Azioni che nessuna modalità approva automaticamente](/docs/it/permission-modes#actions-no-mode-auto-approves) descrive i nuovi tentativi che chiedono conferma mentre è attiva

238

239<h4 id="turn-off-the-retry-with-strict-sandbox-mode">

240 Disattivare il nuovo tentativo con la modalità sandbox rigorosa

163</h4>241</h4>

164 242

165Alcuni comandi non possono essere eseguiti all'interno della sandbox, come strumenti incompatibili con essa o che necessitano di un host che non hai consentito. Claude Code segnala le violazioni della sandbox nel risultato del comando bloccato, nominando il percorso o l'host che la sandbox ha negato, così Claude vede cosa la sandbox ha bloccato. Piuttosto che fallire il compito o richiedere di disattivare il sandboxing, Claude Code include un escape hatch: Claude analizza la violazione e potrebbe riprovare il comando con il parametro `dangerouslyDisableSandbox`.243Puoi disabilitare il nuovo tentativo fuori dalla sandbox impostando `"allowUnsandboxedCommands": false` nelle tue [impostazioni della sandbox](/docs/it/settings-reference#sandbox-settings). Con il nuovo tentativo disabilitato, Claude Code ignora il parametro `dangerouslyDisableSandbox`. Mentre la sandbox è in esecuzione, i comandi eseguiti da Claude vengono quindi eseguiti in sandbox, a meno che non corrispondano a una voce di `excludedCommands`. Per impedire a Claude Code di eseguire comandi fuori dalla sandbox quando la sandbox non può avviarsi, imposta anche [`failIfUnavailable`](/docs/it/settings-reference#sandbox-failifunavailable). La scheda **Overrides** di `/sandbox` mostra questa impostazione come **Strict sandbox mode**.

166 244

167Il comando riprovato viene eseguito al di fuori della sandbox, quindi passa attraverso il flusso di autorizzazione regolare. In modalità Manual ottieni un prompt di conferma. In [modalità auto](/docs/it/permission-modes#eliminate-prompts-with-auto-mode), il classificatore valuta il comando sottostante. Mentre [`permissions.blockReadsOutsideWorkingDirectories`](/docs/it/settings-reference#permissions-blockreadsoutsideworkingdirectories) è attivo, una riprovazione che necessita di approvazione per essere eseguita al di fuori della sandbox ti richiede invece. Per essere richiesto su ogni riprovazione non sandboxata anche in modalità auto, aggiungi una [regola ask](/docs/it/permissions#match-by-input-parameter) per `Bash(dangerouslyDisableSandbox:true)`.245Un valore `false` nelle tue impostazioni utente, in `--settings` o nelle impostazioni gestite resta valido anche quando le impostazioni di un progetto impostano `true`. Un valore `false` nelle tue impostazioni utente non rende la sandbox richiesta dall'amministratore, quindi le altre impostazioni della sandbox di un progetto continuano ad applicarsi. Prima della v2.1.285, un `true` di un progetto sovrascriveva un `false` nelle tue impostazioni utente.

168 246

169Puoi disabilitare questo escape hatch impostando `"allowUnsandboxedCommands": false` nelle tue [impostazioni sandbox](/docs/it/settings-reference#sandbox-settings). Con l'escape hatch disabilitato, Claude Code ignora il parametro `dangerouslyDisableSandbox`, e ogni comando che Claude esegue deve essere eseguito sandboxato a meno che non lo abbia elencato in `excludedCommands`. La scheda **Overrides** di `/sandbox` mostra questa impostazione come **Strict sandbox mode**.247Se tu o il tuo amministratore disabilitate il nuovo tentativo nelle impostazioni gestite o con il flag `--settings`, la sandbox diventa richiesta dall'amministratore. Claude Code ignora quindi le impostazioni nei file di un repository che allentano la sandbox, comprese le voci di `excludedCommands`. [Impostazioni del repository con una sandbox richiesta dall'amministratore](#repository-settings-under-an-admin-required-sandbox) le elenca.

170 248

171La modalità strict sandbox si applica ai comandi che Claude esegue. I comandi che digiti tu stesso al prompt [shell-mode](/docs/it/interactive-mode#shell-mode-with-prefix) con il prefisso `!` vengono eseguiti al di fuori della sandbox a meno che la sessione non sia una di queste:249La modalità sandbox rigorosa si applica ai comandi eseguiti da Claude. I comandi che digiti tu stesso nel [prompt della modalità shell `!`](/docs/it/interactive-mode#shell-mode-with-prefix) vengono eseguiti fuori dalla sandbox, a meno che la sessione non sia una di queste:

172 250

173* **Una [sessione in background](/docs/it/agent-view)**: la modalità strict sandbox copre anche i comandi shell-mode251* **Una [sessione in background](/docs/it/agent-view)**: la modalità sandbox rigorosa copre anche i comandi in modalità shell

174* **Una sessione Linux con [`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`](/docs/it/env-vars#variables) impostato**: ogni comando viene eseguito sandboxato, inclusi i comandi shell-mode252* **Una sessione Linux con [`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`](/docs/it/env-vars#variables) impostata**: ogni comando viene eseguito in sandbox, compresi i comandi in modalità shell

175 253

176Prima della v2.1.260, la modalità strict sandbox sandboxava i comandi shell-mode in ogni sessione.254Prima della v2.1.260, la modalità sandbox rigorosa eseguiva in sandbox i comandi in modalità shell in ogni sessione.

177 255

178<h4 id="temporary-directories">256<h4 id="temporary-directories">

179 Temporary directories257 Directory temporanee

180</h4>258</h4>

181 259

182La directory temporanea della sessione è scrivibile all'interno della sandbox per impostazione predefinita, insieme alla directory di lavoro. A meno che tu non [disabiliti l'isolamento del filesystem](#disable-filesystem-isolation), Claude Code imposta `$TMPDIR` su questa directory per i comandi sandboxati, così gli strumenti che scrivono file temporanei funzionano senza configurazione aggiuntiva.260Per impostazione predefinita, una directory temporanea per utente è scrivibile all'interno della sandbox, insieme alla directory di lavoro. A meno che tu non [disabiliti l'isolamento del filesystem](#disable-filesystem-isolation), Claude Code imposta `$TMPDIR` su questa directory per i comandi in sandbox, così gli strumenti che scrivono file temporanei funzionano senza configurazione aggiuntiva.

183 261

184I comandi non sandboxati ereditano il tuo `$TMPDIR` della shell quando è impostato, quindi mentre l'isolamento del filesystem è attivo, i comandi sandboxati e non sandboxati risolvono `$TMPDIR` in directory diverse. Se la tua shell lascia `$TMPDIR` non impostato o vuoto, un comando non sandboxato che fa riferimento a `$TMPDIR` riceve il tuo override [`CLAUDE_CODE_TMPDIR`](/docs/it/env-vars), o la directory temporanea del sistema operativo quando non ne hai impostato uno o l'override è un percorso lungo, così la variabile non si espande a una stringa vuota. Per passare file temporanei tra i due, scrivili nella directory di lavoro invece.262I comandi fuori dalla sandbox ereditano il `$TMPDIR` della tua shell quando è impostato, quindi mentre l'isolamento del filesystem è attivo, i comandi in sandbox e quelli fuori dalla sandbox risolvono `$TMPDIR` in directory diverse. Se la tua shell lascia `$TMPDIR` non impostato o vuoto, un comando fuori dalla sandbox che fa riferimento a `$TMPDIR` riceve il tuo override [`CLAUDE_CODE_TMPDIR`](/docs/it/env-vars), oppure la directory temporanea del sistema operativo quando non ne hai impostato uno o l'override è un percorso lungo, così la variabile non si espande in una stringa vuota. Per passare file temporanei tra i due, scrivili invece nella directory di lavoro.

185 263

186<h2 id="configure-sandboxing">264<h2 id="configure-sandboxing">

187 Configura il sandboxing265 Configurare il sandboxing

188</h2>266</h2>

189 267

190Personalizza il comportamento della sandbox attraverso il tuo file `settings.json`. Vedi [Settings](/docs/it/settings-reference#sandbox-settings) per il riferimento di configurazione completo.268Personalizza il comportamento della sandbox tramite il file `settings.json`. Consulta [Impostazioni](/docs/it/settings-reference#sandbox-settings) per il riferimento completo della configurazione.

191 269

192Per impostazione predefinita, i comandi in sandbox possono scrivere nella directory di lavoro corrente, nella directory temporanea della sessione e in qualsiasi [directory che hai aggiunto](/docs/it/permissions#additional-directories-grant-file-access-not-configuration) con `--add-dir`, `/add-dir` o `permissions.additionalDirectories`. Se i comandi dei sottoprocessi come `kubectl`, `terraform` o `npm` devono scrivere al di fuori di quelle directory, usa `sandbox.filesystem.allowWrite` per concedere l'accesso a percorsi specifici:270Per impostazione predefinita, i comandi in sandbox possono scrivere nella directory di lavoro corrente, nella directory temporanea per utente e in qualsiasi [directory che hai aggiunto](/docs/it/permissions#additional-directories-grant-file-access-not-configuration) con `--add-dir`, `/add-dir` o `permissions.additionalDirectories`. Se comandi eseguiti come sottoprocessi, come `kubectl`, `terraform` o `npm`, devono scrivere al di fuori di quelle directory, usa `sandbox.filesystem.allowWrite` per concedere l'accesso a percorsi specifici:

193 271

194```json theme={null}272```json theme={null}

195{273{

202}280}

203```281```

204 282

205Questi percorsi sono applicati a livello del sistema operativo, quindi tutti i comandi in esecuzione all'interno della sandbox, inclusi i loro processi figlio, li rispettano. Questo è l'approccio consigliato quando uno strumento ha bisogno dell'accesso in scrittura a una posizione specifica, piuttosto che escludere completamente lo strumento dalla sandbox con `excludedCommands`.283Questi percorsi vengono applicati a livello di sistema operativo, quindi tutti i comandi eseguiti all'interno della sandbox, inclusi i loro processi figli, li rispettano. Questo è l'approccio consigliato quando uno strumento ha bisogno dell'accesso in scrittura a una posizione specifica, anziché escludere completamente lo strumento dalla sandbox con `excludedCommands`.

206 284

207Quando definisci lo stesso array del filesystem in più [ambiti di impostazioni](/docs/it/settings#settings-precedence), Claude Code li unisce, combinando i percorsi da ogni ambito piuttosto che sostituire l'array di un ambito con quello di un altro.285Quando definisci lo stesso array del filesystem in più [ambiti di impostazioni](/docs/it/settings#settings-precedence), Claude Code ne esegue il merge, combinando i percorsi anziché sostituire l'array di un ambito con quello di un altro. Claude Code esclude una voce dal merge quando è coperta da un blocco descritto in [Impedire agli sviluppatori di ampliare la policy](#keep-developers-from-widening-the-policy).

208 286

209Se escludi un'origine con [`--setting-sources`](/docs/it/cli-reference) sulla CLI o [`settingSources`](/docs/it/agent-sdk/claude-code-features#control-filesystem-settings-with-settingsources) in Agent SDK, Claude Code ignora le sue voci `sandbox.filesystem`, le sue regole di permesso `Edit` e le sue regole di negazione `Read` quando costruisce la configurazione della sandbox. Richiede Claude Code v2.1.246 o successivo.287Se escludi un'origine con [`--setting-sources`](/docs/it/cli-reference) nella CLI o con [`settingSources`](/docs/it/agent-sdk/claude-code-features#control-filesystem-settings-with-settingsources) nell'Agent SDK, Claude Code ignora le sue voci `sandbox.filesystem`, le sue regole di permesso `Edit` e le sue regole di negazione `Read` durante la creazione della configurazione della sandbox. Richiede Claude Code v2.1.246 o successivo.

210 288

211Quando modifichi questi elenchi del filesystem durante una sessione, Claude Code [applica la modifica alla sessione in esecuzione](/docs/it/settings#when-edits-take-effect), quindi il prossimo comando in sandbox viene eseguito con i nuovi percorsi.289Quando modifichi questi elenchi del filesystem durante una sessione, Claude Code [applica la modifica alla sessione in corso](/docs/it/settings#when-edits-take-effect), quindi il successivo comando in sandbox viene eseguito con i nuovi percorsi.

212 290

213I prefissi dei percorsi controllano come vengono risolti i percorsi:291I percorsi del filesystem della sandbox usano le convenzioni standard: `/tmp/build` è assoluto e `~/.kube` è relativo alla tua directory home. Questa sintassi è diversa da quella delle [regole di permesso Read e Edit](/docs/it/permissions#read-and-edit), che usano `//path` per i percorsi assoluti e `/path` per quelli relativi al progetto. Per i percorsi relativi, le barre finali e i caratteri jolly, consulta [Prefissi dei percorsi della sandbox](/docs/it/settings-reference#sandbox-path-prefixes).

214 292

215| Prefisso | Significato | Esempio |293Puoi anche negare l'accesso in scrittura o in lettura usando `sandbox.filesystem.denyWrite` e `sandbox.filesystem.denyRead`, e consentire di nuovo percorsi specifici all'interno di un'area negata usando `sandbox.filesystem.allowRead`. Quando le regole di lettura si sovrappongono, si applica la regola con il percorso più ristretto:

216| :- | :- | :- |

217| `/` | Percorso assoluto dalla radice del filesystem | `/tmp/build` rimane `/tmp/build` |

218| `~/` | Relativo alla directory home | `~/.kube` diventa `$HOME/.kube` |

219| `./` o nessun prefisso | Relativo alla radice del progetto per le impostazioni del progetto, o a `~/.claude` per le impostazioni utente | `./output` in `.claude/settings.json` si risolve in `<project-root>/output` |

~~220~~

221Questa sintassi differisce dalle [regole di permesso Read e Edit](/docs/it/permissions#read-and-edit), che usano `//path` per assoluto e `/path` per relativo al progetto. I percorsi del filesystem della sandbox usano convenzioni standard: `/tmp/build` è assoluto. Per come Claude Code tratta una barra finale o un wildcard in questi percorsi, vedi [Prefissi dei percorsi della sandbox](/docs/it/settings-reference#sandbox-path-prefixes).

~~222~~

223Puoi anche negare l'accesso in scrittura o lettura usando `sandbox.filesystem.denyWrite` e `sandbox.filesystem.denyRead`, e ri-consentire percorsi specifici all'interno di una regione negata usando `sandbox.filesystem.allowRead`. Quando le regole di lettura si sovrappongono, il percorso più specifico vince:

224 294

225| Regole di esempio | Risultato |295| Regole di esempio | Risultato |

226| :- | :- |296| :- | :- |

227| `"denyRead": ["~/"]` con `"allowRead": ["~/projects"]` | `~/projects` è leggibile e il resto della directory home rimane bloccato. L'allow più ristretto riapre quella parte della regione negata |297| `"denyRead": ["~/"]` con `"allowRead": ["~/projects"]` | `~/projects` è leggibile e il resto della directory home resta bloccato. Il permesso più ristretto riapre quella parte dell'area negata |

228| `"allowRead": ["~/"]` con `"denyRead": ["~/.env"]` | `~/.env` rimane bloccato e il resto della directory home è leggibile. Il deny si mantiene all'interno di un allow più ampio, quindi un allow ampio non può silenziosamente ri-esporre un segreto |298| `"allowRead": ["~/"]` con `"denyRead": ["~/.env"]` | `~/.env` resta bloccato e il resto della directory home è leggibile. La negazione resta valida all'interno di un permesso più ampio, quindi un permesso esteso non può esporre di nuovo silenziosamente un segreto |

229| `"allowRead": ["~/"]` con `"denyRead": ["~/**/.env"]` | Ogni `.env` sotto la directory home rimane bloccato e il resto è leggibile. Un [wildcard deny](/docs/it/settings-reference#sandbox-path-prefixes) si mantiene all'interno di un allow più ampio nello stesso modo in cui lo fa un percorso esatto |299| `"allowRead": ["~/"]` con `"denyRead": ["~/**/.env"]` | Ogni `.env` sotto la directory home resta bloccato e il resto è leggibile. Una [negazione con carattere jolly](/docs/it/settings-reference#sandbox-path-prefixes) resta valida all'interno di un permesso più ampio allo stesso modo di un percorso esatto |

230 300

231L'esempio seguente blocca la lettura dall'intera directory home mantenendo comunque la lettura dal progetto corrente. Posizionalo nel `.claude/settings.json` del tuo progetto, perché il percorso relativo `.` si risolve alla radice del progetto solo quando la configurazione si trova nelle impostazioni del progetto:301L'esempio seguente blocca la lettura dall'intera directory home pur consentendo la lettura dal progetto corrente. Inseriscilo nel file `.claude/settings.json` del tuo progetto, perché il percorso relativo `.` si risolve nella radice del progetto solo quando la configurazione si trova nelle impostazioni di progetto:

232 302

233```json theme={null}303```json theme={null}

234{304{

242}312}

243```313```

244 314

245Se avessi posizionato la stessa configurazione in `~/.claude/settings.json`, `.` si risolverebbe in `~/.claude` invece, e i file del progetto rimarrebbero bloccati dalla regola `denyRead`.315Se inserissi la stessa configurazione in `~/.claude/settings.json`, `.` si risolverebbe invece in `~/.claude` e i file del progetto resterebbero bloccati dalla regola `denyRead`.

316

317Per negare ai comandi in sandbox l'accesso in lettura alle directory home e ai volumi montati mantenendo leggibili le directory di lavoro, imposta [`permissions.blockReadsOutsideWorkingDirectories`](/docs/it/settings-reference#permissions-blockreadsoutsideworkingdirectories) invece di scrivere regole sui percorsi.

318

319<h3 id="run-commands-outside-the-sandbox-with-excludedcommands">

320 Eseguire comandi al di fuori della sandbox con `excludedCommands`

321</h3>

322

323Elenca un pattern di comando in [`sandbox.excludedCommands`](/docs/it/settings-reference#sandbox-excludedcommands) per eseguire i comandi corrispondenti al di fuori della sandbox, il che significa nessuna restrizione del filesystem e nessun proxy di rete. Usalo per uno strumento che non può funzionare all'interno della sandbox e a cui affidi il tuo accesso completo. Uno strumento che ha bisogno di una directory o di un host in più potrebbe funzionare con `allowWrite` o `allowedDomains`, che mantengono il comando in sandbox.

324

325Questo esempio porta i comandi `docker compose` fuori dalla sandbox. Salvalo in `~/.claude/settings.json` per applicarlo a tutti i tuoi progetti:

326

327```json theme={null}

328{

329 "sandbox": {

330 "enabled": true,

331 "excludedCommands": ["docker compose *"]

332 }

333}

334```

335

336Claude Code confronta le tue voci con ogni chiamata Bash e Monitor. Una chiamata è l'intera riga di comando che Claude invia, che può concatenare più comandi. Le seguenti regole decidono se una chiamata esce dalla sandbox:

337

338* **Termina il pattern con ` *`**: le voci usano la stessa sintassi di una [regola di permesso](/docs/it/permissions#permission-rule-syntax) `Bash(...)`, in cui un pattern senza carattere jolly è una corrispondenza esatta. `docker` corrisponde solo a `docker` senza argomenti. `docker *` corrisponde a `docker` con o senza argomenti

339* **Ogni comando nella chiamata deve corrispondere**: `npm ci && docker compose build` resta in sandbox a meno che un'altra voce non copra `npm ci`

340* **Claude Code confronta il testo della chiamata**: uno script o un target `make` che chiama `docker` internamente non corrisponde, e nemmeno `/usr/local/bin/docker`

341* **Alcune chiamate restano in sandbox**: un reindirizzamento a un file, un `cd` o una sostituzione di comando come `$(...)` mantiene in sandbox l'intera chiamata. La [voce di riferimento](/docs/it/settings-reference#sandbox-excludedcommands) elenca altre chiamate che restano in sandbox

342* **Il punto in cui salvi la voce può fare la differenza**: quando la sandbox è [richiesta dall'amministratore](#repository-settings-under-an-admin-required-sandbox), Claude Code ignora le voci in `.claude/settings.json` e `.claude/settings.local.json`

343

344Un comando escluso segue il normale flusso dei permessi:

246 345

247Per negare ai comandi in sandbox l'accesso in lettura alle directory home e ai volumi montati mantenendo le directory di lavoro leggibili, imposta [`permissions.blockReadsOutsideWorkingDirectories`](/docs/it/settings-reference#permissions-blockreadsoutsideworkingdirectories) invece di scrivere regole di percorso.346* I [comandi di sola lettura](/docs/it/permissions#read-only-commands) e i comandi coperti dalle tue regole di autorizzazione vengono eseguiti senza richiesta di conferma

347* In modalità auto, il classificatore esamina gli altri comandi esclusi

348* In modalità `bypassPermissions`, un comando escluso viene eseguito senza richiesta di conferma a meno che non corrisponda a una regola ask

349

350Per verificare che una voce corrisponda, passa alla modalità Manual e chiedi a Claude di eseguire un comando corrispondente che modifichi qualcosa, come `docker compose up -d`. La richiesta di permesso ha il titolo "Bash command (unsandboxed)".

351

352<Warning>

353 Un comando escluso viene eseguito con il tuo accesso completo. Una voce ampia come `docker *` copre tutto ciò che quello strumento può fare. Se scrivi un pattern che copre un interprete, uno script all'interno della tua directory di lavoro o uno strumento che agisce su un file lì presente, come fa `docker compose` con il suo file compose, Claude può scrivere quel file e poi eseguirlo al di fuori della sandbox. Un pattern più ristretto lascia meno cose che Claude può eseguire al di fuori della sandbox.

354</Warning>

248 355

249<h3 id="disable-filesystem-isolation">356<h3 id="disable-filesystem-isolation">

250 Disabilita l'isolamento del filesystem357 Disattivare l'isolamento del filesystem

251</h3>358</h3>

252 359

253Imposta `sandbox.filesystem.disabled` su `true` per saltare l'isolamento del filesystem mantenendo l'isolamento della rete. L'esempio seguente disattiva l'isolamento del filesystem mantenendo una lista di permessi di domini di rete:360Imposta `sandbox.filesystem.disabled` su `true` per saltare l'isolamento del filesystem mantenendo l'isolamento di rete. L'esempio seguente disattiva l'isolamento del filesystem mantenendo un'allowlist di domini di rete:

254 361

255```json theme={null}362```json theme={null}

256{363{

266}373}

267```374```

268 375

269La sandbox ha due livelli indipendenti: [l'isolamento del filesystem](#filesystem-isolation) controlla quali percorsi i comandi in sandbox possono leggere e scrivere, e [l'isolamento della rete](#network-isolation) controlla quali domini possono raggiungere. Con il livello del filesystem disattivato, i comandi in sandbox ottengono accesso in lettura e scrittura senza restrizioni al filesystem host, mentre il loro egresso di rete rimane confinato ai tuoi domini consentiti. Disattiva il livello quando esegui il sandbox per controllare dove i comandi si connettono piuttosto che cosa scrivono.376La sandbox ha due livelli indipendenti: l'[isolamento del filesystem](#filesystem-isolation) controlla quali percorsi i comandi in sandbox possono leggere e scrivere, e l'[isolamento di rete](#network-isolation) controlla quali domini possono raggiungere. Con il livello del filesystem disattivato, i comandi in sandbox ottengono accesso illimitato in lettura e scrittura al filesystem dell'host, mentre il loro traffico di rete in uscita resta limitato ai domini consentiti. Disattiva questo livello quando usi la sandbox per controllare dove si connettono i comandi anziché cosa scrivono.

270 377

271L'impostazione è disattivata per impostazione predefinita e si applica sulle piattaforme dove la sandbox viene eseguita: macOS, Linux e WSL2. Richiede Claude Code v2.1.216 o successivo.378`sandbox.filesystem.disabled` ha `false` come valore predefinito. Richiede Claude Code v2.1.216 o successivo.

272 379

273<Warning>380<Warning>

274 Con l'isolamento del filesystem disattivato e i comandi auto-consentiti, un comando in sandbox può scrivere file che i comandi successivi eseguono o leggono, come file di avvio della shell, eseguibili su `$PATH` o `~/.claude/settings.json`, e usarli per ampliare il proprio accesso alla prossima esecuzione. Imposta `filesystem.disabled` su `true` solo per carichi di lavoro di cui ti fidi che non escalino il proprio accesso. Bloccare i domini di rete con [`allowManagedDomainsOnly`](#keep-developers-from-widening-the-policy) riduce il rischio ma non lo elimina, poiché quel blocco si applica solo ai comandi in esecuzione all'interno della sandbox.381 Con l'isolamento del filesystem disattivato e i comandi consentiti automaticamente, un comando in sandbox può scrivere file che i comandi successivi eseguono o leggono, come i file di avvio della shell, gli eseguibili in `$PATH` o `~/.claude/settings.json`, e usarli per ampliare il proprio accesso all'esecuzione successiva. Imposta `filesystem.disabled` su `true` solo per carichi di lavoro di cui ti fidi che non amplino il proprio accesso. Bloccare i domini di rete con [`allowManagedDomainsOnly`](#keep-developers-from-widening-the-policy) riduce il rischio ma non lo elimina, poiché quel blocco si applica solo ai comandi eseguiti all'interno della sandbox.

275</Warning>382</Warning>

276 383

277<h4 id="which-settings-can-disable-it">384<h4 id="which-settings-can-disable-it">

278 Quali impostazioni possono disabilitarlo385 Quali impostazioni possono disattivarlo

279</h4>386</h4>

280 387

281Poiché disattivare l'isolamento del filesystem amplia ciò che i comandi in sandbox possono fare, Claude Code onora `filesystem.disabled` solo da queste fonti di impostazioni:388Poiché disattivare l'isolamento del filesystem amplia ciò che i comandi in sandbox possono fare, Claude Code rispetta `filesystem.disabled` solo da queste origini di impostazioni:

282 389

283* Le impostazioni utente, le impostazioni gestite e il flag CLI `--settings` possono impostarlo. Le impostazioni del progetto in `.claude/settings.json` e `.claude/settings.local.json` non possono, quindi un progetto estratto non può disattivare l'isolamento del filesystem.390* Le impostazioni utente, le impostazioni gestite e il flag CLI `--settings` possono impostarlo. Le impostazioni di progetto in `.claude/settings.json` e `.claude/settings.local.json` non possono, quindi un progetto scaricato non può disattivare l'isolamento del filesystem.

284* Quando le impostazioni gestite configurano `sandbox.filesystem` in generale, o elencano qualsiasi voce `sandbox.credentials.files` con `"mode": "deny"`, solo le impostazioni gestite possono impostare la chiave. Questo mantiene in vigore le restrizioni del filesystem distribuite dall'amministratore; per rilassare tale distribuzione, imposta `"disabled": true` nelle impostazioni gestite.391* Quando le impostazioni gestite configurano `sandbox.filesystem` in qualsiasi modo, o elencano una qualsiasi voce `sandbox.credentials.files` con `"mode": "deny"`, solo le impostazioni gestite possono impostare la chiave. Questo mantiene in vigore le restrizioni del filesystem distribuite dall'amministratore; per allentare tale distribuzione, imposta `"disabled": true` nelle impostazioni gestite.

285* Quando [`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`](/docs/it/env-vars) è impostato, Claude Code ignora `filesystem.disabled` da ogni fonte, incluse le impostazioni gestite, e mantiene l'isolamento del filesystem attivo.392* Quando [`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`](/docs/it/env-vars) è impostata, Claude Code ignora `filesystem.disabled` da ogni origine, incluse le impostazioni gestite, e mantiene attivo l'isolamento del filesystem.

286 393

287Se una voce gestita `credentials.files` fissa `filesystem.disabled`, bloccando la chiave alle impostazioni gestite in modo che gli sviluppatori non possano disattivare l'isolamento del filesystem, dipende dalla `mode` della voce e da cosa accade alla voce quando la sandbox si avvia:394Una voce `mask` [valida](/docs/it/settings-reference#invalid-credential-entries-in-managed-settings) non blocca la chiave, anche quando Claude Code [ripiega su `deny`](#mask-credential-files) per essa all'avvio. Elenca un percorso che non può essere mascherato, come una directory di credenziali, come voce `deny` esplicita nelle impostazioni gestite, che blocca la chiave.

~~288~~

289| Voce gestita | Fissa `filesystem.disabled` | Cosa protegge il file quando l'isolamento è disattivato |

290| - | - | - |

291| `"mode": "deny"` | Sì | Niente: il blocco di lettura fa parte del livello del filesystem |

292| `"mode": "mask"`, applicato come maschera | No | La mascheratura stessa: la [copia sentinella e il proxy](#mask-credential-files) su Linux e WSL2, le proprie regole di lettura della sandbox su macOS |

293| `"mode": "mask"`, [fallback a `deny`](#mask-credential-files) al setup | No | Niente, come `deny`. Elenca un percorso che non può essere mascherato, come una directory, come voce esplicita `deny`, che fissa la chiave |

294| `"mode": "mask"`, [degradato a `deny` dalla validazione](/docs/it/managed-settings#invalid-entries-in-managed-settings) | Sì, come una voce esplicita `deny` | Niente, come `deny` |

~~295~~

296Un fallback accade quando la sandbox si avvia, dopo che Claude Code ha già letto le impostazioni su cui viene eseguito il controllo del pin, quindi una voce con fallback non fissa mai. La validazione riscrive una voce non valida a `deny` mentre le impostazioni si caricano, quindi una voce degradata fissa come una che hai scritto come `deny`.

297 395

298<h4 id="what-changes-when-filesystem-isolation-is-off">396<h4 id="what-changes-when-filesystem-isolation-is-off">

299 Cosa cambia quando l'isolamento del filesystem è disattivato397 Cosa cambia quando l'isolamento del filesystem è disattivato

300</h4>398</h4>

301 399

302Impostare `filesystem.disabled` solleva le protezioni che il livello del filesystem stesso applica. Le protezioni che altri livelli applicano continuano a funzionare:400L'impostazione di `filesystem.disabled` rimuove le protezioni applicate dal livello del filesystem stesso. Le protezioni applicate da altri livelli continuano a valere:

303 401

304| Protezione | Con l'isolamento del filesystem disattivato |402| Protezione | Con l'isolamento del filesystem disattivato |

305| - | - |403| - | - |

306| `filesystem.denyRead` e [`credentials.files`](#protect-credentials) blocchi di lettura `deny` | Non applicati. Il livello del filesystem applica entrambi |404| Blocchi di lettura `filesystem.denyRead` e `deny` di [`credentials.files`](#protect-credentials) | Non applicati. Entrambi sono applicati dal livello del filesystem |

307| `credentials.envVars` voci `deny` e `mask` | Applicati. Lo scrubbing delle variabili di ambiente è indipendente dal livello del filesystem |405| Voci `deny` e `mask` di `credentials.envVars` | Applicate. La rimozione delle variabili d'ambiente è indipendente dal livello del filesystem |

308| [`credentials.files` voci `mask`](#mask-credential-files) applicate come maschere | Applicati: la mascheratura è indipendente dal livello del filesystem. Una voce che ha [fallback a `deny`](#mask-credential-files) non è applicata, come qualsiasi voce `deny` |406| [Voci `mask` di `credentials.files`](#mask-credential-files) applicate come maschere | Applicate: il mascheramento è indipendente dal livello del filesystem. Una voce [ripiegata su `deny`](#mask-credential-files) non viene applicata, come qualsiasi voce `deny` |

309 407

310Due altre cose cambiano:408Cambiano altre due cose:

311 409

312* I comandi in sandbox ereditano il `$TMPDIR` della tua shell invece della directory temporanea della sessione, perché ogni directory temporanea è scrivibile e Claude Code non reindirizza più i comandi a quella della sessione.410* I comandi in sandbox ereditano il `$TMPDIR` della tua shell invece della directory temporanea per utente, perché ogni directory temporanea è scrivibile e Claude Code non reindirizza più i comandi a quella per utente.

313 411

314 Su Linux la variabile è spesso non impostata nella shell padre. La guida dello strumento Bash dice a Claude di creare directory di lavoro con `mktemp -d` invece di fare affidamento su `$TMPDIR`.412 Su Linux la variabile spesso non è impostata nella shell padre. Le indicazioni dello strumento Bash dicono a Claude di creare directory temporanee con `mktemp -d` invece di affidarsi a `$TMPDIR`.

315* [`autoAllowBashIfSandboxed`](/docs/it/settings-reference#sandbox-autoallowbashifsandboxed) continua a impostare il valore predefinito su `true`, quindi i comandi in sandbox continuano a essere eseguiti senza prompt. Impostalo su `false` per richiedere prompt per i comandi in sandbox.413* [`autoAllowBashIfSandboxed`](/docs/it/settings-reference#sandbox-autoallowbashifsandboxed) ha ancora `true` come valore predefinito, quindi i comandi in sandbox continuano a essere eseguiti senza richiesta di conferma. Impostalo su `false` per chiedere conferma per i comandi in sandbox.

316 414

317<h3 id="protect-credentials">415<h3 id="protect-credentials">

318 Proteggi le credenziali416 Proteggere le credenziali

319</h3>417</h3>

320 418

321L'impostazione `sandbox.credentials` dichiara file di credenziali e variabili di ambiente da proteggere dai comandi in sandbox. Ogni voce nomina un percorso di file o una variabile di ambiente e una `mode`. Il blocco dedicato `credentials` mantiene le regole delle credenziali raggruppate insieme e separate dalle regole generali del filesystem.419L'impostazione `sandbox.credentials` dichiara i file di credenziali e le variabili d'ambiente da proteggere dai comandi in sandbox. Ogni voce indica un percorso di file o una variabile d'ambiente e un `mode`. Il blocco dedicato `credentials` mantiene le regole sulle credenziali raggruppate e separate dalle regole generali del filesystem.

322 420

323Per le voci con `"mode": "deny"`, i percorsi dei file vengono negati per le letture all'interno della sandbox, la stessa restrizione che `filesystem.denyRead` applica, e le variabili di ambiente vengono non impostate prima di ogni comando in sandbox. La protezione del file fa parte del livello del filesystem, quindi non si applica se [disabiliti l'isolamento del filesystem](#disable-filesystem-isolation); la protezione della variabile di ambiente continua comunque.421Per le voci con `"mode": "deny"`, ai percorsi dei file viene negata la lettura all'interno della sandbox, la stessa restrizione applicata da `filesystem.denyRead`, e le variabili d'ambiente vengono rimosse prima dell'esecuzione di ogni comando in sandbox. La protezione dei file fa parte del livello del filesystem, quindi non si applica se [disattivi l'isolamento del filesystem](#disable-filesystem-isolation); la protezione delle variabili d'ambiente invece sì.

324 422

325L'esempio seguente blocca le letture del file delle credenziali AWS e della directory SSH e rimuove `GITHUB_TOKEN` e `NPM_TOKEN` dall'ambiente dei comandi in sandbox:423L'esempio seguente blocca la lettura del file delle credenziali AWS e della directory SSH e rimuove `GITHUB_TOKEN` e `NPM_TOKEN` dall'ambiente dei comandi in sandbox:

326 424

327```json theme={null}425```json theme={null}

328{426{

342}440}

343```441```

344 442

345Le voci delle variabili di ambiente e le voci dei file accettano anche `"mode": "mask"`, descritte sotto [Maschera le credenziali](#mask-credentials).443Le voci delle variabili d'ambiente e dei file accettano anche `"mode": "mask"`, descritto in [Mascherare le credenziali](#mask-credentials).

346 444

347I percorsi dei file seguono le stesse [regole di prefisso](/docs/it/settings-reference#sandbox-path-prefixes) delle impostazioni `sandbox.filesystem.*`.445I percorsi dei file seguono le stesse [regole sui prefissi](/docs/it/settings-reference#sandbox-path-prefixes) delle impostazioni `sandbox.filesystem.*`.

348 446

349Claude Code unisce le voci `deny` da ogni [ambito di impostazioni](/docs/it/settings#settings-precedence) che la sessione carica. Una voce `deny` restringe solo l'accesso, quindi qualsiasi ambito può aggiungerne una, ma nessun ambito può rimuoverne una che un altro ambito ha aggiunto.447Claude Code combina le voci `deny` di ogni [ambito di impostazioni](/docs/it/settings#settings-precedence) caricato dalla sessione. Una voce `deny` restringe sempre e solo l'accesso, quindi qualsiasi ambito può aggiungerne una, ma nessun ambito può rimuoverne una aggiunta da un altro ambito.

350 448

351Quando [escludi una fonte di impostazioni](#configure-sandboxing):449Quando [escludi un'origine di impostazioni](#configure-sandboxing):

352 450

353* **Impostazioni del progetto o locali**: Claude Code non applica nessuna delle loro voci `credentials`. Richiede Claude Code v2.1.246 o successivo.451* **Impostazioni di progetto o locali**: Claude Code non applica nessuna delle loro voci `credentials`. Richiede Claude Code v2.1.246 o successivo.

354* **Impostazioni utente**: Claude Code applica comunque le voci `deny` in `~/.claude/settings.json` e mantiene le sue [voci `mask` del file](#mask-credential-files) come restrizioni, ma elimina le sue [voci `mask` delle variabili di ambiente](#mask-environment-variables).452* **Impostazioni utente**: Claude Code applica comunque le voci `deny` in `~/.claude/settings.json` e mantiene le sue [voci `mask` dei file](#mask-credential-files) come restrizioni che non autorizzano più il proxy a sostituire il valore reale, ma scarta le sue [voci `mask` delle variabili d'ambiente](#mask-environment-variables).

355 453

356Non esiste un elenco di negazione delle credenziali integrato, quindi solo i file e le variabili che elenchi sono limitati.454Non esiste un elenco integrato di credenziali negate, quindi sono limitati solo i file e le variabili che elenchi.

357 455

358`sandbox.credentials` influisce solo sui comandi Bash in sandbox. Per rimuovere le credenziali da tutti i sottoprocessi indipendentemente dal sandboxing, imposta [`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`](/docs/it/env-vars).456`sandbox.credentials` riguarda solo i comandi Bash in sandbox. Per rimuovere le credenziali da tutti i sottoprocessi indipendentemente dal sandboxing, imposta [`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`](/docs/it/env-vars).

359 457

360<h3 id="mask-credentials">458<h3 id="mask-credentials">

361 Maschera le credenziali459 Mascherare le credenziali

362</h3>460</h3>

363 461

364La mascheratura va oltre una voce `deny` sotto [Proteggi le credenziali](#protect-credentials). Invece di bloccare una credenziale, Claude Code mostra ai comandi in sandbox un segnaposto, la sentinella, e il [proxy della sandbox](#network-isolation) scambia il valore reale sulle richieste in uscita agli host che consenti. Per i file, la sostituzione è il comportamento di Linux e WSL2; [macOS blocca il file invece](#mask-credential-files).462Quando mascheri una credenziale, Claude Code mostra ai comandi in sandbox un segnaposto valido per la sessione, chiamato sentinella, e il [proxy della sandbox](#network-isolation) sostituisce il valore reale nelle richieste in uscita verso gli host che consenti. Una voce `deny` descritta in [Proteggere le credenziali](#protect-credentials) blocca invece la credenziale. Per i file su macOS, Claude Code [blocca il file](#mask-credential-files) invece di mascherarlo.

365 463

366<h4 id="mask-environment-variables">464Il mascheramento delle variabili d'ambiente richiede Claude Code v2.1.199 o successivo. Il riferimento di [`sandbox.credentials`](/docs/it/settings-reference#sandbox-credentials) elenca tutti i campi.

367 Maschera le variabili di ambiente

368</h4>

369 465

370`"mode": "mask"` protegge una credenziale mantenendo gli strumenti che si autenticano con essa funzionanti. `deny` rimuove completamente la variabile, il che rompe anche gli strumenti che ne hanno bisogno, come `gh` o `npm`. Richiede Claude Code v2.1.199 o successivo.466Il mascheramento richiede quanto segue:

371 467

372Con `mask`, il comando in sandbox vede un valore sentinella per sessione invece di quello reale. Ogni voce `mask` può elencare `injectHosts`, gli host a cui il valore reale è consentito raggiungere. Quando una richiesta esce dalla sandbox per uno di loro, il [proxy della sandbox](#network-isolation) sostituisce la sentinella con il valore reale. Il comando e tutto ciò che registra non contengono mai la credenziale reale, ma le sue richieste si autenticano comunque.468* **Terminazione TLS**: il proxy sostituisce il valore reale all'interno del contenuto delle richieste, quindi deve poterlo vedere. Imposta [`network.tlsTerminate`](/docs/it/settings-reference#sandbox-network-tlsterminate) in modo che il proxy termini direttamente il TLS. Senza di esso, il mascheramento fallisce senza esporre nulla: il comando vede comunque solo la sentinella, ma la sentinella raggiunge il server invariata e l'autenticazione fallisce. Claude Code segnala questa configurazione errata all'avvio.

469* **Una destinazione consentita**: ogni voce `mask` può elencare `injectHosts`, gli host che il valore reale può raggiungere. Il proxy inserisce le credenziali solo nelle connessioni ammesse dall'[allowlist dei domini](#network-isolation), quindi ogni host `injectHosts` deve essere raggiungibile anche tramite `network.allowedDomains`. Per una voce `mask` senza `injectHosts`, il proxy sostituisce il valore reale nelle richieste verso ogni host in `network.allowedDomains`.

470* **Un ambito di impostazioni attendibile**: il mascheramento autorizza il proxy a inviare la tua credenziale reale altrove, quindi Claude Code rispetta le voci `mask`, `network.tlsTerminate`, [`credentials.allowPlaintextInject`](/docs/it/settings-reference#sandbox-credentials-allowplaintextinject), `awsPairs` e `sigv4` solo dalle impostazioni utente, dalle impostazioni gestite e dal flag `--settings`. Li ignora nei file `.claude/settings.json` o `.claude/settings.local.json` di un repository. Quando il tuo amministratore distribuisce voci `mask`, `network.tlsTerminate` o `credentials.allowPlaintextInject` tramite impostazioni gestite dal server, queste vengono considerate [impostazioni che richiedono approvazione](/docs/it/server-managed-settings#security-approval-dialogs).

373 471

374Il proxy sostituisce la credenziale all'interno dei contenuti della richiesta, quindi deve vederli. Imposta [`network.tlsTerminate`](/docs/it/settings-reference#sandbox-network-tlsterminate) in modo che il proxy termini TLS stesso.472<h4 id="mask-environment-variables">

~~375~~ 473 Mascherare le variabili d'ambiente

376Senza di esso, la mascheratura fallisce senza esporre nulla: il comando continua a vedere solo la sentinella, ma la sentinella raggiunge il server invariata e l'autenticazione fallisce. Claude Code segnala questa configurazione errata all'avvio.474</h4>

~~377~~

378La sostituzione copre intestazioni e corpi di richiesta. Le richieste che si autenticano con una firma derivata dalla credenziale, piuttosto che dalla credenziale stessa, hanno bisogno di una nuova firma al proxy; [Firma di nuovo le richieste AWS](#re-sign-aws-requests) copre come funziona per AWS.

379 475

380Il proxy inietta solo sulle connessioni che la [lista di permessi del dominio](#network-isolation) ammette, quindi ogni destinazione `injectHosts` deve anche essere raggiungibile attraverso `network.allowedDomains`.476Per mascherare una variabile d'ambiente, imposta `"mode": "mask"` sulla sua voce `credentials.envVars`. Il comando e tutto ciò che registra nei log non contengono mai la credenziale reale, ma le sue richieste vengono comunque autenticate. Quando la stessa variabile è elencata con `deny` in qualsiasi ambito, `deny` ha la precedenza.

381 477

382L'esempio seguente maschera due token. `GH_TOKEN` viene sostituito solo sulle richieste a `api.github.com`, mentre `NPM_TOKEN` non ha `injectHosts` e viene sostituito sulle richieste a ogni host in `network.allowedDomains`.478L'esempio seguente maschera due token. `GH_TOKEN` viene sostituito solo nelle richieste verso `api.github.com`, mentre `NPM_TOKEN` non ha `injectHosts` e viene sostituito nelle richieste verso ogni host in `network.allowedDomains`:

383 479

384```json theme={null}480```json theme={null}

385{481{

399}495}

400```496```

401 497

402<span id="ipv6-destinations-in-injecthosts" />Scrivi una destinazione IPv6 diversamente nei due elenchi, perché ogni elenco ha il suo matcher:498Per impostazione predefinita il mascheramento sostituisce l'intero valore. Per un valore strutturato, come una stringa di connessione `DATABASE_URL` o un JWT, usa i [campi `extract`, `decode`, `maskClaims` e `onExtractNoMatch`](/docs/it/settings-reference#sandbox-credentials-envvars) in modo che gli strumenti che analizzano il valore continuino a funzionare.

~~403~~

404* **`network.allowedDomains`**: la [forma tra parentesi che gli elenchi di domini usano](#ipv6-addresses-in-domain-lists), come `"[::1]"`. Il proxy controlla questo elenco per ammettere la connessione.

405* **`injectHosts`**: l'indirizzo nudo nella sua forma canonica compressa, come `"::1"` o `"2001:db8::1"`. Il proxy confronta ogni voce con l'indirizzo di destinazione nudo della connessione, ignorando le porte, quindi una forma tra parentesi, con ID zona o diversamente compressa non corrisponde mai e il proxy non inietta mai la credenziale lì.

~~406~~

407`claude doctor` contrassegna le voci `injectHosts` che non possono mai corrispondere con l'avviso `Sandbox credential injectHosts entries can never match their destination`. Questo controllo richiede Claude Code v2.1.229 o successivo.

~~408~~

409A differenza di `deny`, la mascheratura autorizza il proxy a inviare la tua credenziale reale agli host elencati, quindi Claude Code la onora solo dalle impostazioni che tu o il tuo amministratore controllate: impostazioni utente, impostazioni gestite e il flag CLI `--settings`. Claude Code ignora le voci `mask` nel `.claude/settings.json` o `.claude/settings.local.json` di un repository. In quei file ignora anche `network.tlsTerminate` e [`credentials.allowPlaintextInject`](/docs/it/settings-reference#sandbox-credentials-allowplaintextinject), l'impostazione che consente al proxy di iniettare credenziali in richieste non crittografate. Se [escludi le impostazioni utente](#configure-sandboxing), Claude Code elimina anche le voci `mask` delle variabili di ambiente in `~/.claude/settings.json`.

410 499

411Quando il tuo amministratore fornisce voci `mask`, `network.tlsTerminate` o `credentials.allowPlaintextInject` attraverso le impostazioni gestite dal server, contano come [impostazioni che richiedono approvazione](/docs/it/server-managed-settings#security-approval-dialogs).500<span id="ipv6-destinations-in-injecthosts" />Per una destinazione IPv6, scrivi l'indirizzo in modo diverso nei due elenchi:

412 501

413Quando la stessa variabile è elencata con `deny` in qualsiasi ambito, `deny` ha la precedenza.502* **`network.allowedDomains`**: la forma tra parentesi quadre, come `"[::1]"`

503* **`injectHosts`**: l'indirizzo senza parentesi nella sua forma compressa canonica, come `"::1"`

414 504

415La mascheratura sostituisce l'intero valore della variabile per impostazione predefinita, il che si adatta a un token nudo. I campi di voce opzionali, che richiedono Claude Code v2.1.224 o successivo, gestiscono valori con struttura:505Il proxy confronta ogni voce `injectHosts` con l'indirizzo di destinazione senza parentesi della connessione, ignorando le porte, quindi una scrittura tra parentesi, con ID di zona o compressa in modo diverso non corrisponde mai. `claude doctor` segnala le voci che non possono mai corrispondere con l'avviso `Sandbox credential injectHosts entries can never match their destination`. Questo controllo richiede Claude Code v2.1.229 o successivo.

~~416~~

417* `extract`: un'espressione regolare che Claude Code applica su tutto il valore, sostituendo solo il testo catturato dal gruppo 1 di ogni corrispondenza, quindi uno strumento che analizza il valore, come una stringa di connessione `DATABASE_URL`, continua a funzionare all'interno della sandbox. Il pattern deve contenere almeno un gruppo di cattura.

418* `onExtractNoMatch` controlla cosa accade quando il pattern non corrisponde a nulla:

419 * `warn`, il valore predefinito, avverte e passa la variabile attraverso senza mascheratura

420 * `deny` non imposta la variabile all'interno della sandbox

421 * `error` interrompe il setup della sandbox finché non fissi la configurazione

422* `decode: "jwt"`: per una variabile che contiene un JSON Web Token (JWT). Claude Code verifica che il valore sia un JWT e lo sostituisce con un token falso strutturalmente valido, quindi il codice all'interno della sandbox che decodifica il token continua a funzionare. Aggiungi `maskClaims` per elencare i claim del payload di livello superiore da mascherare individualmente invece di sostituire l'intero token; gli altri claim rimangono leggibili. Quando il valore non si verifica come JWT, o nessun claim elencato corrisponde, Claude Code passa la variabile attraverso senza mascheratura con un avviso. `decode` non può essere combinato con `extract`.

~~423~~

424Vedi le [righe `credentials.envVars[]` nel riferimento delle impostazioni](/docs/it/settings-reference#sandbox-settings) per l'elenco completo dei campi.

425 506

426<h4 id="re-sign-aws-requests">507<h4 id="re-sign-aws-requests">

427 Firma di nuovo le richieste AWS508 Firmare di nuovo le richieste AWS

428</h4>509</h4>

429 510

430Le richieste AWS portano firme SigV4 sui contenuti della richiesta, quindi maschera `AWS_ACCESS_KEY_ID` e `AWS_SECRET_ACCESS_KEY` insieme. Il proxy rileva una richiesta SigV4 dalla sentinella della chiave di accesso e la firma di nuovo dopo aver sostituito i valori reali. Mascherare solo il segreto lascia le richieste firmate con il segnaposto, che il proxy non può rilevare, quindi falliscono su AWS; Claude Code avverte di questo caso all'avvio, ma non quando solo l'ID della chiave di accesso è mascherato. Una richiesta rilevata che il proxy non può firmare di nuovo, come una senza il suo header `x-amz-date`, fallisce con un errore del proxy invece di raggiungere il server con una firma rotta.511Le richieste AWS contengono firme SigV4 calcolate sul contenuto della richiesta, quindi maschera `AWS_ACCESS_KEY_ID` e `AWS_SECRET_ACCESS_KEY` insieme. Il proxy rileva una richiesta SigV4 tramite la [sentinella](#mask-credentials) della chiave di accesso e firma di nuovo la richiesta con i valori reali, il che richiede Claude Code v2.1.221 o successivo. Se mascheri solo il segreto, le richieste vengono firmate con un segnaposto che il proxy non può rilevare, quindi falliscono su AWS.

~~431~~

432Claude Code collega le variabili convenzionali `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` e `AWS_SESSION_TOKEN` in una credenziale automaticamente quando mascheri i loro interi valori. Se la tua credenziale AWS si trova in variabili con altri nomi, raggruppale tu stesso con [`credentials.awsPairs`](/docs/it/settings-reference#sandbox-credentials-awspairs), che richiede Claude Code v2.1.224 o successivo. Questo esempio aggiunge l'accoppiamento a una configurazione che già maschera `MY_KEY_ID`, `MY_SECRET_KEY` e `MY_SESSION_TOKEN` a valore intero, come nella [configurazione di mascheratura sopra](#mask-environment-variables):

~~433~~

434```json theme={null}

435{

436 "sandbox": {

437 "credentials": {

438 "awsPairs": [

439 {

440 "accessKeyIdVar": "MY_KEY_ID",

441 "secretAccessKeyVar": "MY_SECRET_KEY",

442 "sessionTokenVar": "MY_SESSION_TOKEN"

443 }

444 ]

445 }

446 }

447}

448```

~~449~~

450Ogni voce segue queste regole:

~~451~~

452* `accessKeyIdVar` e `secretAccessKeyVar` nominano le voci `envVars` mascherate che contengono l'ID della chiave di accesso e la chiave segreta. L'opzionale `sessionTokenVar` nomina la voce che contiene il token di sessione per le credenziali temporanee; quando impostato, il proxy invia il token reale come `x-amz-security-token` sulle richieste firmate di nuovo.

453* Ogni variabile nominata deve essere una voce `mask` che maschera il suo intero valore, senza `extract` o `decode`.

454* Il proxy firma di nuovo le richieste sugli host elencati nella voce `injectHosts` dell'ID della chiave di accesso.

455* Nominare una qualsiasi delle variabili convenzionali in una coppia sostituisce l'accoppiamento automatico.

456 512

457Come le voci `mask`, `awsPairs` è onorato solo dalle impostazioni utente, dalle impostazioni gestite e dal flag CLI `--settings`.513Claude Code collega automaticamente le variabili convenzionali `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` e `AWS_SESSION_TOKEN` in un'unica credenziale quando ne mascheri l'intero valore. Se la tua credenziale AWS si trova in variabili con altri nomi, raggruppale con [`credentials.awsPairs`](/docs/it/settings-reference#sandbox-credentials-awspairs), che richiede Claude Code v2.1.224 o successivo.

458 514

459Tre forme di richiesta AWS portano firme che il proxy non può ricalcolare. Quando tale richiesta è firmata con il segnaposto di una coppia mascherata, il proxy la fallisce piuttosto che inoltrarla con una firma rotta; le richieste firmate con credenziali non mascherate non sono mai interessate. L'impostazione [`credentials.sigv4`](/docs/it/settings-reference#sandbox-credentials-sigv4), che richiede Claude Code v2.1.224 o successivo, rilassa questo per forma: impostare la chiave di una forma su `passthrough` inoltra la richiesta con la sua firma derivata dal segnaposto, quindi lo strumento che chiama riceve la propria risposta di rifiuto di AWS invece di un errore del proxy. Come `awsPairs`, `sigv4` è onorato solo dalle impostazioni utente, dalle impostazioni gestite e dal flag CLI `--settings`.515I caricamenti in streaming, gli URL prefirmati e le richieste SigV4A contengono firme che il proxy non può ricalcolare. Quando una di queste richieste è firmata con il segnaposto di una coppia mascherata, il proxy la fa fallire anziché inoltrare una firma non valida. Le richieste firmate con credenziali non mascherate non sono interessate. Usa [`credentials.sigv4`](/docs/it/settings-reference#sandbox-credentials-sigv4), che richiede Claude Code v2.1.224 o successivo, per inoltrare invece una di queste forme di richiesta. AWS rifiuta comunque la richiesta, quindi lo strumento chiamante riceve la risposta di rifiuto di AWS invece di un errore del proxy.

~~460~~

461| Forma di richiesta | Chiave `sigv4` | Perché il proxy non può firmarla di nuovo |

462| :- | :- | :- |

463| caricamenti di streaming aws-chunked | `streaming` | Le firme per chunk si concatenano dalla firma del seed, quindi la firma di nuovo richiederebbe la riscrittura del corpo |

464| URL prescritti | `presigned` | La firma si trova nell'URL stesso, senza header `Authorization` |

465| Firme asimmetriche SigV4A | `sigv4a` | Non esiste un HMAC a chiave condivisa da ricalcolare |

466 516

467<h4 id="mask-credential-files">517<h4 id="mask-credential-files">

468 Maschera i file di credenziali518 Mascherare i file di credenziali

469</h4>519</h4>

470 520

471Le voci dei file accettano anche `"mode": "mask"`, che richiede Claude Code v2.1.221 o successivo. Ciò che un comando in sandbox vede dipende dalla piattaforma:521Per mascherare un file di credenziali, imposta `"mode": "mask"` sulla sua voce `credentials.files`. Il mascheramento dei file richiede Claude Code v2.1.221 o successivo. Ciò che vede un comando in sandbox dipende dalla piattaforma:

472 522

473* **Linux e WSL2**: i comandi in sandbox leggono una copia sentinella del file, un sostituto il cui segreto è sostituito con un valore segnaposto, e il [proxy della sandbox](#network-isolation) sostituisce il valore reale all'uscita.523* **Linux e WSL2**: i comandi in sandbox leggono una copia [sentinella](#mask-credentials) del file, e il proxy sostituisce il valore reale nelle richieste in uscita.

474* **macOS**: i comandi in sandbox non possono leggere il file elencato. Claude Code non costruisce nessuna copia sentinella e non sostituisce nulla all'uscita, quindi gli strumenti che si autenticano con il file non funzionano all'interno della sandbox, lo stesso effetto di `deny`. A differenza di una voce `deny`, il blocco di lettura si mantiene anche quando [disabiliti l'isolamento del filesystem](#disable-filesystem-isolation).524* **macOS**: i comandi in sandbox non possono leggere affatto il file. Claude Code non crea alcuna copia sentinella, quindi gli strumenti che si autenticano con il file non funzionano all'interno della sandbox, lo stesso effetto di `deny`. Il blocco della lettura resta valido anche quando [disattivi l'isolamento del filesystem](#disable-filesystem-isolation).

475 525

476Su ogni piattaforma, Claude Code applica il requisito [`network.tlsTerminate`](/docs/it/settings-reference#sandbox-network-tlsterminate) e `injectHosts` nello stesso modo che per le [variabili di ambiente mascherate](#mask-environment-variables), e ignora le impostazioni del repository nello stesso modo. Se [escludi le impostazioni utente](#configure-sandboxing), Claude Code mantiene le voci `mask` del file in `~/.claude/settings.json` come restrizioni, ma le voci non autorizzano più il proxy a sostituire il valore reale.526L'esempio seguente maschera un token GitHub memorizzato in `~/.config/gh/hosts.yml`. Il pattern `extract` indica quale parte del file è il segreto, quindi su Linux e WSL2 `gh` analizza ancora il resto della sua configurazione:

~~477~~

478L'esempio seguente maschera un token GitHub memorizzato in `~/.config/gh/hosts.yml`; il pattern `extract`, coperto di seguito, dice a Claude Code quale parte del file è il segreto. Su Linux e WSL2, i comandi in sandbox che leggono il file ottengono una sentinella al posto del token, e il proxy sostituisce il token reale sulle richieste a `api.github.com`:

479 527

480```json theme={null}528```json theme={null}

481{529{

499}547}

500```548```

501 549

502Per confermare che la maschera è attiva, chiedi a Claude di eseguire `cat ~/.config/gh/hosts.yml` in un comando in sandbox: su Linux e WSL2 l'output mostra un valore sentinella al posto del token, e su macOS la lettura fallisce invece.550Per verificare che la maschera sia attiva, chiedi a Claude di eseguire `cat ~/.config/gh/hosts.yml` in un comando in sandbox. Su Linux e WSL2 l'output mostra una sentinella al posto del token, mentre su macOS la lettura fallisce.

~~503~~

504Su Linux e WSL2, il pattern `extract` è ciò che mantiene il resto di `hosts.yml` leggibile. Claude Code applica l'espressione regolare su tutto il file e sostituisce solo il testo catturato dal gruppo 1 di ogni corrispondenza, quindi `gh` continua a analizzare la sua configurazione e solo il token è un segnaposto. Usa `extract` per qualsiasi file strutturato che gli strumenti analizzano, come `.netrc`, JSON o YAML; il pattern deve contenere almeno un gruppo di cattura. Senza `extract`, Claude Code sostituisce l'intero contenuto del file con un valore sentinella, il che si adatta a un file che contiene un singolo segreto nudo e nient'altro.

~~505~~

506Per un file che contiene un JSON Web Token (JWT), imposta `decode: "jwt"` invece di, o insieme a, `extract`. `decode` richiede Claude Code v2.1.224 o successivo. Claude Code trova candidati JWT con un pattern integrato, o con il tuo pattern `extract` quando impostato, verifica che ogni candidato sia un JWT, e lo sostituisce con un token falso strutturalmente valido, quindi il codice che decodifica il token all'interno della sandbox continua a funzionare. Aggiungi `maskClaims` per mascherare solo i claim del payload di livello superiore nominati all'interno di ogni token verificato e lascia gli altri claim leggibili. Quando nessun candidato si verifica, o nessun claim nominato corrisponde, il campo `onExtractNoMatch` di seguito governa il risultato, come fa per un pattern che non corrisponde a nulla.

~~507~~

508Due campi opzionali affinano come si comporta la corrispondenza. Entrambi si applicano solo quando `mode` è `mask` e `extract` o `decode` è impostato. Su macOS, Claude Code applica le voci `mask` come `deny` prima che il pattern venga eseguito ogni volta che l'isolamento del filesystem è attivo, quindi questi campi, e i risultati di non corrispondenza di seguito, hanno effetto lì solo quando [l'isolamento del filesystem è disattivato](#disable-filesystem-isolation):

509 551

510* `onExtractNoMatch` controlla cosa accade quando la corrispondenza non trova nulla da mascherare nel file:552Senza `extract` o `decode`, Claude Code sostituisce l'intero file con un'unica sentinella, il che è adatto a un file che contiene un singolo segreto semplice. Usa i [campi `extract`, `decode`, `maskClaims`, `onExtractNoMatch` e `maskDuplicates`](/docs/it/settings-reference#sandbox-credentials-files) per controllare il mascheramento parziale e cosa succede quando il pattern non trova corrispondenze.

511 553

512 * `warn`, il valore predefinito, avverte e salta la voce, quindi i comandi in sandbox possono leggere il file reale senza mascheratura. Il valore predefinito si adatta alle credenziali che possono essere legittimamente assenti; se il segreto potrebbe essere presente ma il pattern potrebbe perderlo, usa `deny`554<Warning>

513 * `deny` rende il file illeggibile invece555 Quando la corrispondenza non trova nulla da mascherare, il valore predefinito di `onExtractNoMatch`, `warn`, salta la voce, quindi i comandi in sandbox possono leggere il file reale senza maschera. Su macOS, Claude Code applica le voci `mask` come `deny` prima che il pattern venga eseguito ogni volta che l'isolamento del filesystem è attivo, quindi i risultati in assenza di corrispondenze hanno effetto lì solo quando [l'isolamento del filesystem è disattivato](#disable-filesystem-isolation). Il valore predefinito è adatto a credenziali che potrebbero legittimamente essere assenti. Se il segreto potrebbe essere presente ma il pattern potrebbe non trovarlo, usa [`deny`](/docs/it/settings-reference#mask-fields-for-files).

514 * `error` interrompe il setup della sandbox finché non fissi la configurazione556</Warning>

~~515~~

516 Claude Code tratta `deny` come `error` ogni volta che il blocco di lettura non sarebbe applicato: quando [disabiliti l'isolamento del filesystem](#disable-filesystem-isolation), e quando una voce `filesystem.allowRead` da qualsiasi fonte di impostazioni riapre il percorso del file.

517* `maskDuplicates` sostituisce anche copie verbatim di ogni valore di credenziale mascherato, un'acquisizione `extract` o un token verificato `decode`, trovato al di fuori degli intervalli corrispondenti, per un segreto ripetuto dove la corrispondenza non raggiunge. Corrisponde a sottostringhe grezze, quindi un valore breve o comune sarebbe sostituito ovunque appaia; riservalo per segreti lunghi e ad alta entropia. Valore predefinito: false.

518 557

519`mask` si applica a un singolo file, quindi elenca ogni file di credenziale individualmente. Claude Code fallback a `deny` per una voce `mask` che non può mascherare in sicurezza: un percorso di directory, un pattern glob, un file più grande di 8 MiB, o un file che non è testo UTF-8. Scrivi le directory come voci esplicite `deny` invece; la tabella sotto [Quali impostazioni possono disabilitarlo](#which-settings-can-disable-it) copre se ogni forma fissa `filesystem.disabled` e come si comporta con l'isolamento del filesystem disattivato.558`mask` si applica a un singolo file, quindi elenca ogni file di credenziali singolarmente. Claude Code ripiega su `deny` per una voce `mask` che non può mascherare in modo sicuro: un percorso di directory, un pattern glob, un file più grande di 8 MiB o un file che non è testo UTF-8.

520 559

521<h2 id="how-sandboxing-works">560<h2 id="how-sandboxing-works">

522 Come funziona il sandboxing561 Come funziona il sandboxing

523</h2>562</h2>

524 563

525<h3 id="filesystem-isolation">564<h3 id="filesystem-isolation">

526 Isolamento del file system565 Isolamento del filesystem

527</h3>566</h3>

528 567

529Lo strumento Bash in sandbox limita l'accesso al file system a directory specifiche:568Lo strumento Bash in sandbox limita l'accesso al file system a directory specifiche:

530 569

531* **Comportamento di scrittura predefinito**: accesso in lettura e scrittura alla directory di lavoro corrente e alle sue sottodirectory, qualsiasi directory aggiunta con `--add-dir`, `/add-dir`, o [`permissions.additionalDirectories`](/docs/it/settings-reference#permissions-additionaldirectories), più la directory temporanea della sessione a cui `$TMPDIR` punta570* **Comportamento di scrittura predefinito**: accesso in lettura e scrittura alla directory di lavoro corrente e alle sue sottodirectory, a tutte le directory che hai aggiunto con `--add-dir`, `/add-dir` o [`permissions.additionalDirectories`](/docs/it/settings-reference#permissions-additionaldirectories), oltre alla directory temporanea per utente a cui punta `$TMPDIR`

532* **Comportamento di lettura predefinito**: accesso in lettura all'intero computer, ad eccezione di determinate directory negate. Nota che questo predefinito consente comunque la lettura di file di credenziali come `~/.aws/credentials` e `~/.ssh/`. Utilizza [`sandbox.credentials`](#protect-credentials) per bloccare le letture di questi file e annullare le variabili di ambiente segrete, oppure aggiungi i percorsi a `denyRead`.571* **Comportamento di lettura predefinito**: accesso in lettura all'intero computer, eccetto alcune directory negate. Questa impostazione predefinita consente comunque la lettura dei file di credenziali, quindi [proteggi le credenziali](#protect-credentials) che non vuoi che i comandi leggano.

533* **Blocco di lettura**: con [`permissions.blockReadsOutsideWorkingDirectories`](/docs/it/settings-reference#permissions-blockreadsoutsideworkingdirectories) attivo, i comandi in sandbox perdono anche l'accesso in lettura alla tua home directory e alle altre directory che contengono file utente, a parte i percorsi che [Comandi in sandbox sotto il blocco](/docs/it/settings-reference#sandboxed-commands-under-the-block) elenca. Quella sezione dice anche quando questa parte del blocco non si applica.572* **Blocco della lettura**: con [`permissions.blockReadsOutsideWorkingDirectories`](/docs/it/settings-reference#permissions-blockreadsoutsideworkingdirectories) attivo, i comandi in sandbox perdono anche l'accesso in lettura alla tua directory home e alle altre directory che contengono file utente, a parte i percorsi elencati in [Comandi in sandbox sotto il blocco](/docs/it/settings-reference#sandboxed-commands-under-the-block). Quella sezione indica anche quando questa parte del blocco non si applica.

534* **Accesso bloccato**: non è possibile modificare file al di fuori della directory di lavoro, delle directory aggiunte e della directory temporanea della sessione senza autorizzazione esplicita, inclusi file di configurazione shell come `~/.bashrc` e binari di sistema in `/bin/`573* **Worktree Git**: quando la directory di lavoro è un [worktree git collegato](/docs/it/worktrees), la sandbox consente anche le scritture nella directory `.git` condivisa del repository principale, in modo che comandi come `git commit` possano aggiornare i ref e l'indice. Le scritture in `hooks/` e `config` all'interno di quella directory restano negate.

535* **Git worktrees**: quando la directory di lavoro è un [git worktree collegato](/docs/it/worktrees), la sandbox consente anche scritture nella directory `.git` condivisa del repository principale in modo che comandi come `git commit` possano aggiornare i ref e l'indice. Le scritture in `hooks/` e `config` all'interno di quella directory rimangono negate.

536* **Configurabile**: definisci percorsi consentiti e negati personalizzati tramite le impostazioni

537 574

538Per saltare completamente l'isolamento del file system mantenendo l'isolamento della rete, imposta [`sandbox.filesystem.disabled`](#disable-filesystem-isolation).575Per saltare completamente l'isolamento del filesystem mantenendo l'isolamento di rete, imposta [`sandbox.filesystem.disabled`](#disable-filesystem-isolation).

539 576

540<h3 id="protected-paths">577<h3 id="protected-paths">

541 Percorsi protetti578 Percorsi protetti

542</h3>579</h3>

543 580

544All'interno delle directory in cui i comandi in sandbox possono scrivere, la sandbox nega comunque le scritture ai file da cui Claude Code carica la configurazione e il codice. Un comando che potrebbe modificare quei file potrebbe concedere a se stesso le autorizzazioni, oppure aggiungere un hook o un server MCP che Claude Code esegue al di fuori della sandbox. Il sistema di autorizzazione ha i suoi [percorsi protetti](/docs/it/permission-modes#protected-paths), che controllano cosa Claude Code approva prima che uno strumento venga eseguito; l'elenco della sandbox si applica a un comando che è già in esecuzione. Copre quattro gruppi di percorsi:581All'interno delle directory in cui i comandi in sandbox possono scrivere, la sandbox nega comunque le scritture nei file da cui Claude Code carica configurazione e codice. Un comando in grado di modificare quei file potrebbe concedersi dei permessi, oppure aggiungere un hook o un server MCP che Claude Code esegue fuori dalla sandbox. Il sistema dei permessi ha i propri [percorsi protetti](/docs/it/permission-modes#protected-paths), che controllano cosa Claude Code approva prima che uno strumento venga eseguito; l'elenco della sandbox si applica a un comando già in esecuzione. Copre quattro gruppi di percorsi:

545 582

546* **Nella directory di lavoro e nelle directory sopra di essa**: i file di impostazioni `.claude`, le directory `.claude/skills`, `.claude/agents`, `.claude/commands` e `.claude/hooks`, `.mcp.json`, e i file che Claude Code esegue autonomamente, come `.claude/workflows` e `.claude/scheduled_tasks.json`583* **Nella tua directory di lavoro e nelle directory superiori**: i file di impostazioni `.claude`, le directory `.claude/skills`, `.claude/agents`, `.claude/commands` e `.claude/hooks`, `.mcp.json` e i file che Claude Code esegue autonomamente, come `.claude/workflows` e `.claude/scheduled_tasks.json`

547* **Solo nella directory di lavoro**: file di avvio shell come `.bashrc` e `.zshrc`, `.gitconfig`, le directory `.vscode` e `.idea`, e `hooks` e `config` all'interno di `.git`584* **Solo nella tua directory di lavoro**: i file di avvio della shell come `.bashrc` e `.zshrc`, `.gitconfig`, le directory `.vscode` e `.idea`, e `hooks` e `config` all'interno di `.git`

548* **File che trasformerebbero la directory di lavoro in un repository git bare**: `HEAD`, `objects` e `refs` al livello superiore, più `config` e `hooks` lì quando un `HEAD` si trova accanto a loro. Un file denominato `config` è negato anche senza `HEAD`. Su Linux e WSL2, la sandbox elimina un file `HEAD` di livello superiore o una directory `objects` o `refs` che appare mentre un comando in sandbox è in esecuzione585* **File che trasformerebbero la tua directory di lavoro in un repository git bare**: `HEAD`, `objects` e `refs` al livello superiore, più le voci `config` e `hooks` esistenti in quel punto quando accanto a esse si trova un `HEAD`. Un file chiamato `config` viene negato anche in assenza di `HEAD`. Su Linux e WSL2, la sandbox elimina un file `HEAD` o una directory `objects` o `refs` di livello superiore che compare mentre un comando in sandbox è in esecuzione

549* **In `~/.claude`, o nella directory a cui `CLAUDE_CONFIG_DIR` punta**: la maggior parte dei suoi contenuti, più `~/.claude.json` e l'archivio credenziali `.credentials.json`586* **In `~/.claude`, o nella directory a cui punta `CLAUDE_CONFIG_DIR`**: la maggior parte del suo contenuto, più `~/.claude.json` e l'archivio delle credenziali `.credentials.json`

550 587

551Se un symlink appare al percorso di un file di impostazioni protetto durante la sessione, la sandbox nega anche le scritture al file a cui punta, a partire dal comando successivo.588Se durante la sessione compare un collegamento simbolico nel percorso di un file di impostazioni protetto, la sandbox nega anche le scritture nel file a cui punta, a partire dal comando successivo.

552 589

553Non c'è modo di esentare uno di questi percorsi: una voce `allowWrite` o una regola di autorizzazione `Edit` che copre il percorso non solleva la protezione. L'unico modo per disattivare la protezione è [`filesystem.disabled`](#disable-filesystem-isolation), che disattiva l'isolamento del file system per ogni percorso. Per vedere la maggior parte di questi percorsi risolti per la tua macchina, esegui `/sandbox` e apri la scheda **Config**, che li elenca sotto **Denied within allowed**, mescolati con le tue voci `denyWrite` personali.590Non c'è modo di esentare uno di questi percorsi: una voce `allowWrite` o una regola di consenso `Edit` che copre il percorso non rimuove la protezione. L'unico modo per disattivare la protezione è [`filesystem.disabled`](#disable-filesystem-isolation), che disattiva l'isolamento del filesystem per ogni percorso. Per vedere la maggior parte di questi percorsi risolti per la tua macchina, esegui `/sandbox` e apri la scheda **Config**, che li elenca sotto **Denied within allowed**, insieme alle tue voci `denyWrite`.

554 591

555Se `git merge` o `git checkout` fallisce con `unable to unlink old` su uno di questi percorsi, vedi [Troubleshooting](#troubleshooting).592Se `git merge` o `git checkout` non riesce con `unable to unlink old` su uno di questi percorsi, consulta [Un comando git non riesce con `unable to unlink old`](#a-git-command-fails-with-unable-to-unlink-old).

556 593

557<h3 id="network-isolation">594<h3 id="network-isolation">

558 Isolamento della rete595 Isolamento di rete

559</h3>596</h3>

560 597

561L'accesso alla rete è controllato tramite un server proxy in esecuzione al di fuori della sandbox:598Un comando in sandbox non ha un accesso diretto alla rete:

562 599

563* **Restrizioni di dominio**: Claude Code non pre-consente alcun dominio per impostazione predefinita. La prima volta che un comando ha bisogno di un nuovo dominio, Claude Code richiede l'approvazione; in [modalità automatica](/docs/it/permission-modes#eliminate-prompts-with-auto-mode), Claude Code invece nomina gli host di cui un comando ha bisogno sul comando stesso, per [Domini consentiti per comando](#per-command-allowed-domains-in-auto-mode).600* **Linux e WSL2**: il comando viene eseguito in un namespace di rete separato che non ha alcuna connessione alla tua rete

564* **Scelte di approvazione**: se scegli Sì quando richiesto, Claude Code consente l'host per il resto della sessione corrente e non richiede di nuovo il prompt per le connessioni successive allo stesso host. Se scegli "Sì, e non chiedere di nuovo", Claude Code salva una regola di autorizzazione `WebFetch(domain:...)` alle tue [impostazioni locali](/docs/it/permissions#permission-system), in modo che l'host rimanga consentito nelle sessioni future.601* **macOS**: il framework sandbox Seatbelt blocca per impostazione predefinita le connessioni diverse da quella verso il proxy della sandbox

565* **Domini pre-consentiti**: pre-consenti i domini con [`allowedDomains`](/docs/it/settings-reference#sandbox-network-alloweddomains) per evitare completamente il prompt. Claude Code pre-consente anche i domini dalle regole di autorizzazione `WebFetch(domain:...)`, come descritto in [Regole di autorizzazione](#permission-rules).

566* **Allowlist rigoroso**: se imposti [`strictAllowlist`](/docs/it/settings-reference#sandbox-network-strictallowlist) a `true` nelle impostazioni utente, gestite o CLI `--settings`, Claude Code nega ai comandi in sandbox l'accesso a qualsiasi host al di fuori dell'allowlist invece di richiedere. L'allowlist è lo stesso contro cui la sandbox altrimenti richiede: `allowedDomains` più domini dalle regole di autorizzazione `WebFetch(domain:...)`, oppure solo le voci di impostazioni gestite quando `allowManagedDomainsOnly` è impostato. Claude Code applica questo solo ai comandi in sandbox; gli strumenti in-process come `WebFetch` seguono comunque le loro [regole di autorizzazione](#permission-rules). Impostarlo nel `.claude/settings.json` o `.claude/settings.local.json` di un repository non ha effetto. Richiede Claude Code v2.1.219 o successivo.

567* **Blocco gestito**: se [`allowManagedDomainsOnly`](/docs/it/settings-reference#sandbox-network-allowmanageddomainsonly) è impostato nelle impostazioni gestite, i domini non consentiti vengono bloccati automaticamente invece di richiedere, e solo `allowedDomains` e le regole di autorizzazione `WebFetch(domain:...)` dalle impostazioni gestite vengono rispettati.

568* **Proxy aziendale**: quando la tua rete richiede che il traffico in uscita passi attraverso un proxy aziendale, imposta `HTTPS_PROXY`, `HTTP_PROXY` e `NO_PROXY` come [configurazione proxy](/docs/it/network-config#proxy-configuration) descrive, nel blocco `env` delle tue impostazioni in modo che gli [agenti in background](/docs/it/network-config#set-network-variables-in-settings-not-the-shell) li ottengano anche, oppure nell'ambiente da cui avvii Claude Code. Claude Code applica l'allowlist di dominio e quindi esegue il tunneling delle connessioni consentite attraverso quel proxy upstream.

569* **Supporto proxy personalizzato**: gli utenti avanzati possono implementare regole personalizzate sul traffico in uscita

570* **Copertura completa**: le restrizioni si applicano a tutti gli script, programmi e sottoprocessi generati dai comandi

571 602

572In una regola `WebFetch(domain:...)`, la sandbox rispetta due forme di wildcard: un `*.` iniziale, come `*.example.com`, e un `*` nudo. La forma `*` nuda richiede Claude Code v2.1.186 o successivo. Un wildcard in qualsiasi altra posizione, come `WebFetch(domain:example.*)`, corrisponde comunque ai fetch ma non ha effetto sui comandi in sandbox.603Claude Code esegue il proxy della sandbox sulla tua macchina, fuori dalla sandbox, e indirizza i comandi verso di esso con `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY` e le variabili d'ambiente correlate. Il proxy confronta il nome host di ogni connessione con i tuoi domini consentiti e negati.

604

605Ciò che uno strumento può raggiungere dipende dal fatto che utilizzi o meno il proxy:

606

607* **Strumenti che leggono le variabili del proxy**: `curl`, `npm`, `git` su HTTPS e strumenti simili si connettono una volta che il loro host è consentito. Una voce `allowedDomains` senza porta consente ogni porta su quell'host

608* **Strumenti che ignorano le variabili del proxy**: `ssh` semplice, la maggior parte dei driver di database e strumenti simili non possono connettersi, nemmeno a un host consentito. Consulta [Un client di database o un altro strumento non HTTP non riesce a raggiungere un host consentito](#a-database-client-or-other-non-http-tool-fails-to-reach-an-allowed-host)

609* **Tutto ciò che non è TCP**: UDP, HTTP/3 su QUIC e gli strumenti ICMP come `ping` non possono uscire dalla sandbox

610

611Le seguenti impostazioni e comportamenti controllano quali host il proxy consente:

612

613* **Restrizioni sui domini**: i tuoi domini consentiti all'inizio sono vuoti. [Host al di fuori dei tuoi domini consentiti](#hosts-outside-your-allowed-domains) descrive cosa succede la prima volta che un comando ha bisogno di un nuovo dominio.

614* **Scelte di approvazione**: se scegli Yes quando ti viene chiesto, Claude Code consente l'host per il resto della sessione corrente. Se scegli "Yes, and don't ask again", Claude Code salva una regola di consenso `WebFetch(domain:...)` nelle tue [impostazioni locali](/docs/it/permissions#permission-system), così l'host resta consentito nelle sessioni future. Mentre la sandbox è [richiesta dall'amministratore](#repository-settings-under-an-admin-required-sandbox), Claude Code salva la regola nelle tue impostazioni utente, dove si applica in ogni progetto.

615* **Domini pre-consentiti**: pre-consenti i domini con [`allowedDomains`](/docs/it/settings-reference#sandbox-network-alloweddomains) per evitare del tutto la richiesta di conferma. Claude Code pre-consente anche i domini provenienti dalle regole di consenso `WebFetch(domain:...)`, come descritto in [Regole di permesso](#permission-rules).

616* **Allowlist rigorosa**: se imposti [`strictAllowlist`](/docs/it/settings-reference#sandbox-network-strictallowlist) su `true` nelle impostazioni utente, gestite o CLI `--settings`, Claude Code nega ai comandi in sandbox l'accesso a qualsiasi host al di fuori dell'allowlist invece di chiedere. L'allowlist è composta da `allowedDomains` più i domini delle regole di consenso `WebFetch(domain:...)`, oppure solo dalle voci delle impostazioni gestite quando è impostato `allowManagedDomainsOnly`. [Blocchi che si applicano senza una sandbox richiesta dall'amministratore](#locks-that-apply-without-an-admin-required-sandbox) descrive le voci di un repository. Claude Code applica questa impostazione solo ai comandi in sandbox; gli strumenti in-process come `WebFetch` seguono comunque le loro [regole di permesso](#permission-rules). Impostarla nel file `.claude/settings.json` o `.claude/settings.local.json` di un repository non ha alcun effetto. Richiede Claude Code v2.1.219 o successivo.

617* **Blocco gestito**: se [`allowManagedDomainsOnly`](/docs/it/settings-reference#sandbox-network-allowmanageddomainsonly) è impostato nelle impostazioni gestite, i domini non consentiti vengono bloccati automaticamente invece di chiedere, e vengono rispettate solo le regole di consenso `allowedDomains` e `WebFetch(domain:...)` provenienti dalle impostazioni gestite.

618* **Proxy aziendale**: quando la tua rete richiede che il traffico in uscita passi attraverso un proxy aziendale, imposta `HTTPS_PROXY`, `HTTP_PROXY` e `NO_PROXY` come descritto in [configurazione del proxy](/docs/it/network-config#proxy-configuration), nel blocco `env` delle tue impostazioni in modo che anche gli [agenti in background](/docs/it/network-config#set-network-variables-in-settings-not-the-shell) le ricevano, oppure nell'ambiente da cui avvii Claude Code. Claude Code applica l'allowlist dei domini e poi instrada le connessioni consentite attraverso quel proxy upstream. Funzionano gli URL di proxy `http://` e `https://`, con l'autenticazione di base nell'URL se ti serve.

619

620In una regola `WebFetch(domain:...)`, la sandbox rispetta due forme di carattere jolly: un `*.` iniziale, come `*.example.com`, e un `*` da solo. La forma `*` da solo richiede Claude Code v2.1.186 o successivo. Un carattere jolly in qualsiasi altra posizione, come `WebFetch(domain:example.*)`, corrisponde comunque ai fetch ma non ha alcun effetto sui comandi in sandbox.

573 621

574<Note>622<Note>

575 Il proxy integrato applica l'allowlist in base al nome host richiesto e, per impostazione predefinita, non termina o ispeziona il traffico TLS. L'impostazione sperimentale [`network.tlsTerminate`](/docs/it/settings-reference#sandbox-network-tlsterminate), disponibile in Claude Code v2.1.199 e successivo, fa sì che il proxy integrato termini TLS stesso, che le voci di credenziali [`mask`](#mask-credentials) richiedono. Vedi [Limitazioni di sicurezza](#security-limitations) per le implicazioni dell'impostazione predefinita, e [Configurazione proxy personalizzata](#custom-proxy-configuration) se il tuo modello di minaccia richiede l'ispezione TLS.623 Il proxy integrato applica l'allowlist in base al nome host richiesto e, per impostazione predefinita, non termina né ispeziona il traffico TLS. L'impostazione sperimentale [`network.tlsTerminate`](/docs/it/settings-reference#sandbox-network-tlsterminate), disponibile in Claude Code v2.1.199 e successivi, fa sì che il proxy integrato termini esso stesso il TLS, cosa richiesta dalle [voci di credenziali `mask`](#mask-credentials). Consulta [Limitazioni di sicurezza](#security-limitations) per le implicazioni del comportamento predefinito e [Configurazione del proxy personalizzato](#custom-proxy-configuration) se il tuo modello di minaccia richiede l'ispezione TLS.

576</Note>624</Note>

577 625

626<h4 id="hosts-outside-your-allowed-domains">

627 Host al di fuori dei tuoi domini consentiti

628</h4>

629

630Quando un comando in sandbox si connette a un host che non è nei tuoi domini consentiti, il comando resta nella sandbox e attende una decisione. In una sessione interattiva nel terminale, la decisione dipende dalla tua modalità di permesso:

631

632| Modalità di permesso | Cosa succede alla connessione |

633| :- | :- |

634| Modalità `bypassPermissions` e plan mode con [bypass dei permessi disponibile](/docs/it/permission-modes#skip-all-checks-with-bypasspermissions-mode) | Consentita senza richiesta di conferma |

635| Modalità manuale, modalità `acceptEdits` e plan mode negli altri casi | Ricevi una richiesta di conferma |

636| Modalità auto | Rifiutata a meno che il comando non abbia [elencato l'host](#per-command-allowed-domains-in-auto-mode) e il classificatore non abbia approvato l'elenco |

637| Modalità `dontAsk` | Rifiutata |

638

639Con [`strictAllowlist`](/docs/it/settings-reference#sandbox-network-strictallowlist) o [`allowManagedDomainsOnly`](/docs/it/settings-reference#sandbox-network-allowmanageddomainsonly) attivo, il proxy integrato della sandbox rifiuta la connessione in ogni modalità di permesso. In modalità `bypassPermissions`, gli host al di fuori dei tuoi domini consentiti sono consentiti a meno che una di queste impostazioni non sia attiva. [La via di fuga del nuovo tentativo fuori dalla sandbox](#the-unsandboxed-retry-escape-hatch) spiega quando un comando può uscire dalla sandbox in quella modalità. Anche una connessione a un host presente in [`deniedDomains`](/docs/it/settings-reference#sandbox-network-denieddomains) viene rifiutata in ogni modalità di permesso.

640

641<h4 id="hostnames-that-resolve-to-local-addresses">

642 Nomi host che si risolvono in indirizzi locali

643</h4>

644

645Dopo che un nome host ha superato l'allowlist, il proxy della sandbox lo risolve e rifiuta la connessione quando il nome si risolve solo in indirizzi locali. Gli indirizzi locali includono gli indirizzi di loopback come `127.0.0.1`, gli indirizzi link-local come l'endpoint dei metadati cloud `169.254.169.254` e gli indirizzi assegnati alla tua macchina. I nomi `localhost` e `*.localhost` possono risolversi in loopback.

646

647Un nome host intranet consentito che si risolve in un intervallo privato come `10.0.0.0/8` si connette. Per consentire a un nome di risolversi in un indirizzo rifiutato, aggiungi quell'indirizzo IP a `allowedDomains`, ad esempio `"127.0.0.1:8080"`.

648

649Il controllo si applica ai nomi host. Per una connessione a un indirizzo IP decidono i tuoi domini consentiti e la modalità di permesso. Il proxy salta il controllo anche per le connessioni che invia attraverso un proxy aziendale upstream, perché è quel proxy a risolvere il nome.

650

578<h4 id="per-command-allowed-domains-in-auto-mode">651<h4 id="per-command-allowed-domains-in-auto-mode">

579 Domini consentiti per comando in modalità automatica652 Domini consentiti per comando in modalità auto

580</h4>653</h4>

581 654

582In [modalità automatica](/docs/it/permission-modes#eliminate-prompts-with-auto-mode) con sandboxing attivo, Claude nomina gli host di cui un comando ha bisogno sul comando stesso invece di attivare un'approvazione di rete per ogni connessione. Ogni comando Bash, PowerShell o [Monitor](/docs/it/tools-reference#monitor-tool) che viene eseguito nella sandbox può portare un elenco di host oltre l'allowlist della sandbox: un dominio come `registry.npmjs.org`, un wildcard come `*.pythonhosted.org`, o un indirizzo IP, ciascuno con una porta opzionale `:port`. Il classificatore esamina gli host insieme al comando. Richiede Claude Code v2.1.271 o successivo.655In [modalità auto](/docs/it/permission-modes#eliminate-prompts-with-auto-mode) con il sandboxing attivo, Claude indica gli host di cui un comando ha bisogno sul comando stesso, invece di attivare un'approvazione di rete per ogni connessione. Ogni comando Bash, PowerShell o [Monitor](/docs/it/tools-reference#monitor-tool) eseguito nella sandbox può includere un elenco di host oltre all'allowlist della sandbox: un dominio come `registry.npmjs.org`, un carattere jolly come `*.pythonhosted.org` o un indirizzo IP, ciascuno con un `:port` facoltativo. Il classificatore esamina gli host insieme al comando. Richiede Claude Code v2.1.271 o successivo.

583 656

584Un elenco approvato apre quegli host solo per quel comando, finché è in esecuzione. Nulla viene aggiunto agli host consentiti della sessione o alle tue impostazioni; il comando successivo nomina i suoi host.657Un elenco approvato apre quegli host solo per quel singolo comando, per tutta la durata della sua esecuzione. Non viene aggiunto nulla agli host consentiti della tua sessione né alle tue impostazioni; il comando successivo indica i propri host.

585 658

586Un comando che porta host va al classificatore invece di essere approvato da una regola di autorizzazione o dalla [modalità auto-allow](#sandbox-modes) della sandbox. Se una [regola ask](/docs/it/permissions#manage-permissions) forza un prompt per il comando, la finestra di dialogo di autorizzazione nel tuo terminale elenca gli host accanto ad esso, e approvarvi copre entrambi.659Un comando che include host viene inviato al classificatore invece di essere approvato da una regola di permesso o dalla [modalità di consenso automatico](#sandbox-modes) della sandbox. Se una [regola ask](/docs/it/permissions#manage-permissions) impone una richiesta di conferma per il comando, la finestra di dialogo dei permessi nel tuo terminale elenca gli host accanto a esso, e approvare lì copre entrambi.

587 660

588Un elenco per comando amplia solo ciò che la sandbox nega per impostazione predefinita. Le voci [`deniedDomains`](/docs/it/settings-reference#sandbox-network-denieddomains) bloccano comunque. Quando [`strictAllowlist`](/docs/it/settings-reference#sandbox-network-strictallowlist) o [`allowManagedDomainsOnly`](/docs/it/settings-reference#sandbox-network-allowmanageddomainsonly) blocca l'allowlist, Claude Code rifiuta gli elenchi per comando.661Un elenco per comando amplia solo ciò che la sandbox nega per impostazione predefinita. Le voci di [`deniedDomains`](/docs/it/settings-reference#sandbox-network-denieddomains) continuano a bloccare. Quando [`strictAllowlist`](/docs/it/settings-reference#sandbox-network-strictallowlist) o [`allowManagedDomainsOnly`](/docs/it/settings-reference#sandbox-network-allowmanageddomainsonly) blocca l'allowlist, Claude Code rifiuta gli elenchi per comando.

589 662

590Mentre gli elenchi per comando si applicano, Claude Code rifiuta una connessione a un host che nessun comando approvato ha elencato, senza un prompt o un controllo del classificatore. Il rifiuto nomina l'host nel risultato del comando, e Claude esegue di nuovo il comando con l'host aggiunto.663Mentre si applicano gli elenchi per comando, Claude Code rifiuta una connessione a un host che nessun comando approvato ha elencato, senza richiesta di conferma né controllo del classificatore. Il rifiuto indica l'host nel risultato del comando, e Claude riesegue il comando con l'host aggiunto.

591 664

592<h4 id="ipv6-addresses-in-domain-lists">665<h4 id="ipv6-addresses-in-domain-lists">

593 Indirizzi IPv6 negli elenchi di dominio666 Indirizzi IPv6 negli elenchi di domini

594</h4>667</h4>

595 668

596Gli elenchi di dominio della sandbox sono `allowedDomains`, `deniedDomains` e le regole `WebFetch(domain:...)` che li alimentano. Per corrispondere a un indirizzo IPv6 in uno qualsiasi di essi, scrivi il letterale tra parentesi: `"[::1]"` corrisponde a quell'indirizzo su ogni porta, e `"[::1]:443"` lo corrisponde sulla porta 443 solo. Scrivi la porta come numero da 1 a 65535 senza zeri iniziali. La forma tra parentesi richiede Claude Code v2.1.229 o successivo. Prima di v2.1.229, quando il testo dopo l'ultimo due punti di una voce non tra parentesi era un numero di porta, Claude Code lo leggeva come uno, quindi `::1:443` denominava l'indirizzo `::1` sulla porta 443.669Per far corrispondere un indirizzo IPv6 in `allowedDomains`, `deniedDomains` o in una regola `WebFetch(domain:...)`, scrivi l'indirizzo tra parentesi quadre: `"[::1]"` corrisponde a quell'indirizzo su ogni porta, e `"[::1]:443"` corrisponde solo sulla porta 443. La forma tra parentesi quadre richiede Claude Code v2.1.229 o successivo.

~~597~~

598Quando scegli "Sì, e non chiedere di nuovo" al prompt di approvazione della rete per un indirizzo IPv6, Claude Code salva la regola `WebFetch(domain:...)` con l'indirizzo tra parentesi, in modo che la regola continui a corrispondere all'indirizzo nelle sessioni future.

599 670

600Una voce non tra parentesi con due o più due punti è ambigua: `::1:443` è sia un indirizzo IPv6 completo che un indirizzo seguito da una porta. Claude Code applica le ortografie ambigue in modo conservativo invece di indovinare quale lettura intendevi:671Una voce senza parentesi come `::1:443` è ambigua tra un indirizzo e un indirizzo con una porta:

601 672

602* **Elenchi di negazione**: Claude Code nega ogni lettura che la voce analizza come, quindi qualunque lettura intendevi è bloccata. Per una voce senza lettura analizzabile, Claude Code non blocca nulla.673* **Elenchi di negazione**: Claude Code nega ogni interpretazione in cui la voce può essere analizzata, quindi qualunque interpretazione intendessi viene bloccata. Per una voce senza alcuna interpretazione analizzabile, Claude Code non blocca nulla

603* **Elenchi di consentimento**: Claude Code non consente mai più di quello che hai scritto. Riscrive una voce ambigua alla sua lettura host-e-porta quando quella lettura analizza in modo pulito, e può eliminare completamente la voce piuttosto che ampliare l'allowlist.674* **Elenchi di consenso**: Claude Code non consente mai più di quanto hai scritto. Riscrive una voce ambigua nella sua interpretazione host e porta quando tale interpretazione viene analizzata correttamente, e può eliminare completamente la voce anziché ampliare l'allowlist

604 675

605Esegui `claude doctor` nel tuo terminale per trovare le voci interessate: l'avviso `Sandbox network domain entries have unreliable spellings` nomina fino a tre di esse e conta il resto. Riscrivi ognuna nella forma tra parentesi per cancellare l'avviso. L'avviso nomina anche voci la cui ortografia è inaffidabile per altri motivi, come `@`, caratteri di percorso o query, o wildcard all'interno di parentesi.676Per trovare le voci ambigue, esegui `claude doctor` nel tuo terminale e cerca l'avviso `Sandbox network domain entries have unreliable spellings`. Riscrivi ciascuna voce ambigua nella forma tra parentesi quadre.

606 677

607<h3 id="os-level-enforcement">678<h3 id="os-level-enforcement">

608 Applicazione a livello del sistema operativo679 Applicazione a livello di sistema operativo

609</h3>680</h3>

610 681

611Lo strumento Bash in sandbox utilizza primitive di sicurezza del sistema operativo:682Lo strumento Bash in sandbox utilizza le primitive di sicurezza del sistema operativo:

612 683

613* **macOS**: utilizza Seatbelt per l'applicazione della sandbox684* **macOS**: utilizza Seatbelt per l'applicazione della sandbox

614* **Linux**: utilizza [bubblewrap](https://github.com/containers/bubblewrap) per l'isolamento685* **Linux**: utilizza [bubblewrap](https://github.com/containers/bubblewrap) per l'isolamento

615* **WSL2**: utilizza bubblewrap, come Linux686* **WSL2**: utilizza bubblewrap, come Linux

616 687

617WSL1 non è supportato perché bubblewrap richiede funzionalità del kernel disponibili solo in WSL2.688Puoi anche eseguire il pacchetto [`@anthropic-ai/sandbox-runtime`](https://github.com/anthropics/sandbox-runtime) in modo autonomo per incapsulare il processo di Claude Code. Consulta [Sandbox runtime](/docs/it/sandbox-environments#sandbox-runtime).

~~618~~

619Questi stessi primitivi sono disponibili come pacchetto standalone [`@anthropic-ai/sandbox-runtime`](https://github.com/anthropic-experimental/sandbox-runtime), che la pagina [Sandbox environments](/docs/it/sandbox-environments#sandbox-runtime) copre come approccio separato per avvolgere l'intero processo di Claude Code.

620 689

621<h2 id="how-sandboxing-relates-to-permissions-and-permission-modes">690<h2 id="how-sandboxing-relates-to-permissions-and-permission-modes">

622 Come il sandboxing si relaziona alle autorizzazioni e alle modalità di autorizzazione691 Come il sandboxing si relaziona alle autorizzazioni e alle modalità di autorizzazione

674Gli amministratori possono richiedere il sandboxing per ogni utente, impedire agli sviluppatori di ampliare la politica e instradare il traffico sandbox attraverso un proxy aziendale.743Gli amministratori possono richiedere il sandboxing per ogni utente, impedire agli sviluppatori di ampliare la politica e instradare il traffico sandbox attraverso un proxy aziendale.

675 744

676<h3 id="enforce-sandboxing-with-managed-settings">745<h3 id="enforce-sandboxing-with-managed-settings">

677 Enforce sandboxing with managed settings746 Applica il sandboxing con le impostazioni gestite

678</h3>747</h3>

679 748

680Per richiedere la sandbox per ogni sviluppatore, fornisci le chiavi `sandbox` tramite [impostazioni gestite](/docs/it/managed-settings#delivery-mechanisms), sia come file gestito dal tuo MDM che tramite [impostazioni gestite dal server](/docs/it/server-managed-settings) su claude.ai.749Per richiedere la sandbox per ogni sviluppatore, fornisci le chiavi `sandbox` tramite [impostazioni gestite](/docs/it/managed-settings#delivery-mechanisms), sia come file gestito dal tuo MDM che tramite [impostazioni gestite dal server](/docs/it/server-managed-settings) su claude.ai.

681 750

682La seguente configurazione di impostazioni gestite abilita la sandbox, rifiuta di avviare Claude Code se la sandbox non può inizializzarsi e impedisce al modello di riprovare i comandi al di fuori della sandbox:751La seguente configurazione di impostazioni gestite abilita la sandbox, rifiuta di avviare Claude Code quando la piattaforma non è supportata o manca una dipendenza e impedisce al modello di riprovare i comandi al di fuori della sandbox:

683 752

684```json theme={null}753```json theme={null}

685{754{

693 762

694Le due chiavi oltre `enabled` controllano cosa succede quando la sandbox non può eseguire un comando:763Le due chiavi oltre `enabled` controllano cosa succede quando la sandbox non può eseguire un comando:

695 764

696* **`failIfUnavailable`**: una dipendenza mancante come bubblewrap su Linux blocca l'avvio di Claude Code piuttosto che mostrare un avviso e ricadere nell'esecuzione non sandboxata765* **`failIfUnavailable`**: una dipendenza mancante come bubblewrap su Linux blocca l'avvio di Claude Code piuttosto che ricadere nell'esecuzione non sandboxata

697* **`allowUnsandboxedCommands: false`**: Claude Code ignora l'escape hatch `dangerouslyDisableSandbox`, quindi quando un comando fallisce sotto la sandbox, Claude non può riprovarlo senza sandbox766* **`allowUnsandboxedCommands: false`**: Claude Code ignora l'escape hatch `dangerouslyDisableSandbox`, quindi quando un comando fallisce sotto la sandbox, Claude non può riprovarlo senza sandbox

698 767

699Due aggiunte meritano considerazione insieme a loro. Aggiungi `excludedCommands` per qualsiasi strumento approvato dall'organizzazione che deve essere eseguito senza isolamento. Aggiungi voci [`sandbox.credentials`](#protect-credentials) per directory di credenziali come `~/.aws` e `~/.ssh` e per variabili di ambiente segrete, poiché la politica di lettura predefinita le consente comunque.768Valuta queste aggiunte insieme a loro:

769

770* Aggiungi `excludedCommands` per qualsiasi strumento approvato dall'organizzazione che deve essere eseguito senza isolamento, perché questa configurazione [impedisce alle impostazioni di un repository di portare comandi fuori dalla sandbox](#repository-settings-under-an-admin-required-sandbox)

771* Aggiungi voci [`sandbox.credentials`](#protect-credentials) per directory di credenziali come `~/.aws` e `~/.ssh` e per variabili d'ambiente segrete, poiché la politica di lettura predefinita le consente comunque

700 772

701Questa configurazione sandboxa i comandi che Claude esegue. Uno sviluppatore può comunque digitare un comando al [prompt della modalità shell con `!`](/docs/it/interactive-mode#shell-mode-with-prefix) ed eseguirlo al di fuori della sandbox, con lo stesso accesso che ha già in qualsiasi terminale al di fuori di Claude Code. Vedi [L'escape hatch di riprovazione senza sandbox](#the-unsandboxed-retry-escape-hatch) per le sessioni in cui i comandi digitati vengono eseguiti in sandbox.773Questa configurazione sandboxa i comandi che Claude esegue. Uno sviluppatore può comunque digitare un comando al [prompt della modalità shell con `!`](/docs/it/interactive-mode#shell-mode-with-prefix) ed eseguirlo al di fuori della sandbox, con lo stesso accesso che ha già in qualsiasi terminale al di fuori di Claude Code. Vedi la [modalità sandbox rigorosa](#turn-off-the-retry-with-strict-sandbox-mode) per le sessioni in cui i comandi digitati vengono eseguiti in sandbox.

702 774

703La sandbox non viene eseguita su Windows nativo, quindi se la tua flotta include host Windows, limita questa configurazione a macOS e Linux o fai in modo che quegli utenti eseguano Claude Code all'interno di WSL2 o di un container.775La sandbox non viene eseguita su Windows nativo, quindi con `failIfUnavailable` impostato, Claude Code si chiude all'avvio su quelle macchine. Se la tua flotta include host Windows, puoi:

776

777* **Distribuire la configurazione in base al sistema operativo**: distribuiscila tramite il tuo MDM o come [file di impostazioni gestite](/docs/it/managed-settings#delivery-mechanisms) solo sulle macchine macOS e Linux. Le [impostazioni gestite dal server](/docs/it/server-managed-settings#current-limitations) si applicano a tutti gli utenti dell'organizzazione

778* **Spostare gli utenti Windows in un ambiente supportato**: fai in modo che eseguano Claude Code all'interno di WSL2 o di un container

704 779

705<h3 id="keep-developers-from-widening-the-policy">780<h3 id="keep-developers-from-widening-the-policy">

706 Keep developers from widening the policy781 Impedisci agli sviluppatori di ampliare la politica

707</h3>782</h3>

708 783

709Per chiavi booleane come `enabled` e `failIfUnavailable`, Claude Code utilizza il valore gestito e ignora qualsiasi cosa uno sviluppatore imposti localmente. Per chiavi array come `excludedCommands` e `allowRead`, Claude Code unisce le voci da ogni ambito che la sessione carica, quindi uno sviluppatore può aggiungere voci che ampliano la politica.784Quando le impostazioni gestite impostano una chiave booleana come `enabled` o `failIfUnavailable`, Claude Code utilizza il valore gestito e ignora qualsiasi cosa uno sviluppatore imposti localmente. Per chiavi array come `allowRead`, Claude Code fa il merge delle voci dagli ambiti che la sessione carica, quindi uno sviluppatore può aggiungere voci che ampliano la politica a meno che un blocco non copra quella chiave.

785

786A meno che non siano impostate dalle impostazioni gestite, le impostazioni utente di uno sviluppatore o `--settings` possono attivare le seguenti chiavi. Può farlo anche il `.claude/settings.json` di un repository, a meno che la sandbox non sia [richiesta dall'amministratore](#repository-settings-under-an-admin-required-sandbox). Ognuna indebolisce la sandbox, quindi impostala su `false` nelle impostazioni gestite se non vuoi che venga usata:

787

788* [`enableWeakerNestedSandbox`](/docs/it/settings-reference#sandbox-enableweakernestedsandbox)

789* [`enableWeakerNetworkIsolation`](/docs/it/settings-reference#sandbox-enableweakernetworkisolation)

790* [`network.allowAllUnixSockets`](/docs/it/settings-reference#sandbox-network-allowallunixsockets)

791* [`network.allowLocalBinding`](/docs/it/settings-reference#sandbox-network-allowlocalbinding)

792* [`allowAppleEvents`](/docs/it/settings-reference#sandbox-allowappleevents), che un repository non può attivare

793

794Imposta `allowManagedReadPathsOnly` su `true` nelle impostazioni gestite in modo che solo le voci `allowRead` dalle impostazioni gestite vengano rispettate. Questo impedisce agli sviluppatori di ampliare l'accesso in lettura oltre i percorsi approvati dall'organizzazione.

710 795

711Imposta `allowManagedReadPathsOnly` su `true` nelle impostazioni gestite in modo che solo le voci `allowRead` dalle impostazioni gestite vengono rispettate. Questo impedisce agli sviluppatori di ampliare l'accesso in lettura oltre i percorsi approvati dall'organizzazione. Per bloccare i domini di rete ai valori gestiti allo stesso modo, imposta [`allowManagedDomainsOnly`](/docs/it/settings-reference#sandbox-network-allowmanageddomainsonly).796Per bloccare i domini di rete ai valori gestiti allo stesso modo, imposta [`allowManagedDomainsOnly`](/docs/it/settings-reference#sandbox-network-allowmanageddomainsonly). Con il blocco attivo, solo le impostazioni gestite possono impostare una [porta proxy](#custom-proxy-configuration).

712 797

713Quando le impostazioni gestite configurano `sandbox.filesystem` o elencano qualsiasi voce `sandbox.credentials.files` con `"mode": "deny"`, solo le impostazioni gestite possono impostare [`filesystem.disabled`](#disable-filesystem-isolation), quindi gli sviluppatori non possono disattivare le restrizioni del filesystem distribuite dall'amministratore. Se una voce `mask` fissa la chiave dipende da come si risolve; la tabella sotto [Which settings can disable it](#which-settings-can-disable-it) copre i quattro casi.798Quando le impostazioni gestite configurano `sandbox.filesystem` o elencano qualsiasi voce `sandbox.credentials.files` con `"mode": "deny"`, solo le impostazioni gestite possono impostare [`filesystem.disabled`](#disable-filesystem-isolation), quindi gli sviluppatori non possono disattivare le restrizioni del filesystem distribuite dall'amministratore. Una voce `mask` [valida](/docs/it/settings-reference#invalid-credential-entries-in-managed-settings) non blocca la chiave. Vedi [Quali impostazioni possono disabilitarla](#which-settings-can-disable-it).

714 799

715`excludedCommands` non ha un equivalente blocco solo gestito, quindi uno sviluppatore può sempre aggiungere voci che eseguono comandi aggiuntivi al di fuori della sandbox. Mantieni l'elenco gestito ristretto.800<h4 id="repository-settings-under-an-admin-required-sandbox">

801 Impostazioni del repository con una sandbox richiesta dall'amministratore

802</h4>

803

804La sandbox è richiesta dall'amministratore mentre è in vigore una di queste impostazioni:

805

806* [`allowUnsandboxedCommands`](/docs/it/settings-reference#sandbox-allowunsandboxedcommands) impostato su `false` nelle impostazioni gestite, oppure con il flag `--settings` a meno che le impostazioni gestite non lo impostino su `true`

807* [`allowManagedDomainsOnly`](/docs/it/settings-reference#sandbox-network-allowmanageddomainsonly) impostato su `true` nelle impostazioni gestite

808

809Queste impostazioni non attivano la sandbox, quindi imposta anche `enabled`.

810

811Mentre la sandbox è richiesta dall'amministratore, Claude Code accetta le impostazioni che la allentano solo dalle impostazioni gestite, dal flag `--settings` e dal `~/.claude/settings.json` di ciascuno sviluppatore. Ignora queste impostazioni nei file `.claude/settings.json` e `.claude/settings.local.json` di un repository:

812

813| Impostazione del repository | Cosa ignora Claude Code |

814| :- | :- |

815| `excludedCommands`, `ignoreViolations`, `network.allowedDomains`, `network.allowUnixSockets`, `network.allowMachLookup`, `network.httpProxyPort`, `network.socksProxyPort` | Ogni voce |

816| `filesystem.allowWrite`, regole di autorizzazione `Edit(...)`, `permissions.additionalDirectories` | L'accesso in scrittura che ogni voce concede ai comandi sandboxati. Gli strumenti per i file di Claude seguono comunque le regole `Edit(...)` e le directory aggiuntive |

817| Regole di autorizzazione `WebFetch(domain:...)` | L'host che ogni regola aggiunge all'allowlist della sandbox. Lo strumento WebFetch segue comunque la regola |

818| `enableWeakerNestedSandbox`, `enableWeakerNetworkIsolation`, `network.allowAllUnixSockets`, `network.allowLocalBinding` | `true`. Un `false` si applica comunque |

819| `enabled`, `failIfUnavailable` | `false`, quando il `~/.claude/settings.json` dello sviluppatore imposta `true` |

820| `filesystem.allowRead` | Una voce in corrispondenza o al di sotto di un percorso la cui lettura è negata dalle impostazioni gestite, da `--settings` o dalle impostazioni utente, oppure un glob che potrebbe corrispondere a uno di essi |

821

822Queste impostazioni si applicano comunque mentre la sandbox è richiesta dall'amministratore:

823

824* **Nei file di un repository**: le voci di negazione e il valore di `autoAllowBashIfSandboxed`. Imposta la chiave nelle impostazioni gestite per impedire a un repository di modificarla

825* **Nelle impostazioni dello sviluppatore**: le impostazioni nella tabella si applicano comunque da `~/.claude/settings.json` o `--settings`, a meno che non siano coperte da un blocco solo gestito come `allowManagedDomainsOnly`. La maggior parte di esse, come `excludedCommands` e `filesystem.allowWrite`, non ha un blocco solo gestito

826

827La configurazione in [Applica il sandboxing con le impostazioni gestite](#enforce-sandboxing-with-managed-settings) rende la sandbox richiesta dall'amministratore. Aggiungi alle impostazioni gestite le voci `excludedCommands`, `allowWrite` e di socket di cui hanno bisogno i tuoi strumenti approvati, perché un repository non può fornirle.

828

829Richiede Claude Code v2.1.285 o successivo. Dalla v2.1.282 alla v2.1.284, le stesse impostazioni facevano sì che Claude Code ignorasse le voci `excludedCommands` di un repository.

830

831<h4 id="locks-that-apply-without-an-admin-required-sandbox">

832 Blocchi che si applicano senza una sandbox richiesta dall'amministratore

833</h4>

834

835Alcune impostazioni fanno sì che Claude Code ignori le chiavi del repository che sovrascrivono direttamente una restrizione, anche quando la sandbox non è richiesta dall'amministratore. Ognuna ha questo effetto solo quando la imposti in un file indicato nella sua riga, e le altre impostazioni sandbox del repository si applicano comunque. Richiede Claude Code v2.1.285 o successivo.

836

837| Impostazione | Dove la imposti | Cosa ignora Claude Code nelle impostazioni di un repository |

838| :- | :- | :- |

839| `network.deniedDomains` o una regola di negazione `WebFetch(domain:...)` | Impostazioni gestite, `--settings` | `httpProxyPort` e `socksProxyPort` |

840| `network.strictAllowlist` | Impostazioni gestite, `--settings`, impostazioni utente | Le porte proxy, `allowedDomains` e le regole di autorizzazione `WebFetch(domain:...)` |

841| `filesystem.denyRead`, una regola di negazione `Read(...)` o una voce `credentials.files` | Impostazioni gestite, `--settings` | Una voce `allowRead`, `allowWrite`, di autorizzazione `Edit(...)` o `additionalDirectories` in corrispondenza o al di sotto di un percorso la cui lettura è negata dalle impostazioni gestite, da `--settings` o dalle impostazioni utente, oppure un glob che potrebbe corrispondere a uno di essi |

842

843Questi blocchi cambiano ciò che i comandi sandboxati possono raggiungere. Lo strumento WebFetch e gli strumenti per i file di Claude seguono comunque le regole e le directory aggiuntive di un repository.

716 844

717<h3 id="custom-proxy-configuration">845<h3 id="custom-proxy-configuration">

718 Custom proxy configuration846 Configurazione proxy personalizzata

719</h3>847</h3>

720 848

721Per le organizzazioni che richiedono una sicurezza di rete avanzata, puoi implementare un proxy personalizzato per:849Per ispezionare, filtrare o registrare il traffico della sandbox con i tuoi strumenti, sostituisci il proxy sandbox integrato con un proxy che esegui sulla stessa macchina.

722 850

723* Decrittare e ispezionare il traffico HTTPS851Per instradare il traffico della sandbox attraverso un proxy aziendale altrove nella tua rete, imposta invece `HTTPS_PROXY`, come descritto dalla voce **Proxy aziendale** in [Isolamento di rete](#network-isolation). In questo modo, l'allowlist di Claude Code si applica comunque.

724* Applicare regole di filtraggio personalizzate

725* Registrare tutte le richieste di rete

726* Integrarsi con l'infrastruttura di sicurezza esistente

727 852

728Per puntare Claude Code al tuo proxy, imposta le porte proxy nelle [impostazioni sandbox](/docs/it/settings-reference#sandbox-settings):853Per indirizzare i comandi sandboxati al tuo proxy, imposta le porte localhost su cui è in ascolto nelle [impostazioni sandbox](/docs/it/settings-reference#sandbox-settings):

729 854

730```json theme={null}855```json theme={null}

731{856{

738}863}

739```864```

740 865

866Se imposti una porta e imposti anche `HTTPS_PROXY` o `HTTP_PROXY`, Claude Code non inoltra ciò che i comandi sandboxati inviano al tuo proxy al proxy indicato da quelle variabili. Per raggiungere un proxy aziendale, configura il tuo proxy in modo che inoltri a esso.

867

868Quali file possono impostare una porta dipende dalle tue altre impostazioni sandbox. Si applica il primo caso corrispondente:

869

870* **`allowManagedDomainsOnly` è attivo**: solo le impostazioni gestite

871* **La sandbox è [richiesta dall'amministratore](#repository-settings-under-an-admin-required-sandbox), oppure si applica un [blocco di rete più ristretto](#locks-that-apply-without-an-admin-required-sandbox)**: impostazioni gestite, `--settings` e impostazioni utente

872* **Altrimenti**: qualsiasi file di impostazioni

873

874Claude Code ignora una porta impostata altrove. Prima della v2.1.285, qualsiasi file di impostazioni poteva impostare una porta.

875

876<Warning>

877 Una volta che una delle due porte si applica, il tuo proxy è responsabile del filtraggio di tutto ciò che gli viene inviato. I controlli di rete di Claude Code, come `allowedDomains`, `deniedDomains`, `strictAllowlist`, le richieste di approvazione e il [controllo degli indirizzi locali](#hostnames-that-resolve-to-local-addresses), smettono di applicarsi a quel traffico. Un comando sandboxato può connettersi a entrambi i proxy, quindi se imposti una sola porta, gli elenchi di domini di Claude Code sull'altro proxy non limitano ciò che il comando raggiunge attraverso il tuo.

878</Warning>

879

741<h2 id="troubleshooting">880<h2 id="troubleshooting">

742 Troubleshooting881 Risoluzione dei problemi

743</h2>882</h2>

744 883

745Alcuni comandi falliscono all'interno della sandbox anche se funzionano al di fuori di essa. Le correzioni seguenti coprono i casi più comuni.884Alcuni comandi falliscono all'interno della sandbox anche se funzionano al di fuori di essa. Trova l'intestazione che corrisponde al tuo sintomo o messaggio di errore.

885

886Se la sandbox della tua organizzazione è [obbligatoria per l'amministratore](#repository-settings-under-an-admin-required-sandbox), Claude Code ignora le impostazioni indicate da queste correzioni nei file di impostazioni di un progetto, quindi salvale in `~/.claude/settings.json`, dove si applicano in ogni progetto. Se una correzione continua a non avere effetto, le impostazioni gestite della tua organizzazione potrebbero impostare quella chiave.

887

888Una correzione che aggiunge un pattern a `excludedCommands` rimuove la sandbox dai comandi a cui corrisponde il pattern. Consulta [cosa può fare un comando escluso](#run-commands-outside-the-sandbox-with-excludedcommands).

889

890<h3 id="commands-fail-with-a-host-not-allowed-error">

891 I comandi falliscono con un errore host-not-allowed

892</h3>

893

894Molti strumenti CLI devono raggiungere host specifici. Approva l'host quando ti viene chiesto, oppure aggiungilo a [`allowedDomains`](/docs/it/settings-reference#sandbox-network-alloweddomains). Se la tua organizzazione blocca l'allowlist con `allowManagedDomainsOnly`, non viene mostrata alcuna richiesta, quindi chiedi al tuo amministratore di aggiungere l'host.

895

896<h3 id="jest-hangs-or-fails">

897 `jest` si blocca o fallisce

898</h3>

899

900`watchman` è incompatibile con la sandbox. Esegui invece `jest --no-watchman`.

901

902<h3 id="go-based-clis-fail-tls-verification-on-macos">

903 I CLI basati su Go falliscono la verifica TLS su macOS

904</h3>

905

906Strumenti come `gh`, `gcloud` e `terraform` potrebbero fallire la verifica TLS sotto [Seatbelt](#os-level-enforcement). Per eseguire questi strumenti al di fuori della sandbox, aggiungi un pattern per ciascuno strumento, come `gh *`, a [`excludedCommands`](#run-commands-outside-the-sandbox-with-excludedcommands). Lo strumento viene quindi eseguito con il tuo accesso completo e con le sue credenziali memorizzate. Se stai utilizzando `httpProxyPort` con un proxy MITM e una CA personalizzata, imposta invece [`enableWeakerNetworkIsolation`](/docs/it/settings-reference#sandbox-enableweakernetworkisolation) su `true`.

907

908<h3 id="open-osascript-or-browser-based-auth-flows-fail-with-error-600-on-macos">

909 `open`, `osascript` o i flussi di autenticazione basati su browser falliscono con errore `-600` su macOS

910</h3>

911

912La sandbox blocca gli Apple Events per impostazione predefinita. Imposta [`allowAppleEvents`](/docs/it/settings-reference#sandbox-allowappleevents) su `true` nelle impostazioni utente, gestite o CLI per consentirli. Claude Code ignora questa chiave nelle impostazioni del progetto.

913

914L'abilitazione di `allowAppleEvents` rimuove l'isolamento dell'esecuzione del codice, poiché i comandi sandboxati possono quindi avviare altre applicazioni non sandboxate senza alcuna richiesta all'utente e inviare comandi AppleScript alle applicazioni in esecuzione, soggetti alla richiesta di consenso per l'automazione di macOS (TCC). In alternativa, aggiungi un pattern come `open *` a [`excludedCommands`](#run-commands-outside-the-sandbox-with-excludedcommands). Ogni chiamata a `open` passa quindi attraverso il flusso dei permessi, e `open` può avviare qualsiasi file o app, inclusi quelli scritti da Claude.

915

916<h3 id="docker-commands-fail">

917 I comandi `docker` falliscono

918</h3>

919

920`docker` è incompatibile con la sandbox. Togli dalla sandbox i comandi `docker` di cui hai bisogno con un pattern in `excludedCommands` come `docker compose *`. [Eseguire comandi al di fuori della sandbox con `excludedCommands`](#run-commands-outside-the-sandbox-with-excludedcommands) spiega cosa può raggiungere un comando `docker` escluso. Un pattern più ristretto toglie meno comandi dalla sandbox.

921

922<h3 id="pbcopy-xclip-or-wl-copy-doesn’t-update-the-clipboard">

923 `pbcopy`, `xclip` o `wl-copy` non aggiorna gli appunti

924</h3>

925

926Le utilità degli appunti `pbcopy`, `xclip` e `wl-copy` possono non riuscire a raggiungere gli appunti di sistema dall'interno della sandbox, nel qual caso il testo inviato loro tramite pipe non arriva.

927

928Per mettere l'output di Claude negli appunti, chiedi a Claude di stamparlo nella sua risposta, quindi esegui [`/copy`](/docs/it/commands). `/copy` scrive negli appunti dal processo di Claude Code anziché da un comando sandboxato.

929

930Quando Claude invia testo tramite pipe a uno di questi strumenti, aggiungere lo strumento a [`excludedCommands`](/docs/it/settings-reference#sandbox-excludedcommands) non toglie di per sé quella chiamata dalla sandbox.

931

932<h3 id="a-git-command-fails-with-unable-to-unlink-old">

933 Un comando git fallisce con `unable to unlink old`

934</h3>

935

936`git merge`, `git checkout` e comandi simili falliscono con `unable to unlink old` quando devono sostituire un file su cui la sandbox nega la scrittura. Su Linux e WSL2 l'errore termina con `Read-only file system`. Il file può trovarsi in uno di questi punti:

937

938* Sotto un [percorso protetto](#protected-paths) come `.claude/skills`

939* Sotto una delle tue voci `denyWrite`

940* Del tutto al di fuori delle directory in cui la sandbox consente ai comandi di scrivere

941

942Dopo il fallimento, Claude potrebbe [offrirsi di rieseguire il comando al di fuori della sandbox](#the-unsandboxed-retry-escape-hatch). Approva quel nuovo tentativo, oppure esegui tu stesso il comando git in un altro terminale. Se hai impostato `allowUnsandboxedCommands` su `false`, Claude non può offrire il nuovo tentativo, quindi esegui tu stesso il comando.

943

944<h3 id="bubblewrap-fails-to-start-inside-a-container">

945 Bubblewrap non riesce ad avviarsi all'interno di un container

946</h3>

947

948In un container senza privilegi, [bubblewrap](#os-level-enforcement) non può montare un nuovo filesystem `/proc`, quindi i comandi sandboxati falliscono con un errore `bwrap` come `Can't mount proc on /newroot/proc: Operation not permitted`. Imposta [`enableWeakerNestedSandbox`](/docs/it/settings-reference#sandbox-enableweakernestedsandbox) su `true` in modo che la sandbox esegua invece il bind-mount del `/proc` esistente del container. Utilizza questa impostazione solo quando il container esterno fornisce già il confine di isolamento di cui hai bisogno, poiché l'impostazione espone ai comandi sandboxati informazioni sui processi che un nuovo mount di `/proc` nasconderebbe.

949

950<h3 id="0-byte-read-only-files-appear-at-claude-settings-paths-and-yes-and-don’t-ask-again-doesn’t-save">

951 Compaiono file di sola lettura da 0 byte nei percorsi delle impostazioni `.claude`, e "Sì, e non chiedere più" non salva

952</h3>

953

954Su Linux e WSL2, la sandbox mantiene un divieto di scrittura su un file che non esiste ancora creando in quel punto un placeholder di sola lettura da 0 byte mentre viene eseguito un comando sandboxato. La sandbox rimuove il placeholder in seguito. Se una sessione viene terminata prima che venga eseguita quella pulizia, ad esempio da SIGKILL, i placeholder rimangono. Le sessioni successive eseguono di nuovo il bind dei placeholder in sola lettura a ogni avvio, quindi una scrittura delle impostazioni, come il salvataggio di una scelta di permesso, fallisce in un percorso in cui rimane un placeholder.

955

956Esegui `claude doctor` nel tuo terminale per elencare i file placeholder rimasti. L'avviso [`Stale sandbox mask files left by a killed session`](/docs/it/errors#stale-sandbox-mask-files-left-by-a-killed-session) ne indica alcuni e conta i restanti. Elimina ciascun file con `rm` mentre nessun'altra sessione di Claude Code è in esecuzione in quel progetto. Prima della v2.1.257, Claude Code lasciava gli stessi placeholder senza segnalarli.

957

958<h3 id="git-over-ssh-fails-with-the-sandbox-on">

959 `git` su SSH fallisce con la sandbox attiva

960</h3>

961

962Su macOS, `git fetch`, `git pull` e `git push` verso un remote SSH falliscono all'interno della sandbox anche quando l'host è consentito. Su Linux e WSL2, funzionano una volta consentito l'host. Claude Code incanala la connessione SSH di git attraverso il [proxy della sandbox](#network-isolation), e il tunnel di macOS non riesce ad autenticarsi con quel proxy.

963

964Su Linux e WSL2, se la connessione continua a fallire, verifica quanto segue:

965

966* **L'host è consentito sulla porta 22**: una voce di `allowedDomains` senza porta, come `"git.example.com"`, la copre

967* **Il tuo proxy aziendale consente la porta 22**: se la tua rete richiede un proxy upstream, anche il tunnel passa attraverso di esso

968* **La chiave è leggibile come file**: la sandbox può bloccare il socket di `ssh-agent`, e una voce `denyRead` o `credentials` per `~/.ssh` nasconde i tuoi file di chiave

969

970Su macOS, passa il remote a HTTPS, che richiede credenziali HTTPS come un personal access token:

971

972```bash theme={null}

973git remote set-url origin https://git.example.com/example-org/example-repo.git

974```

975

976Se devi mantenere il remote SSH, togli i comandi di rete di git dalla sandbox con [`excludedCommands`](#run-commands-outside-the-sandbox-with-excludedcommands):

977

978```json theme={null}

979{

980 "sandbox": {

981 "excludedCommands": ["git fetch *", "git pull *", "git push *"]

982 }

983}

984```

985

986Queste voci corrispondono a `git push origin main`. Una chiamata che aggiunge un `cd`, usa `git -C` o contiene una sostituzione di comando resta nella sandbox. I comandi git esclusi possono raggiungere qualsiasi host, non solo quelli in `allowedDomains`.

987

988I semplici `ssh`, `scp` e `rsync` su SSH falliscono per il motivo indicato nella [voce sui client di database](#a-database-client-or-other-non-http-tool-fails-to-reach-an-allowed-host).

989

990<h3 id="a-database-client-or-other-non-http-tool-fails-to-reach-an-allowed-host">

991 Un client di database o un altro strumento non HTTP non riesce a raggiungere un host consentito

992</h3>

993

994Uno strumento che ignora le variabili d'ambiente del proxy non può connettersi dall'interno della sandbox, nemmeno a un host presente in `allowedDomains`. Un comando sandboxato non ha [alcun percorso diretto verso la rete](#network-isolation), quindi uno strumento che apre una propria connessione fallisce. La maggior parte dei driver di database, il semplice `ssh` e gli strumenti che usano UDP si comportano in questo modo.

995

996Il fallimento si presenta come un errore di rete o di risoluzione dei nomi:

997

998* **macOS**: `Operation not permitted`, oppure un errore di risoluzione dei nomi come `Could not resolve host`

999* **Linux e WSL2**: `Network is unreachable`, oppure un errore di risoluzione dei nomi come `Temporary failure in name resolution`

1000

1001Uno strumento che usa il proxy fallisce in modo diverso quando il suo host non è consentito. Ricevi una richiesta di rete, oppure lo strumento riceve una risposta `403` dal proxy.

1002

1003Per consentire allo strumento di connettersi, esegui il comando che ne ha bisogno al di fuori della sandbox con [`excludedCommands`](#run-commands-outside-the-sandbox-with-excludedcommands). Questo esempio esclude uno script e aggiunge una [regola ask](/docs/it/permissions) in modo che tu approvi ogni esecuzione:

1004

1005```json theme={null}

1006{

1007 "sandbox": {

1008 "excludedCommands": ["python scripts/load_orders.py *"]

1009 },

1010 "permissions": {

1011 "ask": ["Bash(python scripts/load_orders.py *)"]

1012 }

1013}

1014```

1015

1016Lo script viene eseguito con il tuo accesso completo, e Claude può modificare uno script che si trova all'interno della tua directory di lavoro, quindi esaminalo quando compare la richiesta.

1017

1018<h3 id="a-command-fails-to-reach-a-server-on-localhost">

1019 Un comando non riesce a raggiungere un server su localhost

1020</h3>

1021

1022Per impostazione predefinita, un comando sandboxato non può connettersi direttamente a un server in esecuzione sulla tua macchina al di fuori della sandbox, come un server di sviluppo o un database in un container. Cosa puoi modificare dipende dalla tua piattaforma:

746 1023

747* **I comandi falliscono con un errore host-not-allowed**: molti strumenti CLI devono raggiungere host specifici. Concedere l'autorizzazione quando richiesto aggiunge l'host al vostro elenco consentito in modo che lo strumento venga eseguito all'interno della sandbox in futuro.1024* **macOS**: imposta [`network.allowLocalBinding`](/docs/it/settings-reference#sandbox-network-allowlocalbinding) su `true`. I comandi sandboxati possono quindi restare in ascolto su porte di rete e connettersi a qualsiasi porta su localhost, il che include ogni altro servizio in ascolto lì. Un servizio su localhost che non richiede autenticazione, come un debugger, può quindi agire per conto del comando al di fuori della sandbox, e un comando in ascolto su un indirizzo non di loopback accetta connessioni da altre macchine

748* **`jest` si blocca o fallisce**: `watchman` è incompatibile con la sandbox. Eseguite `jest --no-watchman` invece.1025* **Linux e WSL2**: il `localhost` di un comando sandboxato è privato per quel comando. Il comando può restare in ascolto su una porta e raggiungere i server che ha avviato esso stesso. Una connessione diretta a `localhost` o `127.0.0.1` non raggiunge i server sull'host, e `allowLocalBinding` non ha effetto. Esegui il comando che ha bisogno del server dell'host al di fuori della sandbox con [`excludedCommands`](#run-commands-outside-the-sandbox-with-excludedcommands), dove non ha limiti di filesystem o di rete. Per le connessioni che passano attraverso il proxy della sandbox, consulta [Hostname che si risolvono in indirizzi locali](#hostnames-that-resolve-to-local-addresses)

749* **I CLI basati su Go falliscono la verifica TLS su macOS**: strumenti come `gh`, `gcloud` e `terraform` potrebbero fallire la verifica TLS sotto Seatbelt. Elencate questi strumenti in [`excludedCommands`](/docs/it/settings-reference#sandbox-excludedcommands). Se state utilizzando `httpProxyPort` con un proxy MITM e CA personalizzato, impostate [`enableWeakerNetworkIsolation`](/docs/it/settings-reference#sandbox-enableweakernetworkisolation) su `true` invece.

750* **`open`, `osascript`, o i flussi di autenticazione basati su browser falliscono con errore `-600` su macOS**: la sandbox blocca gli Apple Events per impostazione predefinita. Impostate [`allowAppleEvents`](/docs/it/settings-reference#sandbox-allowappleevents) su `true` nelle impostazioni utente, gestite o CLI per consentirli. Le impostazioni del progetto vengono ignorate per questa chiave. L'abilitazione rimuove l'isolamento dell'esecuzione del codice, poiché i comandi sandboxati possono quindi avviare altre applicazioni non sandboxate senza prompt dell'utente e inviare comandi AppleScript alle applicazioni in esecuzione, soggetti al prompt di consenso dell'automazione macOS (TCC). In alternativa, aggiungete il comando a [`excludedCommands`](/docs/it/settings-reference#sandbox-excludedcommands).

751* **I comandi `docker` falliscono**: `docker` è incompatibile con la sandbox. Aggiungete `docker *` a [`excludedCommands`](/docs/it/settings-reference#sandbox-excludedcommands).

752* **`pbcopy`, `xclip`, o `wl-copy` non aggiorna gli appunti**: queste utilità degli appunti possono non riuscire a raggiungere gli appunti di sistema dall'interno della sandbox, nel qual caso il testo inviato tramite pipe a loro non arriva.

753 1026

754 Per mettere l'output di Claude negli appunti, chiedete a Claude di stamparlo nella sua risposta, quindi eseguite [`/copy`](/docs/it/commands). `/copy` scrive negli appunti dal processo Claude Code piuttosto che da un comando sandboxato.1027Questo esempio attiva l'impostazione per macOS:

755 1028

756 Quando Claude invia testo tramite pipe a uno di questi strumenti, aggiungere lo strumento a [`excludedCommands`](/docs/it/settings-reference#sandbox-excludedcommands) non toglie quella chiamata dalla sandbox di per sé.1029```json theme={null}

757* **Un comando git fallisce con `unable to unlink old`**: `git merge`, `git checkout` e comandi simili falliscono in questo modo quando devono sostituire un file a cui la sandbox nega le scritture, sia che il file sia sotto un [percorso protetto](#protected-paths) come `.claude/skills`, sotto una delle vostre voci `denyWrite`, o al di fuori delle directory in cui la sandbox consente ai comandi di scrivere. Su Linux e WSL2 l'errore termina con `Read-only file system`.1030{

1031 "sandbox": {

1032 "network": {

1033 "allowLocalBinding": true

1034 }

1035 }

1036}

1037```

1038

1039Una voce di `allowedDomains` per `localhost` si applica alle connessioni che passano attraverso il proxy, quindi non modifica una connessione diretta. Claude Code imposta `NO_PROXY` per i comandi sandboxati in modo che si connettano a `localhost` direttamente anziché tramite il proxy. La voce espone inoltre ogni porta del localhost della tua macchina a un comando che usa il proxy. Per un hostname di sviluppo che punta a `127.0.0.1`, consulta [Un hostname consentito viene rifiutato con `resolved to a loopback address`](#an-allowed-hostname-is-refused-with-resolved-to-a-loopback-address).

1040

1041<h3 id="an-allowed-hostname-is-refused-with-resolved-to-a-loopback-address">

1042 Un hostname consentito viene rifiutato con `resolved to a loopback address`

1043</h3>

1044

1045Il proxy della sandbox rifiuta un hostname consentito che [si risolve in un indirizzo locale](#hostnames-that-resolve-to-local-addresses), il che riguarda nomi di sviluppo come `myapp.test` che puntano a `127.0.0.1`. Il comando riceve una risposta `403` il cui corpo indica il tipo di indirizzo, ad esempio `Connection to myapp.test blocked: resolved to a loopback address`.

1046

1047Aggiungi l'indirizzo IP in cui si risolve il nome accanto all'hostname in `allowedDomains`, ciascuno con la porta su cui è in ascolto il tuo server:

1048

1049```json theme={null}

1050{

1051 "sandbox": {

1052 "network": {

1053 "allowedDomains": ["myapp.test:3000", "127.0.0.1:3000"]

1054 }

1055 }

1056}

1057```

758 1058

759 Dopo il fallimento, Claude potrebbe [offrire di rieseguire il comando al di fuori della sandbox](#the-unsandboxed-retry-escape-hatch); approvate quel nuovo tentativo, o eseguite il comando git voi stessi in un altro terminale. Se avete impostato `allowUnsandboxedCommands` su `false`, Claude non può offrire il nuovo tentativo, quindi eseguite il comando voi stessi. Se lo stesso comando git fallisce spesso, aggiungetelo a [`excludedCommands`](/docs/it/settings-reference#sandbox-excludedcommands).1059Una voce di indirizzo IP senza porta consente ai comandi sandboxati di raggiungere ogni servizio in ascolto su quell'indirizzo.

760* **Bubblewrap non riesce ad avviarsi all'interno di un container**: in un container senza privilegi, bubblewrap non può montare un filesystem `/proc` fresco, quindi i comandi sandboxati falliscono con un errore `bwrap` come `Can't mount proc on /newroot/proc: Operation not permitted`. Impostate [`enableWeakerNestedSandbox`](/docs/it/settings-reference#sandbox-enableweakernestedsandbox) su `true` in modo che la sandbox interna bind-monti il `/proc` esistente del container invece. Utilizzate questa impostazione solo quando il container esterno fornisce già il confine di isolamento di cui avete bisogno, poiché espone le informazioni del processo ai comandi sandboxati che un mount `/proc` fresco nasconderebbe.

761* **File di sola lettura a 0 byte appaiono nei percorsi delle impostazioni `.claude`, e "Sì, e non chiedere più" non salva**: su Linux e WSL2, la sandbox mantiene un diniego di scrittura su un file che non esiste ancora creando un placeholder di sola lettura a 0 byte lì mentre un comando sandboxato viene eseguito. La sandbox rimuove il placeholder in seguito. Se una sessione viene terminata prima che quella pulizia venga eseguita, ad esempio da SIGKILL, i placeholder rimangono. Le sessioni successive li bind-montano di sola lettura di nuovo ad ogni avvio, quindi una scrittura delle impostazioni come il salvataggio di una scelta di autorizzazione fallisce dove uno si trova.

762 1060

763 Eseguite `claude doctor` per elencare i file placeholder rimasti. L'avviso [`Stale sandbox mask files left by a killed session`](/docs/it/errors#stale-sandbox-mask-files-left-by-a-killed-session) nomina fino a tre di essi e conta il resto. Eliminate ogni file con `rm` mentre nessun'altra sessione Claude Code è in esecuzione in quel progetto. Prima della v2.1.257, Claude Code lasciava gli stessi placeholder dietro senza segnalarli.1061Prima della v2.1.284, il proxy si connetteva a qualsiasi indirizzo in cui si risolvesse un hostname consentito.

764* **`--dangerously-skip-permissions` fallisce come root**: questo flag viene bloccato quando viene eseguito come root o tramite sudo su Linux e macOS, perché l'accesso root combinato con nessun prompt di autorizzazione può modificare qualsiasi file o servizio sul sistema. Il controllo viene saltato automaticamente all'interno di una sandbox riconosciuta. Per eseguire autonomamente in un container, utilizzate la configurazione [dev container](/docs/it/devcontainer), che esegue Claude Code come utente non root.1062

1063<h3 id="/sandbox-fails-with-sandbox-settings-are-overridden-by-a-higher-priority-configuration">

1064 `/sandbox` fallisce con `Sandbox settings are overridden by a higher-priority configuration`

1065</h3>

1066

1067`/sandbox` stampa `Error: Sandbox settings are overridden by a higher-priority configuration and cannot be changed locally.` invece di aprire il suo pannello quando un [livello di impostazioni](/docs/it/settings#settings-precedence) superiore imposta `sandbox.enabled`, `sandbox.autoAllowBashIfSandboxed` o `sandbox.allowUnsandboxedCommands`. Il pannello salva le tue scelte in `.claude/settings.local.json`, e un valore salvato lì non può sovrascrivere quei livelli.

1068

1069Le impostazioni gestite e `--settings` hanno priorità superiore rispetto alle impostazioni locali. Per vedere quali di esse sono state caricate in questa sessione, esegui `/status` e leggi la riga `Setting sources`:

1070

1071* **`Command line arguments`**: se hai avviato Claude Code con [`--settings`](/docs/it/settings#change-a-setting-for-one-session), verifica se il file o il JSON che hai passato imposta una di quelle chiavi. In tal caso, modifica il valore lì, oppure avvia di nuovo Claude Code senza quelle chiavi.

1072* **`Enterprise managed settings`**: sono caricate le impostazioni gestite della tua organizzazione. Se impostano una di quelle chiavi, non puoi modificare quella chiave da `/sandbox` né da alcun file di impostazioni sotto il tuo controllo, quindi rivolgiti al tuo amministratore.

765 1073

766<h2 id="limitations">1074<h2 id="limitations">

767 Limitazioni1075 Limitazioni

773 Limitazioni di sicurezza1081 Limitazioni di sicurezza

774</h3>1082</h3>

775 1083

776* **Filtraggio della rete**: il sandbox limita i domini a cui i processi possono connettersi. Per impostazione predefinita il proxy integrato non termina o ispeziona TLS sul traffico in uscita, quindi i contenuti delle connessioni crittografate non vengono esaminati. L'impostazione sperimentale [`network.tlsTerminate`](/docs/it/settings-reference#sandbox-network-tlsterminate) termina TLS al proxy per la [sostituzione delle credenziali `mask`](#mask-credentials) ma non aggiunge filtraggio dei contenuti. Sei responsabile di assicurarti che solo i domini affidabili siano consentiti nella tua politica.1084* **Filtraggio della rete**: la sandbox limita i domini a cui i processi possono connettersi. Per impostazione predefinita il proxy integrato non termina o ispeziona TLS sul traffico in uscita, quindi i contenuti delle connessioni crittografate non vengono esaminati. L'impostazione sperimentale [`network.tlsTerminate`](/docs/it/settings-reference#sandbox-network-tlsterminate) termina TLS al proxy per la [sostituzione delle credenziali `mask`](#mask-credentials) ma non aggiunge filtraggio dei contenuti. Sei responsabile di assicurarti che solo i domini affidabili siano consentiti nella tua politica.

777 1085

778<Warning>1086<Warning>

779 Consentire domini ampi come `github.com` può creare percorsi per l'esfiltrazione di dati. Poiché il proxy prende la sua decisione di consentimento dal nome host fornito dal client senza ispezionare TLS, il codice in esecuzione all'interno della sandbox potrebbe potenzialmente utilizzare [domain fronting](https://en.wikipedia.org/wiki/Domain_fronting) o tecniche simili per raggiungere host al di fuori dell'allowlist. Se il tuo modello di minaccia richiede garanzie più forti, configura un [proxy personalizzato](#custom-proxy-configuration) che termina TLS e ispeziona il traffico, e installa il suo certificato CA all'interno della sandbox. L'isolamento della rete più consapevole di TLS è un'area di sviluppo attiva.1087 Consentire domini ampi come `github.com` può creare percorsi per l'esfiltrazione di dati. Poiché il proxy prende la sua decisione di consentimento dal nome host fornito dal client senza ispezionare TLS, il codice in esecuzione all'interno della sandbox potrebbe potenzialmente utilizzare [domain fronting](https://en.wikipedia.org/wiki/Domain_fronting) o tecniche simili per raggiungere host al di fuori dell'allowlist. Se il tuo modello di minaccia richiede garanzie più forti, configura un [proxy personalizzato](#custom-proxy-configuration) che termina TLS e ispeziona il traffico, e installa il suo certificato CA all'interno della sandbox. L'isolamento della rete più consapevole di TLS è un'area di sviluppo attiva.

781 1089

782* **Escalation dei privilegi tramite socket Unix**: la configurazione `allowUnixSockets` può inavvertitamente concedere l'accesso a servizi di sistema che potrebbero portare a bypass della sandbox. Ad esempio, consentire l'accesso a `/var/run/docker.sock` concede effettivamente l'accesso al sistema host attraverso il socket Docker. Considera attentamente qualsiasi socket Unix che consenti attraverso la sandbox.1090* **Escalation dei privilegi tramite socket Unix**: la configurazione `allowUnixSockets` può inavvertitamente concedere l'accesso a servizi di sistema che potrebbero portare a bypass della sandbox. Ad esempio, consentire l'accesso a `/var/run/docker.sock` concede effettivamente l'accesso al sistema host attraverso il socket Docker. Considera attentamente qualsiasi socket Unix che consenti attraverso la sandbox.

783* **Escalation dei permessi del filesystem**: i permessi di scrittura del filesystem eccessivamente ampi possono abilitare attacchi di escalation dei privilegi. Consentire scritture a directory contenenti eseguibili in `$PATH`, directory di configurazione di sistema o file di configurazione della shell dell'utente come `.bashrc` o `.zshrc` può portare all'esecuzione di codice in diversi contesti di sicurezza quando altri utenti o processi di sistema accedono a questi file.1091* **Escalation dei permessi del filesystem**: i permessi di scrittura del filesystem eccessivamente ampi possono abilitare attacchi di escalation dei privilegi. Consentire scritture a directory contenenti eseguibili in `$PATH`, directory di configurazione di sistema o file di configurazione della shell dell'utente come `.bashrc` o `.zshrc` può portare all'esecuzione di codice in diversi contesti di sicurezza quando altri utenti o processi di sistema accedono a questi file.

784* **Forza della sandbox Linux**: l'implementazione Linux fornisce un forte isolamento del filesystem e della rete ma include una modalità `enableWeakerNestedSandbox` che le consente di funzionare all'interno di ambienti Docker senza namespace privilegiati, o su host Linux dove gli spazi dei nomi utente senza privilegi sono disabilitati da sysctl. Questa opzione indebolisce considerevolmente la sicurezza e dovrebbe essere utilizzata solo quando l'isolamento aggiuntivo è altrimenti applicato.1092* **Forza della sandbox Linux**: l'implementazione Linux fornisce un forte isolamento del filesystem e della rete ma include una modalità `enableWeakerNestedSandbox` che le consente di funzionare all'interno di ambienti Docker senza namespace privilegiati. Questa opzione indebolisce considerevolmente la sicurezza e dovrebbe essere utilizzata solo quando l'isolamento aggiuntivo è altrimenti applicato.

785* **Apple Events su macOS**: la sandbox macOS blocca gli Apple Events per impostazione predefinita. L'impostazione `allowAppleEvents` rimuove questa restrizione in modo che strumenti come `open` e `osascript` funzionino, ma rimuove l'isolamento dell'esecuzione del codice: i comandi sandboxati possono avviare altre applicazioni senza sandbox senza alcun prompt dell'utente, e possono inviare comandi AppleScript alle applicazioni in esecuzione, soggetti al prompt di consenso per l'automazione macOS per app (TCC). È onorato solo dalle impostazioni utente, gestite o CLI. Le impostazioni del progetto non possono abilitarlo.1093* **Apple Events su macOS**: la sandbox macOS blocca gli Apple Events per impostazione predefinita. L'impostazione `allowAppleEvents` rimuove questa restrizione in modo che strumenti come `open` e `osascript` funzionino, ma rimuove l'isolamento dell'esecuzione del codice: i comandi sandboxati possono avviare altre applicazioni senza sandbox senza alcun prompt dell'utente, e possono inviare comandi AppleScript alle applicazioni in esecuzione, soggetti al prompt di consenso per l'automazione macOS per app (TCC). È onorato solo dalle impostazioni utente, gestite o CLI. Le impostazioni del progetto non possono abilitarlo.

786 1094

787<h3 id="platform-and-tool-compatibility">

788 Compatibilità della piattaforma e degli strumenti

789</h3>

~~790~~

791* **Supporto della piattaforma**: supporta macOS, Linux e WSL2. WSL1 e Windows nativo non sono supportati.

792* **Overhead di prestazioni**: minimo, ma alcune operazioni del filesystem potrebbero essere leggermente più lente.

793* **Compatibilità degli strumenti**: alcuni strumenti che richiedono modelli di accesso al sistema specifici potrebbero necessitare di regolazioni di configurazione, o potrebbero anche dover essere eseguiti al di fuori della sandbox.

~~794~~

795<h3 id="scope">1095<h3 id="scope">

796 Ambito1096 Ambito

797</h3>1097</h3>

798 1098

799La sandbox isola i sottoprocessi Bash. Altri strumenti operano sotto confini diversi:1099La sandbox isola i comandi della shell e i loro processi figli. [Cosa viene eseguito al di fuori della sandbox](#what-runs-outside-the-sandbox) elenca gli strumenti e i processi ausiliari che non copre. L'utilizzo del computer e i subagent si rapportano alla sandbox come segue:

800 1100

801* **Strumenti di file integrati**: Read, Edit e Write utilizzano il sistema di autorizzazione direttamente piuttosto che eseguire attraverso la sandbox. Vedi [permissions](/docs/it/permissions).1101* **Utilizzo del computer**: quando Claude apre app e controlla lo schermo, viene eseguito sul tuo desktop effettivo piuttosto che in un ambiente isolato. Le richieste di permesso per app controllano l'accesso a ogni applicazione. Vedi [computer use nella CLI](/docs/it/computer-use) o [computer use in Desktop](/docs/it/desktop#let-claude-use-your-computer).

802* **Utilizzo del computer**: quando Claude apre app e controlla lo schermo, viene eseguito sul tuo desktop effettivo piuttosto che in un ambiente isolato. I prompt di autorizzazione per app gating ogni applicazione. Vedi [computer use nella CLI](/docs/it/computer-use) o [computer use in Desktop](/docs/it/desktop#let-claude-use-your-computer).1102* **Subagent**: i [subagent](/docs/it/sub-agents) vengono eseguiti nello stesso processo della sessione padre e utilizzano la stessa configurazione sandbox. I comandi Bash all'interno di un subagent vengono sandboxati quando il sandboxing è abilitato nella sessione padre.

803* **Variabili di ambiente**: i comandi Bash sandboxati ereditano l'ambiente del processo padre per impostazione predefinita, incluse le credenziali impostate lì. Usa [`sandbox.credentials`](#protect-credentials) per annullare o mascherare variabili specifiche per i comandi sandboxati, o imposta [`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`](/docs/it/env-vars) per rimuovere le credenziali dai sottoprocessi.1103* **Mod**: un [mod](/docs/it/plugins/mods/overview) è un plugin che esegue il proprio codice all'interno di Claude Code, e un processo avviato da un mod viene eseguito al di fuori della sandbox. Vedi [Cosa può raggiungere un mod](/docs/it/plugins/mods/overview#what-a-mod-can-reach).

804* **Subagenti**: i [subagenti](/docs/it/sub-agents) vengono eseguiti nello stesso processo della sessione padre e utilizzano la stessa configurazione sandbox. I comandi Bash all'interno di un subagente vengono sandboxati quando il sandboxing è abilitato nella sessione padre.

805 1104

806<Warning>1105<Warning>

807 Il sandboxing efficace richiede sia l'isolamento del filesystem che della rete. Senza isolamento della rete, un agente compromesso potrebbe esfiltare file sensibili come chiavi SSH. Senza isolamento del filesystem, sia da una politica permissiva che da [disabilitazione del livello filesystem](#disable-filesystem-isolation), un agente compromesso potrebbe backdoor le risorse di sistema per ottenere accesso alla rete. Quando ampli i predefiniti, verifica che un percorso `allowWrite`, una voce `allowedDomains` ampia o un'eccezione `excludedCommands` non annulli una restrizione dall'altro lato.1106 Il sandboxing efficace richiede sia l'isolamento del filesystem che della rete. Senza isolamento della rete, un agente compromesso potrebbe esfiltrare file sensibili come chiavi SSH. Senza isolamento del filesystem, sia da una politica permissiva che da [disabilitazione del livello filesystem](#disable-filesystem-isolation), un agente compromesso potrebbe inserire backdoor nelle risorse di sistema per ottenere accesso alla rete. Quando ampli i predefiniti, verifica che un percorso `allowWrite`, una voce `allowedDomains` ampia o un'eccezione `excludedCommands` non annulli una restrizione dall'altro lato.

808</Warning>1107</Warning>

809 1108

810<h2 id="see-also">1109<h2 id="see-also">

sandboxing.md 2026-10-01 23:59 UTC to 2026-10-02 18:59 UTC

Configurare lo strumento Bash in sandbox

Cosa limita la sandbox

Cosa viene eseguito al di fuori della sandbox

Inizia

Esegui /sandbox

Scegli una modalità

Esegui un comando Bash

Verificare che i comandi vengano eseguiti nella sandbox

Configurare Linux e WSL2

Modalità della sandbox

Modalità auto-allow

Modalità permessi regolari

La via di fuga del nuovo tentativo fuori dalla sandbox

Disattivare il nuovo tentativo con la modalità sandbox rigorosa

Directory temporanee

Configurare il sandboxing

Eseguire comandi al di fuori della sandbox con `excludedCommands`

Disattivare l'isolamento del filesystem

Quali impostazioni possono disattivarlo

Cosa cambia quando l'isolamento del filesystem è disattivato

Proteggere le credenziali

Mascherare le credenziali

Mascherare le variabili d'ambiente

Firmare di nuovo le richieste AWS

Mascherare i file di credenziali

Come funziona il sandboxing

Isolamento del filesystem

Percorsi protetti

Isolamento di rete

Host al di fuori dei tuoi domini consentiti

Nomi host che si risolvono in indirizzi locali

Domini consentiti per comando in modalità auto

Indirizzi IPv6 negli elenchi di domini

Applicazione a livello di sistema operativo

Come il sandboxing si relaziona alle autorizzazioni e alle modalità di autorizzazione

Regole di autorizzazione

Modalità di autorizzazione

Configura la sandbox per la tua organizzazione

Applica il sandboxing con le impostazioni gestite

Impedisci agli sviluppatori di ampliare la politica

Impostazioni del repository con una sandbox richiesta dall'amministratore

Blocchi che si applicano senza una sandbox richiesta dall'amministratore

Configurazione proxy personalizzata

Risoluzione dei problemi

I comandi falliscono con un errore host-not-allowed

`jest` si blocca o fallisce

I CLI basati su Go falliscono la verifica TLS su macOS

`open`, `osascript` o i flussi di autenticazione basati su browser falliscono con errore `-600` su macOS

I comandi `docker` falliscono

`pbcopy`, `xclip` o `wl-copy` non aggiorna gli appunti

Un comando git fallisce con `unable to unlink old`

Bubblewrap non riesce ad avviarsi all'interno di un container

Compaiono file di sola lettura da 0 byte nei percorsi delle impostazioni `.claude`, e "Sì, e non chiedere più" non salva

`git` su SSH fallisce con la sandbox attiva

Un client di database o un altro strumento non HTTP non riesce a raggiungere un host consentito

Un comando non riesce a raggiungere un server su localhost

Un hostname consentito viene rifiutato con `resolved to a loopback address`

`/sandbox` fallisce con `Sandbox settings are overridden by a higher-priority configuration`

Limitazioni

Limitazioni di sicurezza

Ambito

See also