> ## Documentation Index
> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# 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](#sandbox-modes) 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](#what-runs-outside-the-sandbox).
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.
Questa pagina tratta la sandbox attorno ai comandi shell sulla tua macchina. Altre pagine trattano argomenti correlati:
* Per scoprire come viene isolata una sessione cloud, consulta [Sicurezza e isolamento](/docs/it/claude-code-on-the-web#security-and-isolation)
* Per confrontare altri approcci di isolamento come dev container, container personalizzati e macchine virtuali, consulta [Ambienti sandbox](/docs/it/sandbox-environments)
* Per ridurre le richieste di permesso per strumenti diversi da Bash, consulta [modalità di permesso](/docs/it/permission-modes)
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](#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`.
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](/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) |
| 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) |
| 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) |
| 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) |
Claude Code crea la sandbox a partire dal pacchetto open source [`@anthropic-ai/sandbox-runtime`](https://github.com/anthropics/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](/docs/it/permissions). Una voce `denyRead` non blocca lo strumento Read e `allowedDomains` non limita WebFetch
* **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
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 `!`](/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
* **Comandi esclusi**: i comandi che corrispondono a [`excludedCommands`](#run-commands-outside-the-sandbox-with-excludedcommands) vengono eseguiti fuori dalla sandbox
* **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
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](/docs/it/sandbox-environments).
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](#set-up-linux-and-wsl2). Anche se non li hai ancora installati, puoi iniziare con `/sandbox`, perché il suo pannello mostra se manca qualcosa
Avvia una sessione di Claude Code ed esegui il comando `/sandbox`:
```text theme={null}
/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`](/docs/it/settings-reference#sandbox-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](#set-up-linux-and-wsl2), riavvia Claude Code ed esegui di nuovo `/sandbox`.
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.
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`.
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.
Per ampliare o restringere ciò che la sandbox consente, consulta [Configurare il sandboxing](#configure-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](#bubblewrap-fails-to-start-inside-a-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`](/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).
Per 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:
```bash theme={null}
claude --settings '{"sandbox": {"enabled": true, "allowUnsandboxedCommands": false}}'
```
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.
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 `!`](#what-runs-outside-the-sandbox) 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`](https://github.com/containers/bubblewrap): lo strumento di sandboxing non privilegiato che applica l'isolamento del filesystem
* [`socat`](http://www.dest-unreach.org/socat/): il relay usato per instradare il traffico di rete attraverso il proxy della sandbox
Installali con il gestore di pacchetti della tua distribuzione:
```bash theme={null}
sudo apt-get install bubblewrap socat
```
```bash theme={null}
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 ,
include
profile bwrap /usr/bin/bwrap flags=(unconfined) {
userns,
include if exists
}
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
```
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](/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.
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](/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).
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](#hosts-outside-your-allowed-domains) spiega chi decide se la connessione viene stabilita.
Anche in modalità auto-allow, continuano ad applicarsi i seguenti punti:
* Le [regole di negazione](/docs/it/permissions) esplicite vengono sempre rispettate
* 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
* 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
* 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
* I comandi dello [strumento Monitor](/docs/it/tools-reference#monitor-tool) non vengono approvati automaticamente, anche se vengono comunque eseguiti nella sandbox. Per evitare la richiesta di conferma, aggiungi una [regola allow](/docs/it/permissions#bash) che corrisponda al comando, come `Bash(npm run *)`
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.
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.
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](/docs/it/permission-modes#eliminate-prompts-with-auto-mode)**: 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](/docs/it/permission-modes#analyze-before-you-edit-with-plan-mode)
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](/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
* **[`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
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](/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**.
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](#repository-settings-under-an-admin-required-sandbox) le elenca.
La 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:
* **Una [sessione in background](/docs/it/agent-view)**: la modalità sandbox rigorosa copre anche i comandi in modalità shell
* **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
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](#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.
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`](/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.
Personalizza il comportamento della sandbox tramite il file `settings.json`. Consulta [Impostazioni](/docs/it/settings-reference#sandbox-settings) 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](/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:
```json theme={null}
{
"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](/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).
Se 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.
Quando 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.
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](/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).
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](/docs/it/settings-reference#sandbox-path-prefixes) 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:
```json theme={null}
{
"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`](/docs/it/settings-reference#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`](/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.
Questo esempio porta i comandi `docker compose` fuori dalla sandbox. Salvalo in `~/.claude/settings.json` per applicarlo a tutti i tuoi progetti:
```json theme={null}
{
"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](/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
* **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](/docs/it/settings-reference#sandbox-excludedcommands) elenca altre chiamate che restano in sandbox
* **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`
Un comando escluso segue il normale flusso dei permessi:
* 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
* 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)".
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.
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:
```json theme={null}
{
"sandbox": {
"enabled": true,
"filesystem": {
"disabled": true
},
"network": {
"allowedDomains": ["github.com", "*.npmjs.org"]
}
}
}
```
La 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.
`sandbox.filesystem.disabled` ha `false` come valore predefinito. Richiede Claude Code v2.1.216 o successivo.
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.
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`](/docs/it/env-vars) è impostata, Claude Code ignora `filesystem.disabled` da ogni origine, incluse le impostazioni gestite, e mantiene attivo l'isolamento del filesystem.
Una 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.
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`](#protect-credentials) | 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`](#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` |
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`](/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.
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](#disable-filesystem-isolation); 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:
```json theme={null}
{
"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](#mask-credentials).
I percorsi dei file seguono le stesse [regole sui prefissi](/docs/it/settings-reference#sandbox-path-prefixes) delle impostazioni `sandbox.filesystem.*`.
Claude 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.
Quando [escludi un'origine di impostazioni](#configure-sandboxing):
* **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](#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).
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`](/docs/it/env-vars).
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](#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. Il riferimento di [`sandbox.credentials`](/docs/it/settings-reference#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`](/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. Per verificare questa configurazione errata, esegui `claude doctor` nel terminale e cerca l'avviso `TLS termination is unavailable`.
* **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`.
* **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).
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`:
```json theme={null}
{
"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`](/docs/it/settings-reference#sandbox-credentials-envvars) 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](#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.
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`](/docs/it/settings-reference#sandbox-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`](/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.
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](#mask-credentials) 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](#disable-filesystem-isolation).
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:
```json theme={null}
{
"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`](/docs/it/settings-reference#sandbox-credentials-files) per controllare il mascheramento parziale e cosa succede quando il pattern non trova corrispondenze.
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).
`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`](/docs/it/settings-reference#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](#protect-credentials) che non vuoi che i comandi leggano.
* **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.
* **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.
Per saltare completamente l'isolamento del filesystem mantenendo l'isolamento di rete, imposta [`sandbox.filesystem.disabled`](#disable-filesystem-isolation).
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](/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:
* **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`](#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`.
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`](#a-git-command-fails-with-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](#a-database-client-or-other-non-http-tool-fails-to-reach-an-allowed-host)
* **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](#hosts-outside-your-allowed-domains) 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](/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.
* **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).
* **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.
* **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.
* **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.
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.
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) 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.
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](/docs/it/permission-modes#skip-all-checks-with-bypasspermissions-mode) | 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](#per-command-allowed-domains-in-auto-mode) e il classificatore non abbia approvato l'elenco |
| Modalità `dontAsk` | Rifiutata |
Con [`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.
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](/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.
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](#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.
Un 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.
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](https://github.com/containers/bubblewrap) per l'isolamento
* **WSL2**: utilizza bubblewrap, come Linux
Puoi 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).
Come il sandboxing si relaziona alle autorizzazioni e alle modalità di autorizzazione
Il sandboxing, le [regole di autorizzazione](/docs/it/permissions), e le [modalità di autorizzazione](/docs/it/permission-modes) 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`](/docs/it/tools-reference#endconversation-tool-behavior) mentre rimane qualsiasi altro strumento.
* **Il sandboxing** fornisce un'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 ai comandi degli strumenti Bash, PowerShell e [Monitor](/docs/it/tools-reference#monitor-tool) 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`](#disable-filesystem-isolation) | 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](https://github.com/anthropics/claude-code/tree/main/examples/settings) 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](/docs/it/permission-modes). 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](#sandbox-modes) |
| [Modalità automatica](/docs/it/permission-modes#eliminate-prompts-with-auto-mode) | 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](/docs/it/permission-modes#protected-paths) vengono anche saltati; le [azioni che nessuna modalità auto-approva](/docs/it/permission-modes#actions-no-mode-auto-approves) si applicano ancora |
La [modalità auto-allow](#sandbox-modes) della sandbox è separata dalla [modalità automatica](/docs/it/permission-modes#eliminate-prompts-with-auto-mode): 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](#sandbox-modes). Per scegliere un limite di isolamento per esecuzioni incustodite, vedere [Ambienti sandbox](/docs/it/sandbox-environments#how-isolation-relates-to-permission-modes). Per una tabella degli accoppiamenti comuni di modalità di autorizzazione e sandbox con i flag che avviano ciascuno, vedere [Configurazioni comuni](/docs/it/permission-modes#common-setups).
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](/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.
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:
```json theme={null}
{
"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](#repository-settings-under-an-admin-required-sandbox)
* 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
Questa 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.
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](/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
* **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](#repository-settings-under-an-admin-required-sandbox). Ognuna indebolisce la sandbox, quindi impostala su `false` nelle impostazioni gestite se non vuoi che venga usata:
* [`enableWeakerNestedSandbox`](/docs/it/settings-reference#sandbox-enableweakernestedsandbox)
* [`enableWeakerNetworkIsolation`](/docs/it/settings-reference#sandbox-enableweakernetworkisolation)
* [`network.allowAllUnixSockets`](/docs/it/settings-reference#sandbox-network-allowallunixsockets)
* [`network.allowLocalBinding`](/docs/it/settings-reference#sandbox-network-allowlocalbinding)
* [`allowAppleEvents`](/docs/it/settings-reference#sandbox-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`](/docs/it/settings-reference#sandbox-network-allowmanageddomainsonly). Con il blocco attivo, solo le impostazioni gestite possono impostare una [porta proxy](#custom-proxy-configuration).
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`](#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).
Impostazioni del repository con una sandbox richiesta dall'amministratore
La sandbox è richiesta dall'amministratore mentre è in vigore una di queste impostazioni:
* [`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`
* [`allowManagedDomainsOnly`](/docs/it/settings-reference#sandbox-network-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](#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.
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](#network-isolation). 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](/docs/it/settings-reference#sandbox-settings):
```json theme={null}
{
"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](#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
* **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.
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.
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](#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.
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](#run-commands-outside-the-sandbox-with-excludedcommands).
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`](/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.
`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](#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`.
`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`](/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.
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`](#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.
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`](#run-commands-outside-the-sandbox-with-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`](/docs/it/commands). `/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`](/docs/it/settings-reference#sandbox-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](#protected-paths) 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](#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.
Bubblewrap non riesce ad avviarsi all'interno di un container
In 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.
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`](/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.
`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](#network-isolation), 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:
```bash theme={null}
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`](#run-commands-outside-the-sandbox-with-excludedcommands):
```json theme={null}
{
"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](#a-database-client-or-other-non-http-tool-fails-to-reach-an-allowed-host).
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](#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.
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`](#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:
```json theme={null}
{
"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`](/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
* **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)
Questo esempio attiva l'impostazione per macOS:
```json theme={null}
{
"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`](#an-allowed-hostname-is-refused-with-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](#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`.
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:
```json theme={null}
{
"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](/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.
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`](/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.
* **`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`](/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.
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.
* **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](#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:
* **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).
* **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.
* **Sessioni in background**: una [sessione in background](/docs/it/agent-view) viene eseguita nel proprio processo, e i suoi comandi Bash vengono sandboxati quando [le sue impostazioni](/docs/it/agent-view#settings-and-provider) abilitano il sandboxing.
* **Un confine attorno all'intero processo**: per porre dietro un confine anche i processi elencati in [Cosa viene eseguito al di fuori della sandbox](#what-runs-outside-the-sandbox), esegui Claude Code (modalità locale) all'interno del [sandbox runtime](/docs/it/sandbox-environments#sandbox-runtime) con un'allowlist di rete limitata agli host che approvi, oppure nel [dev container](/docs/it/devcontainer) con il suo script firewall. Per il servizio in background e le sessioni che ospita, consulta [Eseguire Claude Code dietro un launcher aziendale](/docs/it/corporate-launcher).
* **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).
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.
See also
* [Sandbox environments](/docs/it/sandbox-environments): confronta la sandbox integrata con dev container, container e VM
* [Sicurezza](/docs/it/security): funzionalità di sicurezza e best practice
* [Permissions](/docs/it/permissions): configurazione delle autorizzazioni e controllo dell'accesso
* [All settings](/docs/it/settings-reference): ogni chiave di configurazione
* [CLI reference](/docs/it/cli-reference): opzioni della riga di comando