Configura le policy del sandbox

Se un’esecuzione di agente venga incapsulata in un sandbox si decide sul server, all’avvio (--sandbox). L’interruttore Abilita sandboxing e il selettore Backend sotto Impostazioni → Server → Diagnostica e privacy sono preferenze memorizzate sul tuo dispositivo. Il rilevamento dell’host della scheda Sandbox segnala cosa l’host del server può incapsulare.

Due controlli raggiungono un’esecuzione e questa guida li copre entrambi: le regole delle azioni in Impostazioni → Spazio di lavoro → Autorizzazioni degli agenti, che decidono cosa un agente può inviare, aprire o raggiungere, e il flag --sandbox del server stesso.

Cosa vincola un’esecuzione di agente

Sei cose trattengono un agente. La prima è il sandbox del sistema operativo ed è quella condizionale — le altre cinque valgono su ogni host.

Confine	Cosa fa
Il sandbox del sistema operativo	Seatbelt su macOS, bubblewrap su Linux e WSL2. Incapsula la CLI di Claude Code, gli adapter ACP e lo strumento `bash` dell’harness. Assente su Windows e su Linux senza `bwrap` e `socat`
Il suo worktree	Ogni conversazione riceve un checkout copy-on-write. Il checkout originale viene incorporato nell’esecuzione come percorso in diniego di scrittura, e ad applicarlo è il sandbox
Credenziali del broker	Il broker delle credenziali conia un ambiente per esecuzione e lo revoca allo smantellamento. Il suo token GitHub può leggere ma non eseguire push: un push passa da Control Center, che prima interroga la regola di push
Guardrail delle azioni	Ogni strumento che modifica lo stato dichiara le proprie classi di effetto e il guardrail le risolve prima che la chiamata venga eseguita. Un `prompt` senza alcun approvatore collegato viene negato
Sanificazione dell’ambiente	ACP e lo strumento `bash` dell’harness ricevono un ambiente filtrato. Claude Code tramite `NoSandboxAdapter` eredita l’ambiente dell’host
La superficie degli strumenti della modalità	Una modalità di sola lettura rimuove del tutto gli strumenti che mutano il worktree e fissa il verbo di output proprio della modalità, così che possa comunque consegnare

Tre cose restano più deboli di quanto sembrino:

Solo l’harness integrato applica il filtro degli strumenti, i contratti di completamento e le regole strutturali delle modalità. L’adapter Claude Code no. Claude Code in particolare viene avviato con --dangerously-skip-permissions, perché un claude -p non interattivo si bloccherebbe altrimenti per sempre sul proprio prompt — quindi le sue chiamate di lettura, scrittura e modifica non sono né viste né filtrate da Control Center, e i suoi comandi bash li controlla solo un hook che legge la riga di comando. Dove il sandbox è attivo, è il confine che le circonda.
Gli strumenti in-process per i file dell’harness (read, write, edit, apply patch, search, find, search_files) girano dentro il processo del server, quindi nessun profilo di sandbox li vincola. Solo lo strumento bash passa dall’esecutore di comandi nel sandbox. Quegli strumenti sono delimitati dal loro stesso confinamento dei percorsi più i guardrail delle azioni.
Su un host privo di backend la prima riga non si applica affatto. ACP e lo strumento bash dell’harness ripiegano sulla sanificazione dell’ambiente più la policy dei comandi; Claude Code eredita l’ambiente dell’host tramite NoSandboxAdapter. Il server lo dichiara nel proprio log di avvio. Controlla il tuo qui sotto.

Decidi cosa può inviare un agente

Non esiste alcun interruttore per agente per git push, GitHub, ticketing o la rete. Ognuno è una regola delle azioni:

Regola	Predefinito integrato	Cosa copre
Eseguire il push a un remoto	Chiedi prima	Ogni `git push` verso GitHub, qualunque sia l’adapter
Aprire una pull request	Chiedi prima	`gh pr create` e gli strumenti per le pull request
Pubblicare una revisione o unire	Chiedi prima	`gh pr merge`, `gh pr review`, `gh pr comment`, `gh pr close`
Scrivere su un tracker esterno	Chiedi prima	Scritture di ticket tramite gli strumenti di Control Center e `gh issue`
Accedere alla rete	Consenti	Se il sandbox ha una rete, e gli strumenti web dell’harness

Vai su Impostazioni → Spazio di lavoro → Autorizzazioni degli agenti
Scegli l’ambito — Spazio di lavoro, Agente o Spazio — e sulla riga della regola scegli Consenti, Chiedi prima o Nega

Si applicano anche le regole di push limitate ai branch, come una che nega i push su main: vedi Guardrail.

Punto di controllo: chiedi all’agente di eseguire il push di un branch. Con Chiedi prima ricevi un’approvazione che indica il repo e i ref; con Nega git stampa ! [remote rejected] <ref> (Control Center policy: …).

Come ogni regola raggiunge l’esecuzione:

Il push viene applicato in base a ciò che l’esecuzione possiede. Il suo token GitHub è un token di installazione della GitHub App di sola lettura, che può leggere i contenuti e lavorare con le pull request. La sua configurazione git invia ogni push verso GitHub a un gateway di loopback su cc_server, che interroga la regola e solo allora inoltra il push con un token di scrittura che l’agente non vede mai. Il gateway inoltra solo al repo del worktree o a un repo GitHub collegato allo spazio di lavoro. Questo vale per ogni adapter.
Pull request e issue da una shell vengono riconosciute dalla riga di comando, nello strumento bash dell’harness e, tramite un hook, nello strumento Bash di Claude Code. Un agente che nasconde il comando (uno script, eval, una chiamata API diretta) supera questo controllo, ma non il gateway dei push.
Le chiavi di ticketing non vengono mai messe nel sandbox. Gli agenti scrivono i ticket tramite gli strumenti MCP di Control Center, che interrogano la regola.
La rete viene risolta una sola volta, all’avvio dell’esecuzione. Nega disattiva la rete del sandbox; Consenti e Chiedi prima la lasciano attiva, e con Chiedi prima gli strumenti web_fetch e web_search dell’harness continuano a chiedere a ogni chiamata. Finché la rete è attiva, GitHub è sempre nella lista di autorizzazione in uscita.

Verifica se le esecuzioni dei tuoi agenti sono isolate nel sandbox

Due cose lo decidono, entrambe sul server: se l’host offre un backend e se --sandbox è attivo. Controllale in quest’ordine.

Vai su Impostazioni → Server → Diagnostica e privacy
Leggi la scheda Sandbox. La voce Host è la macchina su cui gira cc_server, non quella che stai guardando. Il campo Backend elenca Native sandbox (Seatbelt su macOS, bubblewrap su Linux e WSL2) oppure No isolation. La voce In vigore è la preferenza di questo dispositivo, non l’incapsulamento che il server usa davvero.
Leggi il log di avvio del server. Stampa esattamente una di queste tre righe:
- agent sandbox ON più la nota sul backend — le esecuzioni sono incapsulate
- no OS-native agent sandbox on this host più un suggerimento di installazione dove ce n’è uno — le esecuzioni non sono incapsulate
- agent sandbox DISABLED by --sandbox off — una rinuncia deliberata

GET /healthz non segnala lo stato del sandbox, quindi il controllo è il log di avvio.

Per disattivare il sandbox deliberatamente — un host in cui il profilo si comporta male è la ragione stessa per cui l’opzione esiste — avvia il server con --sandbox off, oppure imposta CC_SERVER_SANDBOX=off. Il valore predefinito è on e on significa «usa un backend se l’host ne ha uno», mai «richiederne uno».

Due situazioni non ottengono mai l’incapsulamento di un sandbox nativo. Su Windows la sonda nativa segnala sempre l’indisponibilità e non c’è nulla da installare — l’invio degli agenti usa none. Il backend microvm è a parte (terminali interattivi e rig) e dipende da una sonda sul proprio runtime. Su Linux e WSL2 sia bwrap sia socat devono essere nel PATH; senza di essi la sonda segnala l’indisponibilità e nomina i pacchetti mancanti.

Su Linux/WSL2 con bubblewrap installato, i glob dei file di segreti della policy standard non possono essere applicati ai file che un agente crea in seguito. Un’esecuzione nativa di questo tipo ora fallisce invece di ignorare in silenzio le regole. Una sonda di avvio positiva non garantisce quindi che un invio su Linux possa partire. --sandbox off è una rinuncia deliberata senza confinamento, non un confine di sicurezza sostitutivo.

Scopri cosa vieta già una modalità

La modalità è memorizzata per spazio e alimenta il risolutore dei guardrail come livello di preimpostazione della modalità. Tre delle quattro modalità sono di sola lettura e una modalità di sola lettura rifiuta senza appello undici classi di effetto:

Modalità	Worktree	Rifiutato dalla preimpostazione
Agente (`chat`)	Scrivibile	Niente — si applicano i valori predefiniti integrati
Piano	Sola lettura	Eliminare un file, scrivere fuori dal worktree, fare commit, fare push, aprire una PR, pubblicare o unire, scrivere su un tracker esterno, installare un pacchetto, avviare un processo, cambiare la struttura dello spazio di lavoro, avviare o pilotare un recinto
Revisione	Sola lettura	Le stesse undici. Non selezionabile dall’utente — il composer offre solo Agente, Piano e Orchestrazione
Orchestrazione	Sola lettura	Le stesse undici

L’accesso alla rete e l’accesso ai segreti non vengono deliberatamente negati da una modalità di sola lettura: la ricerca è il suo scopo.

Richiedi l’approvazione prima che un’azione venga eseguita

L’approvazione è una decisione dei guardrail, non un’impostazione del sandbox.

Vai su Impostazioni → Spazio di lavoro → Autorizzazioni degli agenti
Imposta la classe di azione su Chiedi prima all’ambito dello spazio di lavoro, dell’agente o dello spazio

Una decisione Chiedi prima interrompe l’esecuzione e ti interpella. Senza alcun approvatore collegato fallisce in modo chiuso e l’azione viene negata. Vedi Configura i guardrail per l’ordine di risoluzione completo.

Risoluzione dei problemi

Un agente non riesce a fare push e io non l’ho mai negato

Leggi cosa ha stampato git. Control Center policy: … significa che una regola ha negato il push o che un Chiedi prima è rimasto senza risposta. … is not linked to this workspace significa che il push punta a un repo che non è quello del worktree né è collegato allo spazio di lavoro. Control Center has no GitHub credential that can push … significa che la GitHub App non è installata su quel repo e nessuna credenziale di ripiego ha potuto eseguire il push: installa l’App su quel repo o collega GitHub.

La scheda Sandbox non segnala alcun sandbox nativo

Allora le esecuzioni degli agenti su quell’host non sono incapsulate da Seatbelt o bubblewrap e i confini rimanenti sono tutto ciò che hai. Su Linux e WSL2 installa entrambi gli strumenti mancanti — sudo apt-get install bubblewrap socat — e riavvia il server; il log di avvio dovrebbe quindi dire che il sandbox è attivo. Su Windows non esiste alcun backend nativo da installare, quindi stringi invece i guardrail: vedi Configura i guardrail.

Un agente ha raggiunto un file fuori dal suo worktree

Quale strumento l’ha raggiunto decide se questo sia previsto.

Gli strumenti in-process per i file dell’harness (read, write, edit, apply patch, search, find, search_files) girano nel processo del server, quindi nessun profilo di sandbox si applica a loro — il loro limite è il confinamento dei percorsi degli strumenti stessi più i guardrail. Un comando bash o la CLI di Claude Code viene incapsulato dove esiste un backend e i tuoi checkout registrati sono in diniego di scrittura dentro quell’incapsulamento in ogni modalità, comprese le loro grafie risolte dai symlink (su macOS un percorso raggiunto tramite /tmp o /var/folders si risolve sotto /private ed entrambe le grafie ora vengono negate). Su un host senza backend nulla di tutto ciò si applica. In ogni caso, i guardrail possono rifiutare senza appello Scrivere fuori dal worktree.