Claude Code in un devcontainer

Un ambiente di sviluppo sandbox per eseguire Claude Code con bypassPermissions abilitato in sicurezza. Realizzato presso Trail of Bits per flussi di lavoro di audit di sicurezza.

Perché usarlo?

Eseguire Claude con bypassPermissions sulla tua macchina host è rischioso: può eseguire qualsiasi comando senza conferma. Questo devcontainer fornisce isolamento del filesystem in modo da ottenere i vantaggi di produttività di Claude senza restrizioni senza mettere a rischio il tuo sistema host.

Progettato per:

• Audit di sicurezza: esaminare il codice del cliente senza rischiare il tuo host
• Repository non fidati: esplorare codebase sconosciuti in sicurezza
• Lavoro sperimentale: lasciare che Claude modifichi il codice liberamente in isolamento
• Impegni multi-repo: lavorare su più repository correlati

Prerequisiti

• Runtime Docker (uno tra):

  • Docker Desktop – assicurati che sia in esecuzione
  • OrbStack
  • Colima: brew install colima docker && colima start

• Per flussi di lavoro da terminale (installazione una tantum):

  npm install -g @devcontainers/cli
  git clone https://github.com/trailofbits/claude-code-devcontainer ~/.claude-devcontainer
  ~/.claude-devcontainer/install.sh self-install
  

# Ferma ed elimina la VM corrente (rimuove contenitori/immagini)
colima stop && colima delete

# Avvia con impostazioni ottimizzate
colima start \
  --cpu 4 \
  --memory 8 \
  --disk 100 \
  --vm-type vz \
  --vz-rosetta \
  --mount-type virtiofs

Avvio rapido

Scegli il modello che si adatta al tuo flusso di lavoro:

Modello A: Contenitore per progetto (isolato)

Ogni progetto ottiene il proprio contenitore con volumi indipendenti. Ideale per revisioni una tantum, repo non fidati o quando hai bisogno di isolamento tra progetti.

Terminale:

git clone <repo-non-fidato>
cd repo-non-fidato
devc .          # Installa il template + avvia il contenitore
devc shell      # Apre una shell nel contenitore

VS Code / Cursor:

1. Installa l'estensione Dev Containers:

   • VS Code: ms-vscode-remote.remote-containers
   • Cursor: anysphere.remote-containers

2. Configura il devcontainer (scegli una opzione):

   # Opzione A: usa devc (consigliato)
   devc .
   
   # Opzione B: clona manualmente
   git clone https://github.com/trailofbits/claude-code-devcontainer .devcontainer/
   

3. Apri la cartella del tuo progetto in VS Code, quindi:

   • Premi Cmd+Shift+P (Mac) o Ctrl+Shift+P (Windows/Linux)
   • Digita "Reopen in Container" e seleziona Dev Containers: Reopen in Container

Modello B: Contenitore con area di lavoro condivisa (raggruppato)

Una directory padre contiene la configurazione del devcontainer e cloni più repository al suo interno. Volumi condivisi tra tutti i repo. Ideale per impegni con clienti, repository correlati o lavoro continuativo.

# Crea un'area di lavoro per un impegno cliente
mkdir -p ~/sandbox/nome-cliente
cd ~/sandbox/nome-cliente
devc .          # Installa il template + avvia il contenitore
devc shell      # Apre una shell nel contenitore

# All'interno del contenitore:
git clone <repo-cliente-1>
git clone <repo-cliente-2>
cd repo-cliente-1
claude          # Pronto per lavorare

Autenticazione basata su token (headless)

Per server headless o per saltare la procedura guidata di login interattiva:

claude setup-token                          # esegui sull'host, una tantum
export CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-...
devc rebuild                                # ricostruisce con il token

Il token viene inoltrato nel contenitore. A ogni creazione del contenitore, post_install.py esegue un handshake di autenticazione one-shot in modo che claude si avvii senza la procedura guidata di login.

Questo risolve il problema della procedura guidata di onboarding interattiva di Claude Code che appare sempre nei contenitori, anche con credenziali valide (#8938).

Se non imposti un token, il flusso di login interattivo funziona come prima.

Comandi helper CLI

devc .              Installa il template + avvia il contenitore nella directory corrente
devc up             Avvia il devcontainer
devc rebuild        Ricostruisce il contenitore (preserva i volumi persistenti)
devc destroy [-f]   Rimuove contenitore, volumi e immagine per il progetto corrente
devc down           Ferma il contenitore
devc shell          Apre una shell zsh nel contenitore
devc exec CMD       Esegue un comando all'interno del contenitore
devc upgrade        Aggiorna Claude Code nel contenitore
devc mount SRC DST  Aggiunge un bind mount (host → contenitore)
devc sync [NAME]    Sincronizza le sessioni di Claude Code dai devcontainer all'host
devc template DIR   Copia i file devcontainer in una directory
devc self-install   Installa devc in ~/.local/bin

Nota: Usa devc destroy per pulire le risorse Docker di un progetto. Rimuovere i contenitori manualmente (es. docker rm) lascerà volumi e immagini orfani che devc destroy non sarà in grado di trovare.

Sincronizzazione delle sessioni per /insights

Il comando /insights di Claude Code analizza la cronologia delle sessioni, ma legge solo da ~/.claude/projects/ sull'host. Le sessioni all'interno dei volumi del devcontainer sono invisibili.

devc sync copia i log delle sessioni da tutti i devcontainer (in esecuzione e fermati) sull'host, in modo che /insights possa includerli:

devc sync              # Sincronizza tutti i devcontainer
devc sync crypto       # Filtra per nome progetto (corrispondenza parziale)

I devcontainer vengono scoperti automaticamente tramite i label Docker — non è necessario conoscere nomi o ID dei contenitori. La sincronizzazione è incrementale, quindi è sicuro eseguirla ripetutamente.

Condivisione dei file

VS Code / Cursor

Trascina i file dal tuo host nel pannello Explorer di VS Code — vengono copiati automaticamente in /workspace/. Nessuna configurazione necessaria.

Terminale: devc mount

Per rendere disponibile una directory dell'host all'interno del contenitore:

devc mount ~/drop /drop           # Lettura-scrittura
devc mount ~/secrets /secrets --readonly

Questo aggiunge un bind mount a devcontainer.json e ricrea il contenitore. I mount esistenti vengono preservati durante gli aggiornamenti del template devc template.

Consiglio: Una "cartella di drop" condivisa è utile per passare file senza montare l'intera home directory.

Nota sulla sicurezza: Evita di montare grandi directory dell'host (es. $HOME). Ogni percorso montato è scrivibile dall'interno del contenitore a meno che non venga specificato --readonly, il che compromette l'isolamento del filesystem fornito da questo progetto.

Isolamento di rete

Per impostazione predefinita, i contenitori hanno pieno accesso alla rete in uscita. Per una sicurezza più rigorosa, usa iptables per limitare l'accesso di rete.

Quando abilitare l'isolamento di rete