Claude Code Docker: eseguire agenti AI nei container

Gli agenti AI per il coding autonomi sono potenti. Navigano nel tuo filesystem, eseguono comandi shell, effettuano commit e modificano file, tutto senza che tu scriva una sola riga di codice. Ma quel potere porta con sé una domanda concreta: cosa succede se qualcosa va storto? E se l'agente modificasse un file di configurazione che non dovrebbe toccare o installasse un pacchetto in conflitto con il tuo sistema?

La risposta a cui approdano la maggior parte degli sviluppatori orientati alla produzione è Docker, ed è la stessa a cui sono tornato anch'io dopo una sessione in cui Claude Code ha pensato bene di "ripulire" il file .env del mio progetto perché sembrava inutilizzato. (Non lo era.) 

I container creano un confine netto tra l'agente e la tua macchina host, e quel confine è ciò che fa percepire le esecuzioni non presidiate come sicure anziché ansiogene. 

In questo tutorial ti mostrerò come eseguire Claude Code all'interno di Docker: dalla creazione di un'immagine di base minimale all'orchestrazione di un'applicazione multi-servizio con Docker Compose. Alla fine avrai un flusso di lavoro sicuro e ripetibile da usare su qualsiasi progetto.

Se ti interessano i modelli più recenti di Anthropic, ti consiglio di leggere le nostre guide su Claude Opus 4.6 e Claude Sonnet 4.6.

Come Claude Code si integra con Docker

Per capire perché Docker è così adatto a Claude Code, è utile comprendere brevemente cosa fa ciascuno strumento.

Claude Code è lo strumento agentico da riga di comando di Anthropic per il coding, rilasciato per la disponibilità generale a maggio 2025. Vive nel tuo terminale, legge il tuo codebase ed esegue attività (refactoring del codice, scrittura di test, gestione dei flussi di lavoro git) tramite prompt in linguaggio naturale. Il nostro Tutorial su Claude Code 2.1 copre tutto ciò che devi sapere.

Docker è una piattaforma per impacchettare ed eseguire applicazioni in container leggeri e isolati che condividono il kernel del sistema operativo host ma mantengono confini rigorosi di processi e filesystem. Se sei completamente nuovo a Docker, ti consiglio di dare un'occhiata alla nostra guida sulla piattaforma gratuita Play with Docker e fare qualche esperimento lì.

Claude Code ha bisogno di un ambiente in cui girare. Docker ne fornisce uno riproducibile e usa e getta. La combinazione è potente, ma per sfruttarla al massimo devi capire il modello di esecuzione, i valori predefiniti di sicurezza e quale approccio di deploy si adatta al tuo caso.

Architettura del container e flusso di esecuzione

Partiamo da come funziona, a livello di richiesta, una sessione di Claude Code containerizzata.

1. Invii un prompt dal terminale dell'host. 
2. Docker avvia il container con la CLI di Claude Code preinstallata e il tuo workspace montato come volume. 
3. Claude Code legge i file da quel mount, ragiona sul codebase, esegue comandi nello spazio di processo isolato del container e scrive l'output nel volume montato. 
4. Alla fine della sessione, il filesystem effimero del container (tutto ciò che è fuori dal mount) viene scartato.

La distinzione chiave è tra stato effimero e stato persistente. Qualsiasi cosa scritta nel container ma fuori dal volume montato viene eliminata in fase di cleanup. Il tuo workspace, che vive sull'host ed è montato nel container, persiste. 

Questo significa che dipendenze temporanee, artefatti di build e installazioni di tool spariscono, ma i file reali del tuo progetto restano esattamente come li ha lasciati Claude. Trovo questa separazione davvero rassicurante: prima di capirla, stavo lì nervoso a guardare le sessioni dell'agente. Ora avvio un task e vado a farmi un caffè.

Modelli di sicurezza e impostazioni sicure di default

Con il flusso di esecuzione in mente, vale la pena essere espliciti su cosa protegge davvero l'isolamento di Docker e cosa no.

L'isolamento del filesystem è il principale vantaggio in termini di sicurezza. Claude Code può leggere e scrivere file solo nei percorsi che monti esplicitamente. Se non li monti nel container, le tue chiavi SSH, le credenziali ~/.aws, le variabili d'ambiente dell'host e i file di configurazione di sistema sono invisibili all'agente a meno che non li esponi deliberatamente. Tuttavia, questa protezione vale solo se configuri i mount con attenzione.

Una regola critica: non montare mai la socket Docker dell'host (/var/run/docker.sock) nel container di Claude Code. Se l'agente può parlare con il demone Docker sul tuo host, potrebbe avviare container privilegiati, evadere completamente la sandbox e ottenere accesso di livello root alla tua macchina. 

È un percorso di escalation dei privilegi ben noto e senza una buona giustificazione. L'ho visto suggerito in alcuni Dockerfile della community come modo per far "gestire i container" all'agente, e ogni volta vorrei scrivere all'autore un messaggio molto deciso.

Scegliere il giusto percorso di deploy

Al di là dei default di sicurezza, c'è un'ultima decisione da prendere prima di scrivere codice: quale modello di deploy si adatta al tuo caso d'uso? Le opzioni principali sono tre, e non sono intercambiabili.

Per la maggior parte dei task (eseguire l'agente su una singola repo, fare il debug di uno script, fare refactoring di un modulo), una semplice sandbox Docker è il default più sicuro. 

Docker Compose ha senso quando Claude Code deve interagire con un database in esecuzione, un'API o un servizio frontend. 

I devcontainer sono la scelta giusta per ambienti standardizzati a livello di team con estensioni IDE preconfigurate. Da notare che il devcontainer di riferimento ufficiale di Anthropic include un firewall integrato che limita le connessioni in uscita a una allowlist di domini attendibili, e quell'isolamento è ciò che rende sicuro eseguire Claude Code con --dangerously-skip-permissions per un'operatività completamente non presidiata. 

In questo tutorial copriremo sia la sandbox a container singolo sia una configurazione Compose.

Configurare un container Docker per Claude Code

Ora che architettura e opzioni di deploy sono chiare, assicuriamoci che l'ambiente sia configurato correttamente prima di scrivere codice. Ho visto saltare questo passaggio più volte di quante ne possa contare, ed è il motivo più comune per cui tutorial come questo falliscono a metà strada.

Requisiti di sistema e software

Ecco tutto ciò che ti serve prima del primo docker build:

• Docker Desktop (macOS o Windows) o Docker Engine (Linux), con il demone attivo. Su macOS e Windows, la virtualizzazione deve essere abilitata nelle impostazioni del BIOS/firmware. Su Linux, aggiungi il tuo utente al gruppo docker con sudo usermod -aG docker $USER, oppure anteponi sudo a ogni comando Docker.

• Node.js v18 o successivo sulla tua macchina host, dato che la CLI di Claude Code è un pacchetto npm. Conferma con node --version.

• Una chiave API Anthropic, che puoi generare nella Claude Console.

Verifica rapidamente che Docker sia in salute con un sanity check prima di proseguire:

docker run --rm hello-world

Se vedi Hello from Docker!, il tuo demone risponde correttamente e puoi procedere.

Autenticazione e variabili d'ambiente

Con il demone confermato funzionante, la prossima cosa da impostare correttamente sono le credenziali. Iniettare la tua chiave API Anthropic come variabile d'ambiente a runtime è sostanzialmente più sicuro che effettuare il login in modo interattivo dentro il container. 

L'ho imparato a mie spese: i login interattivi possono incorporare le credenziali nei layer del container o nei file di cronologia della shell, che restano su disco a lungo dopo che te ne sei dimenticato.

Il pattern corretto è passare la chiave a runtime usando -e:

docker run --rm -e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" my-claude-image

Nota che faccio riferimento a $ANTHROPIC_API_KEY dalla mia shell host. La chiave non viene mai scritta nel Dockerfile, mai commitata nel controllo versione e non appare in alcun layer dell'immagine. Impostala una volta nel profilo della tua shell (~/.zshrc o ~/.bashrc) e fluirà pulita in ogni esecuzione del container da quel momento in poi.

Inizializzazione del workspace

Sistemata l'autenticazione, l'ultimo passo di setup è creare un workspace pulito. Creo sempre una directory dedicata per ogni sessione dell'agente invece di puntare Claude a un progetto esistente, perché elimina il rischio che l'agente vaghi in codice adiacente che non intendevi toccasse.

mkdir ~/claude-docker-tutorial
cd ~/claude-docker-tutorial
echo "# My Project" > README.md
echo "def hello(): return 'world'" > app.py

Mantieni pulita questa directory. Non copiare il tuo vero file .env o credenziali. Il workspace dovrebbe contenere solo il codice su cui vuoi che l'agente lavori, nient'altro. Con questo in atto, siamo pronti a buildare.

Eseguire Claude Code in Docker

Con l'ambiente configurato e i concetti chiari, è il momento di buildare. Questa sezione illustra i passaggi: prima, un'immagine minimale a container singolo, poi una sessione sandbox funzionante e infine uno stack Compose multi-servizio completo. Ogni passaggio si basa sul precedente, quindi ti consiglio di seguirli in ordine invece di saltare avanti.

1. Creare l'immagine base del container

Tutto in questa sezione si fonda sui principi di sicurezza discussi prima. Ecco un Dockerfile minimale che li mette in pratica, installando la CLI di Claude Code su un'immagine base Node.js slim:

FROM node:20-slim

# Create a non-root user for safer execution
RUN useradd -m -u 1001 claude

# Install Claude Code CLI globally
RUN npm install -g @anthropic-ai/claude-code

# Set the working directory
WORKDIR /workspace

# Switch to non-root user
USER claude

ENTRYPOINT ["claude"]

Vale la pena spiegare alcune scelte progettuali. Uso node:20-slim invece di node:20-alpine perché Alpine usa la libreria libc musl, che a volte causa problemi di compatibilità con i pacchetti npm nativi. 

Mi è capitato proprio questo al primo tentativo con Alpine: la CLI di Claude Code si installava, ma andava in crash al primo avvio con un oscuro errore del linker che mi ha richiesto un'ora per ricondurre a musl. 

La variante slim è basata su Debian: leggera e affidabile, senza quel tipo di drammi. Inoltre, creo un utente dedicato claude e passo a questo utente prima dell'entrypoint, così il processo dell'agente gira senza privilegi di root e limita ciò che può fare anche dentro il container.

Builda l'immagine con:

docker build -t claude-code:latest .

Alla prima build, Docker scarica l'immagine base e installa la CLI. Alle build successive senza cambi al Dockerfile, vedrai “CACHED” accanto a ogni layer, rendendo i rebuild quasi istantanei una volta stabilita la base.

2. Avviare una sessione sandbox isolata

Con l'immagine pronta, è ora di eseguire la prima sessione reale. 

Operazioni in sola lettura

Per task in sola lettura come elencare o riassumere i file, basta il comando base:

docker run --rm \
  -e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
  -v $(pwd):/workspace \
  claude-code:latest \
  "List the files in this workspace and describe what each one does."

L'opzione -v $(pwd):/workspace monta la tua directory corrente nel container, quindi il comando funziona da qualunque directory di progetto. Il flag --rm rimuove automaticamente il container al termine.

Operazioni di scrittura

Le operazioni di scrittura richiedono due flag aggiuntivi. 

Il flag -u $(id -u):$(id -g) passa l'UID e il GID del tuo utente host nel container, dando al processo claude il permesso di scrivere sui file montati. Senza di esso, otterrai un errore di filesystem in sola lettura perché l'utente claude del container non corrisponde al proprietario dei file sull'host. 

Il flag --dangerously-skip-permissions salta i prompt di approvazione interattivi di Claude Code, necessari quando si esegue in modo non interattivo dentro un container. È il confine Docker a rendere questa scelta sicura.

docker run --rm \
  -e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
  -v $(pwd):/workspace \
  -u $(id -u):$(id -g) \
  claude-code:latest \
  --dangerously-skip-permissions \
  "Add a docstring to the hello function in app.py."

Operazione di scrittura di Claude Code in Docker

Poi verifica il tuo file locale: cat app.py. Se vedi la docstring, il mount del volume funziona in entrambe le direzioni e sei pronto a passare a una configurazione multi-servizio.

3. Orchestrare un'app multi-servizio

La sandbox a container singolo funziona bene per task isolati, ma lo sviluppo reale spesso coinvolge più servizi in esecuzione simultaneamente. Qui è dove Docker Compose si guadagna il suo posto.

La configurazione seguente collega l'agente Claude Code con un servizio web e un database PostgreSQL, un setup rappresentativo per molti progetti backend:

services:
  claude:
    build: .
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
    volumes:
      - ./workspace:/workspace
    depends_on:
      db:
        condition: service_healthy
    networks:
      - app-network

  web:
    image: python:3.12-slim
    working_dir: /app
    volumes:
      - ./workspace:/app
    command: python -m http.server 8080
    ports:
      - "8080:8080"
    networks:
      - app-network

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: appdb
      POSTGRES_USER: user
      POSTGRES_PASSWORD: password
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U user -d appdb"]
      interval: 5s
      timeout: 3s
      retries: 5
    networks:
      - app-network

networks:
  app-network:
    driver: bridge

Nota che version è omesso, perché è obsoleto nel Docker Compose moderno e se incluso genera un avviso. 

Altri due dettagli degni di nota:

Primo, il servizio claude monta .:/workspace (la directory corrente) anziché una sottodirectory. Usare ./workspace richiederebbe l'esistenza di una sottocartella separata e l'agente vedrebbe un workspace vuoto. 

Secondo, DATABASE_URL viene passato esplicitamente così l'agente sa come raggiungere Postgres. Senza di esso, Claude non ha una connection string e te ne chiederà una.

La riga user: "${UID}:${GID}" applica lo stesso override di UID/GID dell'host usato nei comandi docker run standalone, così le scritture su file funzionano correttamente. Esportali entrambi prima di eseguire:

export UID=$(id -u) GID=$(id -g)

Il servizio claude non ha un command persistente, quindi a differenza di web e db non è pensato per restare in esecuzione continua. Avvia prima i servizi di supporto, poi invoca Claude on demand con docker compose run:

# Avvia il database e il servizio web
docker compose up -d web db

# Esegui un task una tantum con Claude
docker compose run --rm \
  claude \
  --dangerously-skip-permissions \
  "Check the database connection and summarize the schema in README.md."

Claude Code con Docker Compose

Avvia prima i servizi di supporto con docker compose up -d web db, poi osserva i loro log con docker compose logs -f. Nota il depends_on con condition: service_healthy. 

L'ho saltato in un progetto all'inizio e ho passato 20 minuti a rincorrere errori di connessione al database prima di rendermi conto che Claude era partito prima che Postgres fosse pronto. L'health check non costa nulla e ti risparmia esattamente quel mal di testa.

4. Gestire il cleanup della sessione

Una volta completata la sessione, il cleanup è importante quanto il setup. I container orfani consumano memoria e interferiscono con le esecuzioni future e, per esperienza, è il passaggio che più spesso viene saltato finché qualcosa non inizia a comportarsi in modo strano.

Ecco i comandi che userai più spesso e quando ricorrere a ciascuno:

L'opzione -v su docker compose down è quella da usare con cautela. Elimina i volumi nominati, quindi qualsiasi dato accumulato in Postgres andrà perso. La uso solo quando voglio davvero ripartire da zero. Altrimenti docker compose down da solo è sufficiente.

Integrazioni e troubleshooting di Claude Code con Docker

Con il flusso di lavoro principale che gira pulito, vediamo come estenderlo e come fare debug quando qualcosa si rompe.

Integrare modelli locali ed estensioni

Claude Code supporta il reindirizzamento dell'inferenza a qualsiasi endpoint locale compatibile con Anthropic tramite ANTHROPIC_BASE_URL. Docker Model Runner, integrato in Docker Desktop, espone proprio un'API di questo tipo, rendendo l'integrazione nativa nell'ecosistema Docker.

Scarica un modello e punta Claude Code all'endpoint locale:

docker model pull ai/smollm2
ANTHROPIC_BASE_URL=http://localhost:12434 claude --model ai/smollm2 "List the files of the repository."

Questo è un pattern diverso rispetto all'approccio con container sandbox visto prima. Qui, Claude Code gira sull'host e l'inferenza resta locale tramite Docker Model Runner, quindi nessuna chiamata API lascia la tua macchina.

Oltre ai modelli locali, puoi estendere la portata di Claude Code tramite i server MCP (Model Context Protocol). Se non lo conosci, la nostra Guida a MCP è un'ottima risorsa per iniziare.

La MCP Toolkit di Docker fornisce oltre 200 server MCP preconfigurati e containerizzati che coprono GitHub, Jira, Supabase e altro, dando a Claude Code accesso autorizzato a quegli strumenti senza esporre credenziali API grezze. 

Insieme, questi due punti di estensione ti danno un controllo significativo sia su dove avviene l'inferenza sia su quali servizi esterni l'agente può raggiungere.

Ottimizzare le prestazioni di build

Man mano che il tuo Dockerfile cresce, il tempo di build può diventare un collo di bottiglia. Le build multi-stage risolvono separando l'installazione dall'immagine di runtime:

# Build stage
FROM node:20-slim AS builder
RUN npm install -g @anthropic-ai/claude-code

# Runtime stage
FROM node:20-slim
COPY --from=builder /usr/local/lib/node_modules /usr/local/lib/node_modules
COPY --from=builder /usr/local/bin/claude /usr/local/bin/claude
RUN useradd -m -u 1001 claude
USER claude
WORKDIR /workspace
ENTRYPOINT ["claude"]

L'ordine dei layer conta tanto quanto la struttura, e questo è qualcosa che ho sbagliato per più tempo di quanto vorrei ammettere. 

Le istruzioni che cambiano raramente (come l'installazione di pacchetti di sistema) vanno in alto. Quelle che cambiano spesso (come la copia dei file sorgente) vanno in basso. Così massimizzi i cache hit e trasformi rebuild da 30 secondi in quasi istantanei.

Debug dei guasti di integrazione più comuni

Anche con un setup ben strutturato, le cose si rompono. Ecco un loop di debug ripetibile per i problemi che incontro più spesso. Sintomo per primo, poi il comando da eseguire:

• Uscita di rete bloccata: Claude Code non riesce a raggiungere l'API di Anthropic. Esegui docker run --rm alpine wget -qO- https://api.anthropic.com per verificare l'accesso in uscita. Se fallisce, controlla docker network inspect bridge per impostazioni di proxy.

• Mount di volumi errati: Claude Code segnala che non trova i file. Esegui docker run --rm -v $(pwd):/workspace alpine ls /workspace. Un elenco vuoto significa che il percorso è sbagliato. Conferma prima di tutto che la directory esista.

• Cache di build obsoleta: Hai aggiornato il Dockerfile, ma il comportamento non è cambiato. Forza una rebuild completa con docker build --no-cache -t claude-code:latest ..

• Guasti di connessione tra servizi in Compose: Un servizio non riesce a raggiungerne un altro. I servizi comunicano tramite i loro nomi di servizio (db, web), non localhost. Esegui docker compose exec web ping db per testare la raggiungibilità. Un ping fallito significa che i servizi non sono sulla stessa rete.

Conclusione

Eseguire Claude Code dentro Docker ti dà qualcosa di davvero prezioso: la libertà di lasciare lavorare un agente autonomo, sapendo che ciò che può toccare è rigidamente delimitato. 

In questo tutorial ho illustrato come costruire un'immagine container minimale senza privilegi di root, gestire i volumi del workspace, orchestrare applicazioni multi-servizio con Docker Compose e diagnosticare i guasti di integrazione più comuni. 

Mi ci è voluto circa un pomeriggio per mettere a punto il setup, e ha cambiato completamente il mio approccio allo sviluppo assistito dagli agenti. Delego interi task invece di osservare ogni passo, e il confine Docker è ciò che lo rende possibile.

Da qui, vale la pena esplorare due direzioni:

Primo, valuta i template di devcontainer per il tuo team. Il devcontainer di riferimento di Claude Code su GitHub include un firewall preconfigurato che limita le connessioni in uscita a domini attendibili. Secondo, sperimenta con Docker MCP Toolkit per dare a Claude Code accesso strutturato ai tuoi strumenti esistenti: GitHub, database, sistemi di project management e altro.

Infine, imposta un promemoria per aggiornare periodicamente le immagini di base. Le immagini Docker accumulano vulnerabilità nel tempo e un rapido docker pull node:20-slim seguito da una rebuild richiede solo pochi minuti.

Se sei interessato a sviluppare applicazioni di intelligenza artificiale, ti consiglio vivamente di iscriverti al nostro percorso di competenze AI Engineering with LangChain. I corsi inclusi sono nativi AI, quindi avrai un insegnante personale che ti segue esattamente al tuo livello e ti aiuta a raggiungere i tuoi obiettivi al tuo ritmo.