Configurare ambienti cloud

• L’app Desktop
• L’app mobile Claude
• Il tuo browser su claude.ai/code
• Il terminale con claude --cloud
• Le attività pianificate cloud
• Claude Tag

​

L’ambiente Default

• 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 setup; mantieni i valori predefiniti del modulo e fai clic su Create & finish per ottenere lo stesso ambiente Default

• 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.

• 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.

​

Configurare il vostro ambiente

​

Impostare le variabili di ambiente

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

• La VM viene ripristinata dopo essere stata inattiva: dopo alcuni minuti senza attività, la VM di una sessione si mette in pausa con i suoi file salvati. Il vostro messaggio successivo ripristina la stessa VM e avvia di nuovo Claude Code.
• La VM è stata recuperata e viene ricostruita: se la VM in pausa è stata successivamente recuperata, riaprire la sessione provisiona una VM nuova.

​

Aggiungere segreti di rete

​

Requisiti

• Ruolo: sui piani Pro, Max e Team, puoi aggiungere ed eliminare segreti nei tuoi ambienti qualunque sia il tuo ruolo. Su Team ed Enterprise, gli Owner detengono un ruolo di amministratore dell’organizzazione nella tua organizzazione claude.ai e gli Admin no, il che cambia ciò che vedi in questi casi:
  • Il tuo ambiente su Enterprise: con un ruolo di amministratore dell’organizzazione, aggiungi ed elimini i segreti. Senza di esso, la riga Network secrets apre l’elenco dei segreti con la nota “Only an organization admin can add or delete network secrets”, senza il pulsante Add secret né quello di eliminazione. Chiedi a un Owner di aggiungere il segreto a un ambiente condiviso, quindi esegui lì le tue sessioni
  • Un ambiente condiviso: gli Owner aggiungono ed eliminano i suoi segreti dalle impostazioni di amministrazione. Senza un ruolo di amministratore dell’organizzazione, chiedi a un Owner di aggiungere il segreto, perché la finestra di dialogo dell’ambiente non ha una sezione Network secrets
  • Il tuo ambiente su Team: senza un ruolo di amministratore dell’organizzazione, Add secret apre un modulo più breve che accetta un solo host
• Tipo di ambiente: un ambiente cloud ospitato da Anthropic che esiste già. Un ambiente self-hosted non ha segreti di rete
• Raggiungibilità API: l’API accetta connessioni da internet, perché le richieste escono dalla rete di Anthropic
• Chiavi di crittografia: se la tua organizzazione utilizza chiavi di crittografia gestite dal cliente, non puoi salvare segreti di rete

​

Aggiungere un segreto

​

Aggiungere un segreto su un piano Team senza un ruolo di amministratore dell’organizzazione

• Host: l’unico host che riceve il segreto, come api.example.com. Il modulo non accetta un carattere jolly *.
• Name: un’etichetta facoltativa per il segreto
• Secret type: Token per una chiave che viaggia in un’intestazione della richiesta, oppure Username and password. Per un token, incolla la chiave come Value

​

Quali richieste ricevono il segreto

​

Richieste che non ricevono mai il segreto

• GitHub: è invece il proxy GitHub ad autenticare le richieste a GitHub, quindi non hai bisogno di un segreto di rete 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
• Esportazione della telemetria di Claude Code: Claude Code invia l’esportazione della telemetria propria piuttosto che attraverso un comando che esegue, e quella richiesta non passa attraverso il proxy dell’agente

​

Selezionare un ambiente dalla CLI

​

Archiviare un ambiente

• 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.
• I segreti di rete dell’ambiente rimangono allegati nelle sue sessioni in esecuzione. Elimina quelli che non vuoi più prima di archiviare.
• Nessuna nuova sessione può iniziare in un ambiente archiviato, su nessuna superficie:
  • Default CLI salvato: se l’ambiente era il tuo default CLI salvato, Claude Code avvia le sessioni cloud CLI nell’ambiente ospitato da Anthropic quando il tuo elenco ne ha uno. Altrimenti, le avvia nel primo ambiente del tuo elenco che non è un ambiente bridge Remote Control.
  • Configurato esplicitamente: qualsiasi cosa configurata esplicitamente con l’ambiente, come un’attività pianificata cloud, non può avviare nuove sessioni in esso. Puntala a un altro ambiente.

​

Ambienti condivisi dell’organizzazione

• 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: apri uno dei tuoi ambienti per la modifica nel selettore di ambiente, quindi condividilo dalla riga Who can use it. L’ambiente mantiene il suo ID, quindi le sessioni e le attività pianificate che lo utilizzano già non sono interessate, e ogni membro può quindi vederlo e avviare sessioni in esso.

​

Impostare l’ambiente che un canale Claude Tag utilizza

• 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

​

Livelli di accesso

• GitHub, attraverso il suo proxy separato
• I connettori MCP che abilitate, il cui traffico viaggia attraverso i server di Anthropic
• Gli host che hai elencato nei segreti di rete dell’ambiente, tranne gli host che non ricevono mai il segreto
• L’API Anthropic, per le richieste di Claude Code stesso, anche a None, come notato sotto Sicurezza e isolamento

​

Consentire domini specifici

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

• 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.

​

Proxy GitHub

• 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.
• Restrizioni sui push: il proxy rifiuta le eliminazioni di branch e i push di qualsiasi cosa diversa da un branch, come un tag. Non limita quali branch un push può aggiornare. Per farlo, usa le regole di protezione dei branch o i ruleset su GitHub.
• Ambito del repository: il proxy gestisce le richieste API GitHub per i repository collegati alla sessione. Una richiesta API per un altro repository riceve un 403 il cui messaggio inizia con GitHub access to e contiene is not enabled for this session. Un archivio sorgente che recuperi tramite un URL github.com/{owner}/{repo}/archive/ o codeload.github.com riceve lo stesso 403 quando il repository non è collegato, anche se è pubblico.
• Restrizioni GraphQL: il proxy rifiuta le richieste all’endpoint GraphQL di GitHub con un 403 il cui messaggio inizia con GitHub GraphQL is not available from Claude Code sessions e indica il fallback REST, gh api repos/{owner}/{repo}/.... I sottocomandi di gh che usano GraphQL, come gh pr e gh issue, ricevono lo stesso 403. La restrizione si applica a ogni richiesta attraverso il proxy indipendentemente dalle credenziali che fornisci, quindi anche un GH_TOKEN che imposti riceve lo stesso 403. Claude non può raggiungere attraverso il proxy le API GitHub che esistono solo in GraphQL, come Projects v2.

​

Proxy di sicurezza

• Protezione contro richieste dannose
• Limitazione della velocità e prevenzione degli abusi

​

Cosa è disponibile nelle sessioni cloud

​

Cosa viene trasferito dalla tua configurazione

​

Aggiungere preferenze personali senza fare il commit nel repository

#!/bin/bash
mkdir -p ~/.claude
cat > ~/.claude/CLAUDE.md <<'EOF'
Use conventional commit messages.
EOF

​

Strumenti installati

​

Lavorare con issue e pull request di GitHub

• Se imposti un token, viene passato al container senza modifiche, quindi i tuoi script e la CLI gh di GitHub lo usano direttamente.
• Se non ne imposti nessuno e il proxy GitHub gestisce l’autenticazione per la tua sessione, entrambe le variabili contengono la stringa segnaposto proxy-injected nei comandi che Claude esegue, e il proxy sostituisce le tue credenziali reali nelle richieste GitHub in uscita. Le chiamate gh api per i repository collegati funzionano senza un tuo token, ma uno script che legge direttamente GITHUB_TOKEN ottiene il segnaposto, non un token utilizzabile.

​

Collegare l’output alla sessione

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

​

Eseguire test, avviare servizi e aggiungere pacchetti

​

Eseguire test

​

Avviare servizi

service postgresql start

service redis-server start

​

Aggiungere pacchetti

​

Limiti di risorse

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

​

Limiti di tempo

• Comandi che Claude esegue: un ambiente cloud non imposta un proprio timeout per i comandi, quindi si applicano i default dello strumento Bash. Per impostazione predefinita Claude attende 2 minuti per un comando in primo piano e può richiedere fino a 10 minuti. Quando un comando raggiunge il suo timeout, Claude Code lo sposta in background invece di interromperlo, a meno che il comando non inizi con sleep. Un comando spostato in questo modo può continuare a essere eseguito per altri 30 minuti al massimo prima che Claude Code lo interrompa al raggiungimento del limite di tempo per i comandi in background. Impostare BASH_DEFAULT_TIMEOUT_MS oltre 1800000 millisecondi allunga sia quel limite sia il default per i comandi in primo piano.
• Hook SessionStart: Claude Code annulla un hook command dopo 600 secondi, a meno che tu non imposti timeout, in secondi, nella voce dell’hook. Claude Code non applica il timeout a un hook che esegui con async: true.
• Script di configurazione: uno script che impiega più di circa cinque minuti non viene memorizzato nella cache. Requisiti dello script spiega come restare sotto questo limite.
• Sessioni inattive: dopo alcuni minuti senza attività, la VM di una sessione va in pausa con i suoi file salvati, e una VM in pausa può essere successivamente recuperata dal sistema. Impostare variabili d’ambiente descrive cosa una sessione recepisce in ciascun caso, e Environment expired spiega come riaprire una sessione la cui VM è stata recuperata.

​

Script di configurazione

​

Aggiungere uno script di configurazione

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

​

Requisiti dello script

• 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. Quando la configurazione richiede più tempo di quello, l’ambiente non viene memorizzato nella cache. 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. Se le nuove sessioni si bloccano o si interrompono durante la configurazione, vedere Le nuove sessioni si bloccano o scadono durante la configurazione.
• 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.
• Le variabili dell’ambiente non sono ancora impostate: lo script viene eseguito prima che la sessione imposti le variabili d’ambiente dell’ambiente. Imposta nello script stesso qualsiasi valore di cui lo script ha bisogno.

​

Cache dell’ambiente

​

Script di configurazione vs. hook SessionStart

• Ambiente ospitato da Anthropic: Claude Code esegue gli hook dalle impostazioni gestite dal server della tua organizzazione e, al di fuori di un thread di un progetto, dal repository. Le sessioni Claude Tag non ricevono impostazioni gestite dal server, quindi gli hook dalle impostazioni gestite dal server non vengono eseguiti lì.
• 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

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

#!/bin/bash

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

cd "$CLAUDE_PROJECT_DIR" || exit 1
hashes=node_modules/.install_pkgs.sha256

if ! sha256sum --check --status "$hashes" 2>/dev/null; then
  # Delete the old hashes first, so a failed install runs again next time
  rm -f "$hashes"
  if npm install; then
    sha256sum scripts/install_pkgs.sh package.json package-lock.json > "$hashes" || rm -f "$hashes"
  fi
fi

# pip skips requirements that are already satisfied
pip install -r requirements.txt
exit 0

​

Limitazioni nelle sessioni cloud

• Un repository per sessione: in un ambiente ospitato da Anthropic, una sessione con più repository non carica gli hook dal .claude/settings.json di nessun repository, quindi un hook SessionStart che definisci lì non viene eseguito. Installa invece le dipendenze per quelle sessioni con uno script di configurazione. Per un ambiente self-hosted, consulta quali impostazioni del repository si applicano.
• Non nei thread cloud di un progetto: un thread cloud in un progetto non esegue gli hook dal .claude/settings.json di un repository, qualunque sia il numero di repository. In un ambiente ospitato da Anthropic, installa le dipendenze per i thread con uno script di configurazione. In un ambiente self-hosted, usa invece un hook nelle impostazioni dell’host del runner.
• 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 all’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. Mantieni veloci gli script di installazione saltando il lavoro già fatto, come fa lo script di installazione delle dipendenze.

​

Domini consentiti predefiniti

​

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
• Attività pianificate cloud: le esecuzioni pianificate 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