Configurazione

Tutta la configurazione risiede nel file .env nella radice del progetto. Questo file è incluso nel gitignore — non viene mai committato.

Variabili d’Ambiente

Provider AI

Il container supporta due modalità di autenticazione mutuamente esclusive (in ordine di priorità):

• Proxy LiteLLM — impostare LITELLM_BASE_URL e LITELLM_API_KEY per instradare attraverso un proxy LiteLLM (vedi sotto).
• Modalità OAuth — impostare solo CLAUDE_CODE_OAUTH_TOKEN (vedi sotto).

Non combinare le modalità — utilizzarne esattamente una.

Claude Max (OAuth)

Variabile	Descrizione	Esempio
CLAUDE_CODE_OAUTH_TOKEN	Token OAuth da un abbonamento Claude Max	sk-ant-oat01-...

Quando impostato, Claude Code si autentica direttamente con Anthropic tramite OAuth — non è necessaria alcuna chiave API o proxy. Ottenere il token dalle impostazioni di Claude Code o dalla console Anthropic.

Proxy LiteLLM

Se il vostro proxy LiteLLM (o altro) supporta già nativamente l’API Anthropic Messages — inclusi web_search, streaming e utilizzo degli strumenti — impostare LITELLM_BASE_URL sul dominio del proxy. Il container deriva automaticamente gli URL specifici del provider:

• Endpoint Anthropic → ${LITELLM_BASE_URL}/anthropic (utilizzato da Claude Code)
• Endpoint compatibile OpenAI → ${LITELLM_BASE_URL}/openai/v1

Variabile	Descrizione	Esempio
LITELLM_BASE_URL	Dominio del vostro proxy LiteLLM (senza suffisso di percorso)	https://litellm.example.com
LITELLM_API_KEY	Chiave API per l’autenticazione al proxy	your-api-key o predefinita a litellm-proxy

Gli utenti devono impostare solo il dominio — i suffissi di percorso del provider vengono aggiunti automaticamente. A runtime, l’entrypoint deriva ANTHROPIC_API_KEY da LITELLM_API_KEY in modo che Claude Code possa utilizzare le credenziali del proxy senza richiedere una variabile separata lato utente.

I nomi dei modelli non vengono rimappati in questa modalità. Claude Code invia i suoi identificatori di modello standard (es. claude-sonnet-4-6) e LiteLLM li instrada verso il backend configurato.

Validazione dei Certificati TLS

Per impostazione predefinita, Node.js valida i certificati TLS per tutte le connessioni HTTPS. Se il vostro provider API upstream utilizza un certificato auto-firmato (comune con proxy interni Open WebUI o LiteLLM), è possibile disabilitare la validazione aggiungendo questo al file .env:

NODE_TLS_REJECT_UNAUTHORIZED=0

Questo non è raccomandato per l’uso in produzione. Impostare questo valore solo quando ci si fida del percorso di rete tra il container e il vostro endpoint API.

Agenti di Coding AI

Il container include diversi agenti di coding AI oltre a Claude Code:

Agente	Comando	Provider
Codex	codex	Compatibile OpenAI
Pi	pi	Multi-provider (configurare a runtime)
Oh-My-Pi	omp	Multi-provider (configurare a runtime)

Pi e Oh-My-Pi sono installati come pacchetti npm globali. Codex è un binario standalone che si auto-aggiorna a runtime.

Display Remoto (noVNC)

Il container esegue uno stack di display virtuale per visualizzare e interagire con browser con interfaccia grafica. Consultare Display Remoto (noVNC) per le istruzioni di connessione e le variabili d’ambiente (ENABLE_VNC, VNC_RESOLUTION, DISPLAY, NOVNC_HOST_PORT).

Chrome DevTools MCP

Il container include un server Chrome DevTools MCP preconfigurato per l’automazione del browser headless. Claude Code può navigare pagine web, acquisire screenshot e ispezionare il DOM senza alcuna configurazione aggiuntiva. Consultare Chrome DevTools MCP per i dettagli.

Git

Variabile	Descrizione	Come Impostare
GIT_AUTHOR_NAME	Nome per i commit git	git config user.name
GIT_AUTHOR_EMAIL	Email per i commit git	git config user.email

Se git è configurato sul vostro host, è possibile popolare automaticamente entrambi i valori:

echo "GIT_AUTHOR_EMAIL=$(git config user.email)" >> .env
echo "GIT_AUTHOR_NAME=\"$(git config user.name)\"" >> .env

SSH

Variabile	Descrizione	Come Impostare
SSH_PRIVATE_KEY	Chiave privata codificata in Base64	base64 < ~/.ssh/id_ed25519

GitHub CLI

Variabile	Descrizione	Come Impostare
GH_TOKEN	Token di accesso personale GitHub per la CLI gh e git HTTPS	gh auth token (se gh è installato localmente)

Quando GH_TOKEN è impostato nel .env, la CLI gh si autentica automaticamente — non è necessario eseguire gh auth login. L’entrypoint esegue anche gh auth setup-git, che configura l’helper delle credenziali git in modo che git clone e git push via HTTPS funzionino senza chiavi SSH.

Se gh è installato e autenticato sulla vostra macchina host, è possibile estrarre il token direttamente:

echo "GH_TOKEN=$(gh auth token)" >> .env

Altrimenti, creare un token di accesso personale e aggiungerlo manualmente. Funzionano sia i token fine-grained (raccomandati) che i token classici. I token fine-grained permettono di limitare l’accesso a repository specifici. I token classici richiedono lo scope repo per l’accesso ai repository privati.

Per verificare l’autenticazione all’interno del container:

gh auth status

Come Vengono Installati gli Strumenti

Ogni runtime di linguaggio, CLI e strumento viene installato direttamente nel Dockerfile al momento della build dell’immagine. L’immagine pre-compilata viene pubblicata su ghcr.io/f5-sales-demo/devcontainer:latest ad ogni push su main, quindi la maggior parte degli utenti non ha mai bisogno di compilare localmente.

Docker

L’esecuzione di docker compose up -d scarica automaticamente l’immagine pre-compilata. Per compilare localmente dopo aver personalizzato il Dockerfile, passare esplicitamente il file di build:

docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build

Consultare Sviluppo Locale per i dettagli.

Podman

L’esecuzione di podman-compose up -d scarica automaticamente l’immagine pre-compilata. Per compilare localmente dopo aver personalizzato il Dockerfile, passare esplicitamente il file di build:

podman-compose -f docker-compose.yml -f docker-compose.build.yml up -d --build

Consultare Sviluppo Locale per i dettagli.

Il Dockerfile utilizza una build a due stadi ottimizzata per il caching dei layer Docker. Consultare Sviluppo Locale — Architettura di Build a Due Stadi per il dettaglio completo dei layer e le informazioni sulla cache di build.

Consapevolezza degli Strumenti di Claude Code

Il container include una configurazione integrata che impedisce a Claude Code di confondere i nomi degli strumenti. La consapevolezza degli strumenti è installata su due livelli di memoria per una difesa in profondità:

• Policy gestita (/etc/claude-code/CLAUDE.md) — installata al momento della build Docker. Questo è il livello con la priorità più alta nella gerarchia di memoria di Claude Code e viene sempre caricato, anche quando esiste un CLAUDE.md di progetto di grandi dimensioni nella directory di lavoro.
• Memoria utente (~/.claude/CLAUDE.md) — popolata dall’entrypoint al primo avvio. Fornisce un livello di backup e una copia visibile e personalizzabile per gli utenti.

Priorità dei Livelli di Memoria

Claude Code carica le istruzioni da più livelli di memoria (dalla priorità più alta alla più bassa):

1. Policy gestita (/etc/claude-code/) — Sempre caricata, non può essere esclusa
2. Memoria di progetto (./CLAUDE.md) — Caricata per directory di progetto
3. Memoria utente (~/.claude/CLAUDE.md) — Caricata globalmente per tutte le sessioni
4. Memoria locale (./CLAUDE.local.md) — Override personali per progetto

Senza il livello della Policy gestita, la consapevolezza degli strumenti nella Memoria utente può essere deprioritizzata quando compete con un CLAUDE.md a livello di progetto di grandi dimensioni, causando la perdita da parte di Claude della consapevolezza dei nomi degli strumenti in PascalCase. Il livello della Policy gestita garantisce che la consapevolezza degli strumenti sia sempre caricata con la priorità più alta.

Auto-Test

Eseguire l’auto-test integrato per verificare la configurazione:

claude-self-test

Questo controlla che tutti i file di configurazione siano presenti e contengano i riferimenti agli strumenti previsti.

Aggiungere Strumenti

Per aggiungere strumenti all’immagine, modificare il Dockerfile e ricompilare localmente. Consultare Sviluppo Locale — Aggiungere Strumenti per le istruzioni sull’aggiunta di pacchetti APT, strumenti npm, strumenti pip e download di binari.

Estensioni VS Code

Le estensioni sono configurate in .devcontainer/devcontainer.json sotto customizations.vscode.extensions e vengono installate automaticamente all’apertura in VS Code.

Persistenza dei Dati

Tutti i dati risiedono in volumi nominati — nessuna directory host viene montata:

Volume	Punto di Mount	Contenuti
workspace	/workspace	I vostri repository clonati e file di progetto
home	/home/vscode	Cronologia shell, configurazioni degli strumenti, cache, chiavi SSH

Docker

Entrambi persistono tra riavvii e ricompilazioni del container. Eseguire docker compose pull per scaricare l’ultima immagine pre-compilata prima di riavviare.

Azione	Dati
docker compose down	Preservati
docker compose down -v	Eliminati

Podman

Entrambi persistono tra riavvii e ricompilazioni del container. Eseguire podman-compose pull per scaricare l’ultima immagine pre-compilata prima di riavviare.

Azione	Dati
podman-compose down	Preservati
podman-compose down -v	Eliminati

Mappatura delle Porte

Host	Container	Servizio
127.0.0.1:${NOVNC_HOST_PORT:-6080}	6080	Display remoto noVNC (solo localhost, sovrascrivere con NOVNC_HOST_PORT)

Le porte sono associate a 127.0.0.1 in modo che siano accessibili solo dalla vostra macchina, non dalla rete.