Configurare ambienti cloud

Configurare ambienti cloud per le sessioni cloud di Claude Code: livelli di accesso di rete, variabili di ambiente, script di configurazione e caching dell'ambiente.

Ogni sessione cloud viene eseguita in un ambiente cloud. È possibile configurare un ambiente per consentire o negare l'accesso di rete, impostare variabili di ambiente per la sessione, sui piani Pro e Max memorizzare credenziali API che le sessioni utilizzano senza vederle, ed eseguire uno script di configurazione prima che Claude inizi a lavorare.

Gli stessi ambienti si applicano ovunque avviate una sessione cloud: l'app Desktop, l'app mobile Claude, il vostro browser su claude.ai/code, il terminale con claude --cloud, routine e Claude Tag. Ognuna di queste superfici può anche instradare a un ambiente self-hosted. Disponibilità e limitazioni copre cosa Claude non può ancora utilizzare quando una sessione Claude Tag viene eseguita in uno.

L'ambiente Default

Se non avete ancora un ambiente, l'onboarding configura l'ambiente Default per voi. Come dipende da dove eseguite l'onboarding:

• Flussi CLI come /web-setup: creano Default per voi
• Onboarding web su Pro e Max: crea Default per voi
• Onboarding web su Team ed Enterprise: mostra un modulo Create your first cloud environment a meno che un Owner non abbia attivato Quick web setup; mantenete i valori predefiniti del modulo e fate clic su Create & finish per ottenere lo stesso ambiente Default

Default non ha alcuna configurazione propria:

• Accesso di rete Trusted: le sessioni raggiungono i registri dei pacchetti e altri domini consentiti, e nient'altro attraverso la rete della sessione.
• Nessun'altra configurazione: Default non definisce variabili di ambiente o script di configurazione, quindi le sessioni iniziano con solo gli strumenti preinstallati.

Con solo Default disponibile, ogni sessione viene eseguita in esso. Quando si dispone di più di un ambiente, le sessioni ne scelgono uno per superficie:

• Nell'app Desktop, nell'app mobile e su claude.ai/code, le sessioni che avviate voi stessi utilizzano l'ambiente mostrato nel selettore. Un default dell'organizzazione impostato da un Owner riempie la selezione quando non ne avete scelto uno. I thread in un progetto utilizzano invece l'ambiente impostato nelle impostazioni del progetto.
• Dalla CLI, Claude Code utilizza la vostra scelta /remote-env, o ricade nell'ambiente ospitato da Anthropic quando il vostro elenco ne ha uno, e altrimenti nel primo ambiente nel vostro elenco che non è un ambiente bridge, una voce Remote Control che registra per rappresentare la vostra macchina piuttosto che un ambiente cloud. Per un ambiente self-hosted, passare --environment <environment-id> con il suo ID ccpool_ quando inviate una sessione sostituisce la scelta /remote-env e il fallback per quella invocazione. Claude Code rifiuta gli ID env_ ospitati da Anthropic passati al flag, quindi utilizzate /remote-env per indirizzare quelli. Il flag richiede Claude Code v2.1.224 o successiva.

Configurate un ambiente quando il default non è sufficiente: quando Claude ha bisogno di raggiungere domini al di fuori della lista di consentiti predefinita, ha bisogno di variabili di ambiente impostate per le sue sessioni, o ha bisogno di dipendenze installate prima di iniziare a lavorare.

Configurare il vostro ambiente

Create, modificate e archiviate gli ambienti dal selettore di ambiente, che raggiungete su claude.ai/code dopo l'onboarding web, oppure dalla casella di messaggio nell'app Desktop. Gli ambienti che create sono personali al vostro account; gli ambienti condivisi creati da un Owner appaiono nello stesso selettore. Consultate Strumenti installati per vedere cosa è disponibile senza alcuna configurazione.

1

Aprire il selettore di ambiente

Su claude.ai/code, selezionate l'icona cloud che mostra il nome dell'ambiente corrente, nella riga sopra la casella di messaggio. Non c'è una pagina di impostazioni o un URL diretto per il selettore.

2

Aggiungere o modificare un ambiente

Selezionate Add cloud environment, oppure passate il mouse su un ambiente esistente e selezionate l'icona delle impostazioni che appare a destra. La finestra di dialogo include il nome, il livello di accesso di rete, le variabili di ambiente e lo script di configurazione. Quando modificate un ambiente cloud esistente su un piano Pro o Max, la finestra di dialogo include anche credenziali API.

Impostare le variabili di ambiente

Le variabili di ambiente utilizzano il formato .env, una coppia KEY=value per riga. I valori semplici non hanno bisogno di virgolette, e se quotate un valore con una coppia corrispondente, le virgolette non diventano parte del valore. Quotate un valore che si estende su più righe o contiene un #: in un valore non quotato, # inizia un commento e il resto della riga viene eliminato.

L'esempio seguente definisce tre variabili.

NODE_ENV=development
LOG_LEVEL=debug
DATABASE_URL=postgres://localhost:5432/myapp

Ogni sessione copia i valori dell'ambiente una volta, all'avvio, in variabili di ambiente ordinarie che qualsiasi comando eseguito da Claude può leggere. Poiché le sessioni in esecuzione non rileggono la configurazione, la modifica o l'aggiunta di variabili influisce sulle sessioni che avviate in seguito; le sessioni già in esecuzione mantengono i valori con cui sono state avviate.

Una sessione cloud imposta anche alcune variabili da sola quando si avvia. Per CLAUDE_AUTOCOMPACT_PCT_OVERRIDE, il valore che la sessione imposta sostituisce uno che aggiungete qui, quindi aggiungere quella chiave qui non ha effetto.

Chiunque utilizzi l'ambiente può leggere i valori. Sui piani Pro e Max, utilizzate una credenziale API invece per una chiave che il proxy dell'agente può allegare a una richiesta. Le richieste che non ricevono mai una credenziale sono elencate lì.

Aggiungere credenziali API

Una credenziale API è una chiave API o un token che memorizzate in un ambiente cloud in modo che Claude possa chiamare quell'API da qualsiasi sessione nell'ambiente senza vedere la chiave. Il proxy dell'agente di Anthropic aggiunge la chiave alle richieste per gli host che elencate, dopo che ogni richiesta esce dalla VM della sessione. La chiave non raggiunge mai Claude, i comandi che esegue, o le variabili di ambiente della sessione.

Le credenziali API sono disponibili sui piani Pro e Max. Non sono ancora disponibili sui piani Team o Enterprise, quindi la sezione API credentials non appare nella finestra di dialogo dell'ambiente su quei piani.

Requisiti

Due di questi decidono se potete aggiungere una credenziale, e due decidono se il proxy dell'agente può utilizzarla una volta aggiunta:

• Ruolo: un ruolo di amministratore dell'organizzazione nella vostra organizzazione claude.ai
  • Su Team ed Enterprise, gli Owner lo detengono e gli Admin no
  • Su Pro e Max, lo detenete nella vostra organizzazione personale
  • Senza di esso, vedete una nota invece dell'elenco delle credenziali, anche sui vostri ambienti personali. Chiedete a un Owner di aggiungere la credenziale a un ambiente condiviso ed eseguite le vostre sessioni lì
• Tipo di ambiente: un ambiente cloud ospitato da Anthropic che già esiste. Un ambiente self-hosted non ha credenziali API
• Raggiungibilità API: l'API accetta connessioni da internet, perché le richieste escono dalla rete di Anthropic
• Chiavi di crittografia: se la vostra organizzazione utilizza chiavi di crittografia gestite dal cliente, non potete salvare credenziali

Aggiungere una credenziale

Aggiungete le credenziali una alla volta dall'editor di un ambiente che già esiste. La finestra di dialogo per un nuovo ambiente non le offre. Non c'è nemmeno modifica. Per modificare gli host o il valore di una credenziale, cancellatela e aggiungetela di nuovo.

Per confermare che la credenziale funziona, avviate una sessione nell'ambiente e chiedete a Claude di chiamare l'API, ad esempio con curl. L'API risponde come se la chiave fosse nella richiesta, e la chiave non appare nelle variabili di ambiente della sessione o in nessun file. Se l'elenco contrassegna una credenziale Not sent, la nota sotto di essa dice perché e cosa fare. Due credenziali i cui host si sovrappongono senza corrispondere esattamente non ricevono alcun marcatore, e il proxy dell'agente ne invia solo una.

Quali richieste ricevono la credenziale

Il proxy dell'agente allega una credenziale a una richiesta quando l'host della richiesta corrisponde a uno che avete elencato su quella credenziale. Le sessioni possono raggiungere quegli host anche quando il livello di accesso di rete dell'ambiente non lo permetterebbe altrimenti, tranne gli host che non ricevono mai la credenziale. La credenziale si applica in ogni sessione che viene eseguita nell'ambiente, chiunque l'abbia avviata, finché non la cancellate.

Richieste che non ricevono mai la credenziale

Il proxy dell'agente non allega mai una credenziale che aggiungete a queste richieste:

• GitHub: il proxy GitHub autentica le richieste a GitHub invece, quindi non avete bisogno di una credenziale API per esso
• L'API Anthropic e i registri di pacchetti pubblici: api.anthropic.com, registry.npmjs.org, jsr.io, npm.jsr.io, pypi.org, files.pythonhosted.org, index.crates.io e proxy.golang.org
• Richieste dello script di configurazione: Claude Code si connette al proxy dell'agente quando si avvia, dopo che lo script di configurazione è stato eseguito

Selezionare un ambiente dalla CLI

Eseguite /remote-env nel vostro terminale per scegliere l'ambiente predefinito per le sessioni cloud che create dalla CLI, come claude --cloud. Il comando apre un selettore dei vostri ambienti esistenti e salva la vostra scelta nella chiave remote.defaultEnvironmentId nelle vostre impostazioni utente, quindi si applica in ogni progetto sulla vostra macchina fino a quando non la cambiate, a meno che la stessa chiave non sia impostata a un livello di impostazioni di precedenza più alta, come le impostazioni del progetto di un repository.

Un ID di ambiente self-hosted, che ha la forma ccpool_..., segue una regola di origine più ristretta. Consultate remote.defaultEnvironmentId per i livelli di impostazioni che Claude Code onora da esso.

/remote-env imposta solo il default: non avvia una sessione e non può aggiungere o modificare ambienti. Gestite gli ambienti dal selettore di ambiente.

Archiviare un ambiente

Per archiviare uno dei vostri ambienti, apritelo per la modifica e selezionate Archive. Un Owner archivia un ambiente condiviso dalla pagina Cloud environments nelle impostazioni di amministrazione. Non potete eliminare un ambiente, solo archiviarlo.

L'archiviazione influisce sulle nuove sessioni, non su quelle in esecuzione:

• Le sessioni già in esecuzione nell'ambiente continuano a funzionare.
• L'ambiente scompare dal selettore e da /remote-env, quindi non potete sceglierlo per le nuove sessioni.
• Le credenziali API sull'ambiente rimangono allegate nelle sue sessioni in esecuzione. Cancellate quelle che non desiderate più prima di archiviare.
• Nessuna nuova sessione può iniziare in un ambiente archiviato, su nessuna superficie. Se l'ambiente era il vostro default CLI salvato, Claude Code avvia le sessioni cloud CLI nell'ambiente ospitato da Anthropic quando il vostro elenco ne ha uno, e altrimenti nel primo ambiente nel vostro elenco che non è un ambiente bridge Remote Control. Qualsiasi cosa configurata con l'ambiente esplicitamente, come una routine, non può avviare nuove sessioni in esso. Puntate a un altro ambiente.

Ambienti condivisi dell'organizzazione

Sui piani Team ed Enterprise, un Owner può creare ambienti cloud che sono condivisi con ogni membro dell'organizzazione. Lo stesso ruolo gestisce tutto il resto sulla pagina Cloud environments dell'amministrazione, inclusi gli ambienti self-hosted; il ruolo Admin non può aprire la pagina. L'elenco completo dei ruoli che possono aprirla è quello per gestire le impostazioni gestite dal server.

Gli ambienti condivisi appaiono nel selettore di ambiente di ogni membro sotto un'intestazione Organization, dopo gli ambienti personali del membro sotto Personal, quindi un team può standardizzare su una configurazione invece di farla ricreare a ogni membro. Selezionando l'icona delle impostazioni di un ambiente condiviso lì apre un riepilogo di sola lettura della sua configurazione per ogni membro, Owner inclusi.

Un Owner rende un ambiente disponibile all'organizzazione in uno di due modi:

• Creare un ambiente condiviso: utilizzate la pagina Cloud environments nelle impostazioni di amministrazione, che è anche dove gli Owner modificano e archiviano gli ambienti condivisi. Ognuno ha un nome, un livello di accesso di rete, variabili di ambiente in formato .env e uno script di configurazione.
• Condividere un ambiente personale: aprite uno dei vostri ambienti per la modifica nel selettore di ambiente, quindi condividetelo dalla riga Who can use it. L'ambiente mantiene il suo ID, quindi le sessioni e le routine che lo utilizzano già non sono interessate, e ogni membro può quindi vederlo e avviare sessioni in esso.

Gli Owner scelgono l'ambiente predefinito dell'organizzazione separatamente, su claude.ai/admin-settings/claude-code.

Le sessioni di ogni membro in un ambiente condiviso leggono le sue variabili, quindi non includete segreti in esse. Le credenziali API, che danno alle sessioni una chiave che non possono leggere, non sono ancora disponibili sui piani Team o Enterprise.

Impostare l'ambiente che un canale Claude Tag utilizza

Nei canali Claude Tag, Claude lavora come identità condivisa della vostra organizzazione, non come nessun membro, quindi le sessioni dei canali utilizzano solo ambienti a livello di organizzazione, sia ambienti condivisi che ambienti self-hosted. Per dare a un canale un toolchain che non è preinstallato, come .NET, un Owner può creare un ambiente condiviso dalla pagina Cloud environments dell'amministrazione con uno script di configurazione che lo installa. Puntate il canale a un ambiente in uno di due modi:

• Impostate un ambiente condiviso o self-hosted come l'ambiente predefinito dell'organizzazione su claude.ai/admin-settings/claude-code.
• Fissate uno a un canale nelle impostazioni di amministrazione di Claude Tag.

Accesso di rete

Ogni ambiente imposta un livello di accesso di rete, che controlla le connessioni in uscita che le sue sessioni possono effettuare. Il livello predefinito, Trusted, consente i registri dei pacchetti e altri domini consentiti; Custom accetta il vostro elenco di domini.

Per modificare l'accesso di rete di un ambiente, apritelo per la modifica e utilizzate il selettore Network access nella finestra di dialogo. Un ambiente condiviso si apre in sola lettura lì, quindi un Owner modifica il suo accesso di rete dalla pagina Cloud environments nelle impostazioni di amministrazione invece. L'icona cloud che apre il selettore appare sulle superfici dell'app elencate sotto L'ambiente Default e nell'editor di routine; gli ambienti personali non hanno una pagina separata nelle impostazioni del vostro account claude.ai.

Livelli di accesso

Il campo Network access nella finestra di dialogo dell'ambiente accetta uno di quattro livelli:

Qualunque livello scegliate, le sessioni possono ancora raggiungere questi, perché ognuno prende un percorso che non passa attraverso l'elenco di consentiti di rete della sessione:

• GitHub, attraverso il suo proxy separato
• I connettori MCP che abilitate, il cui traffico viaggia attraverso i server di Anthropic
• Gli host che avete elencato sulle credenziali API dell'ambiente, tranne gli host che non ricevono mai la credenziale
• L'API Anthropic, per le richieste di Claude Code stesso, anche a None, come notato sotto Sicurezza e isolamento

Consentire domini specifici

Per consentire domini che non sono nella lista Trusted, selezionate Custom nelle impostazioni di accesso di rete dell'ambiente, quindi elencate un dominio per riga nel campo Allowed domains. Questo esempio consente tre host che un progetto interno potrebbe necessitare.

api.example.com
*.internal.example.com
registry.example.com

Le sessioni in questo ambiente possono ora raggiungere api.example.com, qualsiasi sottodominio di internal.example.com e registry.example.com, e nessun altro dominio attraverso la rete della sessione. Il traffico GitHub, il traffico del connettore MCP e le richieste agli host delle credenziali API dell'ambiente, diversi dagli host che non ricevono mai la credenziale, non passano attraverso questo elenco di consentiti. Un *. iniziale corrisponde a ogni sottodominio. Per mantenere anche i domini Trusted, selezionate Also include default list of common package managers; lasciatelo deselezionato per consentire solo quello che elencate.

Se la vostra organizzazione utilizza gli artifact, non avete bisogno di *.frame.claudeusercontent.com nell'elenco affinché le sessioni li leggano. Quando l'elenco lascia fuori quell'host, Claude Code legge il contenuto dell'artifact attraverso la connessione della sessione ad Anthropic invece. Mantenete l'host in un elenco di consentiti in due situazioni:

• Le sessioni in questo ambiente aprono gli artifact pubblici di un'altra organizzazione: Claude Code li recupera dall'host direttamente, quindi aggiungetelo a questo elenco.
• State configurando la CLI locale o un runner self-hosted: mantenete l'host in quell'elenco di consentiti. Consultate i requisiti di accesso di rete e i requisiti di rete self-hosted.

Ogni ambiente ha il suo elenco di domini consentiti; non c'è un elenco di consentiti a livello di organizzazione che gli amministratori possono spingere agli ambienti di ogni membro. Le impostazioni gestite dal server si applicano ancora all'interno delle sessioni cloud, ma nessuna di esse aggiunge domini all'elenco di consentiti di rete dell'ambiente. Per dare a un team un elenco standard, un Owner può creare un ambiente condiviso dall'organizzazione con accesso di rete Custom e quell'elenco.

Proxy GitHub

Negli ambienti ospitati da Anthropic, tutte le operazioni GitHub passano attraverso un proxy dedicato che mantiene le vostre credenziali GitHub reali al di fuori della VM della sessione, indipendentemente dal livello di accesso dell'ambiente. Le sessioni in un ambiente self-hosted si autenticano con le operazioni git con le credenziali che la vostra distribuzione fornisce; Configurare git copre le opzioni, incluse le credenziali coniate per sessione e un opt-in a questo stesso proxy. Il proxy fornisce:

• Credenziali Git: il client git all'interno della VM utilizza una credenziale con ambito, che il proxy verifica e scambia con il vostro token GitHub effettivo.
• Richieste API: le richieste dagli strumenti GitHub integrati e da gh sotto il segnaposto proxy-injected, vengono inviate con le vostre credenziali reali sostituite.
• Protezione push: git push funziona solo contro il ramo di lavoro corrente della sessione; la clonazione, il recupero e le operazioni PR funzionano normalmente.
• Ambito del repository: le richieste API GitHub e di asset di rilascio raggiungono solo i repository collegati alla sessione, quindi uno script di configurazione che scarica asset di rilascio da un repository non collegato riceve un 403.
• Restrizioni GraphQL: il proxy serve solo un set fisso di operazioni GraphQL per i flussi di lavoro delle pull request. Il proxy rifiuta tutto il resto sull'endpoint GraphQL con un 403 che dice This GraphQL query is not enabled for this session e nomina il fallback REST, gh api repos/{owner}/{repo}/.... La restrizione si applica a ogni richiesta attraverso il proxy indipendentemente dalle credenziali che fornite, quindi un GH_TOKEN che impostate riceve lo stesso 403. Claude non può raggiungere le API GitHub che esistono solo in GraphQL, come Projects v2, attraverso il proxy.

I file sottoposti a commit dai repository pubblici arrivano tramite raw.githubusercontent.com, che il proxy di sicurezza gestisce invece. Quel dominio è nella lista Trusted predefinita, quindi quei file rimangono raggiungibili a meno che il livello di accesso dell'ambiente non lo escluda.

Proxy di sicurezza

Le sessioni cloud negli ambienti ospitati da Anthropic vengono eseguite dietro un proxy di rete HTTP/HTTPS per scopi di sicurezza e prevenzione degli abusi; in un ambiente self-hosted, il traffico in uscita esce attraverso il vostro confine di rete invece. Tutto il traffico internet in uscita da una sessione ospitata da Anthropic passa attraverso questo proxy, che fornisce:

• Protezione contro richieste dannose
• Limitazione della velocità e prevenzione degli abusi
• Filtro dei contenuti per una sicurezza migliorata
• Un audit trail a livello DNS dei nomi host richiesti

Cosa è disponibile nelle sessioni cloud

Negli ambienti ospitati da Anthropic, ogni sessione ottiene una macchina virtuale (VM) fresca che esegue Ubuntu 24.04 su x86_64, indipendentemente dal vostro sistema operativo e dall'architettura della CPU, con il vostro repository clonato e i toolchain comuni preinstallati. Quando una dipendenza fornisce binari precompilati, come gem Ruby con estensioni native o wheel Python precostruiti, utilizzate la sua build Linux x86_64 per corrispondere alla VM. Questa sezione copre i default ospitati da Anthropic, gli strumenti GitHub integrati, come eseguire test e servizi, e i limiti di risorse che ogni VM ottiene.

Cosa viene trasferito dalla vostra configurazione

Le sessioni cloud iniziano da un clone fresco del vostro repository. Qualsiasi cosa che sottoponete a commit nel repository è disponibile. Qualsiasi cosa che avete installato o configurato solo sulla vostra macchina non è disponibile nella sessione. La politica della vostra organizzazione arriva separatamente attraverso le impostazioni gestite dal server.

Per rendere disponibile la vostra configurazione nelle sessioni cloud, sottoponete a commit nel repository.

Chiunque utilizzi l'ambiente può leggere le sue variabili di ambiente e lo script di configurazione. La nota della finestra di dialogo sotto Environment variables lo dice e avverte contro l'aggiunta di segreti lì. Sui piani Pro e Max, memorizzate una chiave che il proxy dell'agente può allegare come credenziale API invece.

Strumenti installati

Le sessioni cloud vengono fornite con runtime di linguaggio comuni, strumenti di build e database preinstallati. La tabella seguente riassume cosa è incluso per categoria.

¹ Bun è installato ma ha problemi di compatibilità noti con il proxy per il recupero dei pacchetti.

Per ottenere le versioni della maggior parte degli strumenti in questa tabella, chiedete a Claude di eseguire check-tools in una sessione cloud. È un comando shell installato sulla VM della sessione, non un comando che digitate con /; chiedete a Claude perché Claude esegue tutti i comandi della VM per voi. Per uno strumento che non segnala, come Ruby, PHP, bun, PostgreSQL o Redis, chiedete a Claude di eseguire il comando di versione dello strumento stesso, ad esempio psql --version.

Le versioni di Node.js sono installate su /opt/node20, /opt/node21 e /opt/node22, con 22 su PATH per impostazione predefinita. Per lavorare con una versione diversa, chiedete a Claude di anteporre la directory bin di quella versione, come /opt/node20/bin, a PATH.

I toolchain al di fuori di questo elenco, come .NET SDK, non sono preinstallati anche quando i loro registri di pacchetti sono sulla lista di consentiti predefinita. Installateli con uno script di configurazione.

Lavorare con i problemi e le pull request di GitHub

Le sessioni cloud includono strumenti GitHub integrati che consentono a Claude di leggere i problemi, elencare le pull request, recuperare i diff e pubblicare commenti senza alcuna configurazione. Questi strumenti si autenticano attraverso il proxy GitHub utilizzando il metodo che avete configurato sotto Opzioni di autenticazione GitHub, quindi il vostro token non entra mai nel contenitore.

Potete impostare GH_TOKEN o GITHUB_TOKEN voi stessi nelle impostazioni di ambiente, o lasciare entrambi non impostati e lasciare che il proxy GitHub si autentichi per voi:

• Se impostate un token, passa attraverso al contenitore invariato, quindi i vostri script e il gh CLI di GitHub lo utilizzano direttamente.
• Se non impostate nessuno e il proxy GitHub sta gestendo l'autenticazione per la vostra sessione, entrambe le variabili leggono come la stringa segnaposto proxy-injected nei comandi che Claude esegue, e il proxy sostituisce le vostre credenziali reali sulle richieste GitHub in uscita. gh funziona senza un token vostro, ma uno script che legge GITHUB_TOKEN direttamente ottiene il segnaposto, non un token utilizzabile.

Un token che impostate è una variabile di ambiente ordinaria, quindi chiunque utilizzi l'ambiente può leggerlo; il percorso del proxy mantiene la credenziale fuori dalla configurazione dell'ambiente e dalla VM della sessione.

Per verificare quale caso si applica alla vostra sessione, chiedete a Claude di eseguire echo $GH_TOKEN.

Il gh CLI di GitHub è preinstallato. Se avete bisogno di un comando gh che gli strumenti integrati non coprono, come gh release o gh workflow run, chiedete a Claude di eseguirlo. gh legge GH_TOKEN automaticamente, quindi non avete bisogno di eseguire gh auth login.

Collegare l'output di nuovo alla sessione

Ogni sessione cloud ha un URL di trascrizione su claude.ai, e la sessione può leggere il suo ID dalla variabile di ambiente CLAUDE_CODE_REMOTE_SESSION_ID. Utilizzate questo per mettere un link tracciabile nei corpi PR, nei messaggi di commit, nei post Slack o nei report generati in modo che un revisore possa aprire l'esecuzione che li ha prodotti.

I commit che Claude crea in una sessione cloud includono un trailer git Claude-Session: <url>, e i corpi PR includono l'URL della sessione su una riga propria. Per omettere il trailer e il link nel corpo PR, impostate attribution.sessionUrl su false.

Per includere il link della sessione in qualcosa di diverso da un commit o PR, come un messaggio Slack che Claude pubblica o un file di report che scrive, chiedete a Claude di eseguire il comando seguente e utilizzate il suo output. Il comando converte il prefisso cse_ nel valore della variabile di ambiente al prefisso session_ che l'URL della trascrizione si aspetta:

echo "https://claude.ai/code/${CLAUDE_CODE_REMOTE_SESSION_ID/#cse_/session_}"

Eseguire test, avviare servizi e aggiungere pacchetti

Non avete una shell nella VM della sessione. Claude esegue ogni comando per voi, quindi formulate i compiti in questa sezione come richieste nel vostro prompt.

Eseguire test

Claude esegue i test come parte del lavoro su un compito. Chiedete nel vostro prompt, come "fix the failing tests in tests/" o "run pytest after each change." I test runner che vengono con i toolchain preinstallati, come pytest e cargo test, funzionano senza configurazione aggiuntiva. Un runner che il vostro progetto dichiara come dipendenza, come jest, si installa con le vostre dipendenze.

Avviare servizi

PostgreSQL e Redis sono preinstallati ma non in esecuzione per impostazione predefinita. Chiedete a Claude di avviare quello di cui avete bisogno; i comandi che esegue sono:

service postgresql start

service redis-server start

Docker è disponibile per l'esecuzione di servizi containerizzati. Chiedete a Claude di eseguire docker compose up per avviare i servizi del vostro progetto. L'accesso di rete per il pull delle immagini segue il livello di accesso del vostro ambiente, e i default Trusted includono Docker Hub e altri registri comuni.

Se le vostre immagini sono grandi o lente da estrarre, aggiungete docker compose pull o docker compose build al vostro script di configurazione. La cache dell'ambiente mantiene le immagini estratte, quindi ogni nuova sessione le ha su disco. La cache memorizza solo file, non processi in esecuzione, quindi Claude avvia comunque i contenitori ogni sessione.

Aggiungere pacchetti

Per aggiungere pacchetti che non sono preinstallati, utilizzate uno script di configurazione. La cache dell'ambiente mantiene quello che lo script installa, quindi i pacchetti che installate lì sono disponibili all'inizio di ogni sessione senza reinstallare ogni volta. Potete anche chiedere a Claude di installare pacchetti a metà sessione, ma quelle installazioni non si trasferiscono ad altre sessioni.

Limiti di risorse

Le sessioni cloud negli ambienti ospitati da Anthropic vengono eseguite con limiti di risorse approssimativi che possono cambiare nel tempo:

• 4 vCPU
• 16 GB di RAM
• 30 GB di disco

La VM può interrompere i compiti che necessitano di significativamente più memoria, come grandi lavori di build o test ad alta intensità di memoria. Per carichi di lavoro oltre questi limiti, utilizzate Remote Control per eseguire Claude Code sul vostro hardware, o eseguite le sessioni cloud in un ambiente self-hosted su compute che la vostra organizzazione gestisce.

Script di configurazione

Uno script di configurazione è uno script Bash che viene eseguito quando inizia una nuova sessione cloud, prima che Claude Code si avvii. Utilizzare gli script di configurazione per installare dipendenze, configurare strumenti o recuperare qualsiasi cosa di cui la sessione ha bisogno e che non è preinstallata.

Gli script vengono eseguiti come root su Ubuntu 24.04, quindi apt install e la maggior parte dei gestori di pacchetti del linguaggio funzionano.

Per aggiungere uno script di configurazione, aprire la finestra di dialogo delle impostazioni dell'ambiente e inserire lo script nel campo Setup script.

Questo esempio installa ShellCheck, che non è preinstallato.

#!/bin/bash
apt update && apt install -y shellcheck

Requisiti dello script

Uno script di configurazione ha tre vincoli da considerare:

• Exit zero: se lo script esce con un codice diverso da zero, la sessione non si avvia. Aggiungere || true ai comandi non critici in modo che un errore di installazione intermittente non blocchi la sessione.
• Completamento entro cinque minuti: mantenere il tempo di esecuzione totale dello script sotto circa cinque minuti in modo che la cache dell'ambiente possa essere costruita. Eseguire le installazioni indipendenti in parallelo con & e wait, e spostare qualsiasi singolo download che non rientra in un hook SessionStart che lo avvia in background.
• Accesso di rete per le installazioni: le installazioni di pacchetti devono raggiungere i registri. Il livello Trusted predefinito copre i domini consentiti comuni inclusi npm, PyPI, RubyGems e crates.io; con accesso di rete None, le installazioni non riescono.

Cache dell'ambiente

Lo script di configurazione viene eseguito la prima volta che si avvia una sessione in un ambiente. Dopo il completamento, Anthropic crea uno snapshot del filesystem e riutilizza quello snapshot come punto di partenza per le sessioni successive. Le nuove sessioni iniziano con le dipendenze, gli strumenti e le immagini Docker già sul disco, e saltano il passaggio dello script di configurazione. Questo mantiene l'avvio veloce anche quando lo script installa grandi toolchain o estrae immagini di container.

La cache è uno snapshot del filesystem, quindi mantiene ciò che lo script di configurazione scrive su disco e perde tutto ciò che era solo in esecuzione. I pacchetti installati, le immagini Docker estratte e i file scritti vengono tutti trasferiti. Un database avviato dallo script, uno stack docker compose up o qualsiasi altro processo in background no; avviare quelli per sessione chiedendo a Claude o con un hook SessionStart.

Lo script di configurazione viene eseguito di nuovo per ricostruire la cache quando si modifica lo script di configurazione dell'ambiente o gli host di rete consentiti, e quando la cache raggiunge la scadenza dopo circa sette giorni. La ripresa di una sessione esistente non riesegue mai lo script di configurazione.

Non è necessario abilitare la cache o gestire gli snapshot da soli.

Script di configurazione vs. hook SessionStart

Utilizzare uno script di configurazione per il provisioning della VM stessa: toolchain e strumenti CLI che non sono preinstallati. Utilizzare un hook SessionStart per la configurazione del progetto che dovrebbe essere eseguita ovunque, cloud e locale, come npm install.

Gli script di configurazione e gli hook SessionStart vengono eseguiti in un ordine fisso quando inizia una sessione cloud. La tabella confronta dove li si configura, quando vengono eseguiti e dove vengono eseguiti.

Se si hanno hook SessionStart nel file ~/.claude/settings.json a livello di utente, non aspettarsi che siano nel cloud. Le impostazioni a livello di utente rimangono sulla macchina. Quali altri hook vengono eseguiti dipende da dove viene eseguita la sessione:

• Ambiente ospitato da Anthropic: Claude Code esegue gli hook dal repository e dalle impostazioni gestite dal server dell'organizzazione.
• Ambiente self-hosted: Claude Code esegue anche gli hook che l'operatore ha seminato da ~/.claude/ dell'host del runner, e gli hook nel file di impostazioni gestite dell'immagine del runner quando quel file è uno dei fonti gestite che Claude Code applica.

Installare dipendenze con un hook SessionStart

Per installare dipendenze solo nelle sessioni cloud, abbinare un hook SessionStart con uno script che controlla dove viene eseguito.

Innanzitutto, aggiungere un hook SessionStart al .claude/settings.json del repository. Questa configurazione dice a Claude Code di eseguire scripts/install_pkgs.sh dal repository ogni volta che una sessione si avvia o riprende:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|resume",
        "hooks": [
          {
            "type": "command",
            "command": "bash \"$CLAUDE_PROJECT_DIR\"/scripts/install_pkgs.sh"
          }
        ]
      }
    ]
  }
}

Il matcher limita l'hook agli eventi startup e resume, e $CLAUDE_PROJECT_DIR si risolve nella radice del repository, quindi l'hook trova lo script indipendentemente dalla directory di lavoro della sessione.

Successivamente, creare lo script in scripts/install_pkgs.sh. Esce immediatamente al di fuori del cloud, quindi installa le dipendenze:

#!/bin/bash

if [ "$CLAUDE_CODE_REMOTE" != "true" ]; then
  exit 0
fi

npm install
pip install -r requirements.txt
exit 0

Il controllo CLAUDE_CODE_REMOTE è ciò che limita l'installazione alle sessioni cloud: la VM della sessione trasporta quella variabile come true, non è mai true localmente, quindi sul laptop lo script esce prima di installare qualsiasi cosa.

Insieme, i due file danno a ogni sessione cloud un npm install e pip install freschi all'avvio mentre lasciano le sessioni locali intatte.

Limitazioni nelle sessioni cloud

Gli hook SessionStart si comportano allo stesso modo nel cloud che localmente, con questi avvertimenti:

• Una repository per sessione: una sessione con più repository non carica gli hook da nessuno dei .claude/settings.json della repository, quindi un hook SessionStart che si definisce lì non viene eseguito. Installare le dipendenze per quelle sessioni con uno script di configurazione invece.
• Nessun ambito solo cloud: gli hook vengono eseguiti sia nelle sessioni locali che in quelle cloud. Per saltare l'esecuzione locale, uscire anticipatamente a meno che la variabile di ambiente CLAUDE_CODE_REMOTE non sia true, come fa lo script di installazione delle dipendenze.
• Richiede accesso di rete: i comandi di installazione devono raggiungere i registri dei pacchetti. Se l'ambiente utilizza accesso di rete None, questi hook non riescono. L'elenco consentiti predefinito sotto Trusted copre npm, PyPI, RubyGems e crates.io.
• Compatibilità proxy: negli ambienti ospitati da Anthropic, tutto il traffico in uscita passa attraverso un proxy di sicurezza, e alcuni gestori di pacchetti non funzionano correttamente con esso; Bun è un esempio noto. In un ambiente self-hosted, il traffico in uscita passa attraverso il proprio confine di rete.
• Aggiunge latenza di avvio: gli hook vengono eseguiti ogni volta che una sessione si avvia o riprende, a differenza degli script di configurazione che beneficiano della cache dell'ambiente. Mantenere gli script di installazione veloci controllando se le dipendenze sono già presenti prima di reinstallarle.

Per personalizzare l'immagine di base, utilizzare uno script di configurazione per installare ciò di cui si ha bisogno sopra l'immagine fornita, o eseguire la propria immagine come container insieme a Claude con docker compose. La sostituzione completa dell'immagine di base non è ancora supportata.

Domini consentiti predefiniti

Con accesso di rete Trusted, le sessioni possono raggiungere i seguenti domini per impostazione predefinita. I domini contrassegnati con * indicano la corrispondenza del sottodominio con carattere jolly, quindi *.gcr.io consente qualsiasi sottodominio di gcr.io.

Risorse correlate

• Cloud sessions reference: avviare, gestire e condividere sessioni cloud
• Cloud sessions quickstart: connettere GitHub e avviare la vostra prima sessione cloud
• Claude Tag: le sessioni che Claude avvia da Slack vengono eseguite negli stessi ambienti
• Routine: le esecuzioni programmate utilizzano gli stessi ambienti e livelli di accesso di rete
• Remote Control: eseguire sessioni sulla rete e sui file della vostra macchina invece
• Ambienti self-hosted: eseguire sessioni cloud sull'infrastruttura propria della vostra organizzazione
• SessionStart hooks: configurazione sottoposta a commit nel repository che viene eseguita nelle sessioni locali e cloud
• Impostazioni gestite dal server: politica dell'organizzazione che raggiunge le sessioni cloud