Questa pagina è tradotta dalla documentazione inglese. Comandi, identificatori ed esempi restano invariati. Runtime 7.24.4 · SDK 2.6.7. Testo inglese

Modalità sandbox

Stato: Attivo Ambito: stato attuale Ultima revisione: 2026-08-23 Responsabile: runtime di ax-code

AX Code include una sandbox di esecuzione integrata che può limitare ciò che l’agente di IA fa sul sistema. Per impostazione predefinita, AX Code parte in accesso completo con la sandbox spenta, quindi le scritture sul filesystem e l’accesso alla rete non hanno restrizioni. Attiva workspace-write o read-only prima di lavorare con repository non attendibili o di eseguire compiti non presidiati.

Avviso di sicurezza: full-access non è un confine di sicurezza. L’agente può modificare file fuori dal workspace, scrivere .git/ e .ax-code/, eseguire comandi di shell senza restrizioni e accedere alla rete.

Avvio rapido

Attiva o disattiva la sandbox dalla TUI:

• Digita /sandbox nel prompt, oppure
• Premi Ctrl+P e cerca “sandbox”

La barra di stato mostra lo stato corrente:

• sandbox on (verde) — agente confinato al workspace
• sandbox off (rosso) — nessuna restrizione

L’impostazione persiste tra le sessioni in ax-code.json.

Che cosa cambia

Configurazione

Fonte di verità

Questa pagina riassume il comportamento visibile all’utente. Quando il comportamento cambia, verifica la documentazione rispetto a:

• packages/ax-code/src/isolation/index.ts per la risoluzione della modalità, i percorsi protetti, i controlli di rete, di scrittura e di bash, e IsolationDeniedError.
• packages/ax-code/src/config/schema.ts per la forma della configurazione, i predefiniti e le descrizioni.
• packages/ax-code/src/server/routes/isolation.ts per il comportamento dell’interruttore a runtime e la persistenza.
• packages/ax-code/test/isolation/isolation.test.ts e packages/ax-code/test/tool/bash.test.ts per il comportamento di applicazione atteso.

Tieni brevi le affermazioni duplicate nel README alla radice e rimanda qui per i dettagli.

Interruttore dalla TUI

Usa /sandbox o la palette dei comandi (Ctrl+P → “Turn sandbox on/off”). La modifica ha effetto subito e viene salvata nel ax-code.json del progetto.

Flag della CLI

ax-code --sandbox workspace-write   # sandbox on
ax-code --sandbox full-access       # sandbox off
ax-code --sandbox read-only         # strictest: blocks all mutations

Variabile di ambiente

AX_CODE_ISOLATION_MODE=workspace-write ax-code

File di configurazione

In ax-code.json:

{
  "isolation": {
    "mode": "workspace-write",
    "network": false
  }
}

Precedenza

Flag della CLI > variabile di ambiente > file di configurazione > predefinito (full-access)

Quando è attiva una sostituzione da CLI o da ambiente, la TUI riporta quella modalità efficace. Un interruttore /sandbox può salvare la preferenza del progetto, ma la sostituzione a precedenza più alta resta attiva finché non viene rimossa (di norma al riavvio).

Modalità di isolamento

Percorsi protetti

In modalità workspace-write, questi percorsi sono sempre protetti in scrittura:

• .git/ — impedisce la corruzione accidentale dello stato git
• .ax-code/ — impedisce la manomissione di configurazione e plugin

Aggiungi percorsi protetti personalizzati nella configurazione:

{
  "isolation": {
    "mode": "workspace-write",
    "protected": ["secrets", "credentials"]
  }
}

Accesso alla rete

La rete è disattivata per impostazione predefinita nelle modalità workspace-write e read-only. Strumenti interessati:

• webfetch — bloccato
• websearch — bloccato
• codesearch — bloccato
• bash — i client solo di rete (curl, wget, nc/ncat/netcat, telnet, ftp, tftp, scp, sftp, dig, nslookup, host) sono bloccati

Limite: il blocco della rete in bash è a livello applicativo e copre i client di rete dedicati sopra elencati. Non intercetta gli strumenti a doppio uso che funzionano anche offline (git, npm/pnpm/yarn, pip, go, interpreti di linguaggio come python/node), perché le loro invocazioni offline non si distinguono in modo statico e bloccarle romperebbe flussi comuni. Un isolamento di rete vero ed esaustivo richiede controlli a livello di sistema operativo, che questa sandbox non fornisce. Quando si colpisce un client negato, l’agente chiede un’escalation una tantum.

Per consentire la rete mantenendo le restrizioni di scrittura:

{
  "isolation": {
    "mode": "workspace-write",
    "network": true
  }
}

Backend di isolamento (app e sistema operativo)

macOS: profili Seatbelt tramite sandbox-exec (scrittura limitata a workspace e worktree, rete negata quando network: false).
Linux: bubblewrap (bwrap) se installato (--unshare-net quando la rete è disattivata, workspace montato in bind in lettura e scrittura).
Windows: solo livello applicativo, oggi.

{
  "isolation": {
    "mode": "workspace-write",
    "network": false,
    "backend": "auto"
  }
}

Vedi SECURITY.md per il modello delle minacce.

Autorizzazioni e hook controllati dal repository

I file di progetto non sono attendibili per impostazione predefinita. Le regole di autorizzazione in ax-code.json, .ax-code/policy.json e le definizioni di agente o modalità del progetto possono restringere l’accesso con deny, ma le concessioni allow/ask controllate dal repository vengono ignorate. I comandi di progetto non possono attivare l’espansione della shell. .ax-code/hooks.json, .ax-code/plugin/ e i plugin configurati dal progetto non vengono eseguiti.

Anche una configurazione di progetto non attendibile non può selezionare una shell personalizzata, un LSP o un formattatore eseguibile, un pacchetto di provider o un endpoint API, variabili di ambiente delle credenziali del provider, una sorgente di skill esterna o un percorso di istruzioni fuori dal worktree. Restano disponibili i percorsi di istruzioni relativi sicuri e le sostituzioni integrate non eseguibili. I server MCP usano un flusso di approvazione separato, con impronta, descritto in Integrazioni MCP.

Dopo aver revisionato la configurazione controllata dal repository, gli utenti possono aderire fuori dal repository per il processo corrente:

AX_CODE_TRUST_PROJECT_CONFIG=1 ax-code

L’interruttore solo di ambiente impedisce a un checkout di dichiararsi attendibile.

Come funziona l'applicazione

L’applicazione della sandbox è sempre a livello applicativo, controllata a ogni invocazione di strumento. Quando backend è os o auto e la piattaforma lo supporta, bash viene inoltre avvolto in una sandbox del kernel.

Quando uno strumento viola l’isolamento, lancia un IsolationDeniedError con un messaggio chiaro che spiega che cosa è stato bloccato e perché.