Skip to main content
Gli ambienti self-hosted sono in beta pubblica sui piani Team ed Enterprise; Disponibilità e limitazioni copre il percorso di abilitazione. Questa pagina avvia la tua prima sessione; vedi Ambienti self-hosted per sapere cosa sono e Distribuisci in produzione per l’hardening e le ricette di fleet.
Un ambiente self-hosted esegue sessioni cloud di Claude Code su infrastrutture che la tua organizzazione gestisce, eseguite da processi runner che distribuisci. Questa guida rapida configura il tuo primo, il più piccolo che funziona: un runner su un singolo host, che esegue una sessione di test. Ci sono due passaggi: crea l’ambiente, avvia un runner e indirizza una sessione ad esso, quindi invia un messaggio a quella sessione dal tuo terminale. Ti sposterai tra due superfici: claude.ai per creare l’ambiente, controllarne lo stato e indirizzare una sessione, e un terminale sull’host per tutto ciò che il runner fa. Alla fine avrai un ambiente nella pagina di amministrazione Cloud environments, un runner che esegue il polling per il lavoro, e una sessione in esecuzione sul tuo host. Prima di connettere repository reali o sistemi interni, lavora attraverso Distribuisci in produzione, che copre il profilo di sicurezza, il controllo dell’egress, le credenziali git e l’orchestrazione.

​
Prerequisiti

​
Organizzazione e ruoli

Il lato claude.ai ha bisogno di:
  • Allow self-hosted environments attivato da un Owner nella pagina di amministrazione Cloud environments; il pulsante New non appare finché non è attivato. Se non hai il ruolo, qualcuno che lo ha può creare l’ambiente e passarti il suo secret; i passaggi del runner e del terminale su questa pagina non richiedono alcun ruolo claude.ai, e dove un passaggio controlla lo stato nell’interfaccia di amministrazione, le proprie righe di log del runner ti danno lo stesso segnale.
  • Il connettore GitHub attivato da un Owner, e la connessione GitHub personale di ogni sviluppatore, in modo che possano selezionare repository github.com quando avviano sessioni.

​
Host e rete

L’host del runner ha bisogno di:
  • Un host o container Linux o macOS con HTTPS in uscita verso api.anthropic.com, verso claude.ai e gli host di download a cui reindirizza per il passaggio di installazione sottostante, e verso il tuo host git per il clone; la tabella dei requisiti di rete ha l’elenco completo. Windows non è supportato come host runner; esegui il runner in un container Linux invece. Le workstation degli sviluppatori non sono interessate, poiché le sessioni iniziano da claude.ai in un browser.
  • Un repository per la sessione di test: uno pubblico, oppure uno che questo host può già clonare tramite il suo URL HTTPS senza che vengano richieste credenziali. Una chiave SSH da sola non basta, perché il runner clona l’URL https:// del repository. Per clonare invece tramite SSH, vedi Riscrivere gli URL git per reti private.
  • Un orologio sincronizzato all’ora reale, ad esempio con NTP. L’autenticazione fallisce quando l’orologio è più di cinque minuti indietro; vedi Troubleshooting.

​
Software sull’host del runner

Installa sull’host prima di iniziare:
  • Claude Code v2.1.224 o successivo, con uno qualsiasi dei metodi di installazione standard. Il runner fa parte del binario claude standard, e le versioni precedenti non riconoscono il subcommand self-hosted-runner. Un runner che serve sessioni Claude Tag richiede la v2.1.229 o successiva e python3 nel suo PATH, poiché gli hook forniti dal control plane per quelle sessioni eseguono python3. Per fissare la versione esatta che la tua fleet esegue, vedi Installa una versione specifica. Per le immagini container, vedi il Dockerfile in Distribuisci in produzione.
  • Git 2.24 o più recente. Alcune opzioni git nella pagina di distribuzione richiedono versioni più recenti; Configura git indica ogni limite.
Conferma che l’host è pronto:
Un host pronto stampa il testo di utilizzo del runner, elencando flag come --environment-secret-file. Sulle versioni precedenti a 2.1.224, il comando stampa invece l’output generale di claude --help. Se vedi quell’output, aggiorna Claude Code. Se esegui claude da un’immagine container, ricostruisci l’immagine con la versione 2.1.224 o successiva.

​
Configura un ambiente e un runner

Usa la configurazione guidata oppure i passaggi manuali. La configurazione guidata è un singolo comando che avvia una sessione Claude Code interattiva e ti guida attraverso il resto. Usa invece i passaggi manuali su un host dove una sessione interattiva non è possibile. Usali anche quando qualcuno che detiene il ruolo Owner ha creato l’ambiente e ti ha consegnato il suo secret, poiché la configurazione guidata richiede un accesso come Owner.

​
Esegui la configurazione guidata

La configurazione guidata ti guida attraverso la creazione dell’ambiente nell’interfaccia di amministrazione, avvia un runner locale con il file secret che salvi, conferma che il runner si registra e scrive un foglio di aiuto in ./runner-setup/CHEAT-SHEET.md. Prima di eseguirla, verifica l’accesso e la versione:
  • Accesso: eseguila su una macchina dove hai effettuato l’accesso con claude auth login usando un account che detiene un ruolo Owner. Con solo una chiave API o un provider di modelli di terze parti, la sessione si avvia ma i suoi controlli sull’organizzazione falliscono.
  • Versione: conferma che il controllo della versione è passato. Sulle versioni precedenti a 2.1.224, il comando setup avvia una sessione Claude con le parole come prompt invece della configurazione guidata.
Per avviare la configurazione guidata, esegui il subcommand setup nella tua shell e segui le istruzioni:
La configurazione non avvia da sola una sessione di test: ti dice di avviarne una su claude.ai/code. L’ultimo passaggio della configurazione arresta il runner che ha avviato. Se esci dalla configurazione prima di quel passaggio, il runner continua a essere in esecuzione. Per proseguire dopo l’ultimo passaggio, avvia di nuovo il runner nella tua shell con il comando presente in ./runner-setup/CHEAT-SHEET.md, quindi indirizza una sessione all’ambiente.

​
Configura manualmente

Crea l’ambiente su claude.ai, avvia il runner da un terminale sull’host, quindi torna su claude.ai per confermare che il runner appare e indirizzare una sessione verso di esso. Se qualcuno che detiene il ruolo Owner ha già creato l’ambiente e ti ha consegnato il suo secret, inizia dal passaggio 2.
1

Crea un ambiente

Vai alla pagina Cloud environments nelle impostazioni di amministrazione. Sotto Self-hosted environments, seleziona New, nomina l’ambiente, e seleziona Create. Nel secondo passaggio della procedura guidata, seleziona Copy environment key per copiare il secret dell’ambiente, che l’interfaccia di amministrazione etichetta come environment key. claude.ai mostra il secret una volta, e non puoi recuperarlo in seguito; scade 365 giorni dopo la creazione. L’ID ccpool_... dell’ambiente rimane visibile nella sua finestra di dialogo dei dettagli; ne avrai bisogno per il controllo aud nella verifica del token e per l’invio di sessioni di test da CI.Se perdi il secret o hai bisogno di ruotarlo, crea un nuovo secret dalla scheda Configuration dell’ambiente, distribuisci il nuovo secret ai tuoi runner, quindi revoca quello vecchio. I runner che detengono un secret revocato falliscono il loro prossimo poll autenticato ed escono, registrando poll auth failed, e il tuo orchestrator li riavvia con il nuovo secret.
2

Avvia un runner

Crea la directory del secret. Questo comando e il successivo usano /etc/claude, che richiede root, e il file secret che creano è leggibile solo dall’utente che li esegue. Se il runner verrà eseguito come un altro utente, esce con error: Failed to read environment secret file <path> (EACCES: permission denied, open '<path>'). In tal caso, esegui entrambi i comandi come utente del runner con una directory in cui quell’utente può scrivere al posto di /etc/claude, e passa lo stesso percorso a --environment-secret-file. Qualsiasi percorso che il processo runner può leggere funziona.
Scrivi il secret dell’ambiente in un file. Il comando sottostante legge dal tuo terminale in modo che il secret rimanga fuori dalla cronologia della shell: incolla il valore che hai copiato, premi Invio, quindi Ctrl-D, e l’umask della subshell rende il file leggibile solo dal suo proprietario.
Scegli una directory di base, sostituendo <writable-dir> nel comando del runner sottostante con un percorso assoluto che il runner può scrivere o creare. Il runner crea la directory all’avvio, quindi controlla i repository e crea directory per sessione sotto di essa. Senza --base-dir usa /workspace, che funziona solo se quella directory esiste già ed è scrivibile o avvii il runner come root.
Usa una directory dedicata al runner, non la tua directory home o una directory contenente i tuoi cloni. Il runner considera qualsiasi cosa trovi in <writable-dir>/<repo-owner>/<repo> come un proprio clone, e può reimpostarlo e sovrascrivere o eliminare i file al suo interno.
Se il runner non può creare o scrivere nella directory di base, esce all’avvio con un errore che nomina la directory invece di registrarsi. Vedi Risoluzione dei problemi.Quindi avvia il runner con --environment-secret-file e --base-dir:
Il runner registra Registered: runner_id=<runner-id> una volta che si è registrato con il tuo ambiente, quindi inizia il polling per il lavoro. Avviato con questo comando, esce per progettazione dopo aver servito una sessione, non dopo ogni turno. Per servire altre sessioni, avvia di nuovo il runner ogni volta che esce. Vedi Se il runner esce per sapere quando succede e cosa registra il runner.
3

Verifica che il runner appaia

Ritorna alla pagina Cloud environments. Lo stato del tuo ambiente cambia da No runners deployed a Healthy entro pochi secondi dall’avvio del runner; apri l’ambiente e seleziona Activity per vedere il runner stesso. Se non hai accesso alla pagina di amministrazione, la riga Registered: runner_id=<runner-id> nel log del runner del passaggio precedente ti fornisce lo stesso segnale.
4

Indirizza una sessione all'ambiente

Avvia una sessione su claude.ai/code e seleziona il tuo ambiente dal selettore di ambiente, dove gli ambienti self-hosted appaiono insieme a quelli ospitati da Anthropic. Come repository, scegli quello indicato nei prerequisiti: un repository pubblico, o uno che questo host può già clonare tramite il suo URL HTTPS senza che vengano richieste credenziali.Il prossimo runner disponibile raccoglie la sessione in coda e registra Picked up session <session-id> insieme al suo conteggio attivo e alla capacità, in modo che tu possa confermare dall’output del runner stesso quale host ha preso la sessione. Guarda la sessione lavorare e leggi le risposte di Claude su claude.ai/code.Se la sessione non inizia a lavorare, individua il caso che corrisponde a ciò che vedi:
  • La sessione rimane in coda: vedi Risoluzione dei problemi.
  • La sessione non si avvia a causa di un errore git: se l’errore include il messaggio di git could not read Username for seguito dall’URL del tuo host git, il runner non aveva credenziali HTTPS per quell’host.
    • Fornisci credenziali HTTPS: vedi Configura git
    • Clona invece tramite SSH: se l’host del runner ha già una chiave SSH, vedi Riscrivi gli URL git per le reti private
    • Dopo una delle due correzioni: avvia di nuovo il runner e osserva la sessione non riuscita invece di avviarne una nuova. Se non è riuscita più volte, attendi diversi minuti che il runner registri Picked up session.
    • Per usare invece un repository diverso: archivia o elimina la sessione non riuscita, quindi avvia di nuovo il runner e avvia una nuova sessione. Altrimenti, il runner può raccogliere la sessione non riuscita invece di quella nuova.

​
Se il runner esce

Se il runner esce durante questa guida rapida, avvialo di nuovo. Il runner può uscire da solo:
  • Nulla rimasto in esecuzione: il log mostra [runner:exit] account workload drained — exiting. Il runner esce per progettazione quando non sta più eseguendo alcuna sessione, ad esempio:
    • Hai archiviato o eliminato la sessione: avvia di nuovo il runner
    • La sessione non è riuscita ad avviarsi: correggi la causa, quindi avvia di nuovo il runner
  • Contatto perso: il log mostra una riga [runner:fatal] con runner record gone server-side o con poll auth failed. Se il runner perde il contatto con Anthropic per un po’ di tempo, ad esempio perché l’host va in sospensione, può uscire la prossima volta che raggiunge Anthropic.
Un turno terminato non chiude la tua sessione di test. Dopo il primo turno la sessione è ancora collegata e il runner è ancora attivo, quindi puoi inviare alla sessione un messaggio di follow-up senza prima riavviare il runner. Per la produzione, distribuisci il runner sotto un orchestrator che lo riavvia all’uscita e attende più a lungo tra i riavvii quando il runner continua a uscire subito dopo l’avvio. Vedi Distribuisci in produzione e Quando il runner esce.

​
Inviare un messaggio di follow-up a una sessione in esecuzione

Una volta che una sessione è in esecuzione nel vostro ambiente, inviatele un follow-up dalla CLI claude su qualsiasi macchina dove siete collegati con claude auth login; il comando non ha bisogno di essere eseguito dalla macchina che ha avviato la sessione. Il comando invia un messaggio:
Per <session-id>, passa l’ID semplice session_... o cse_... oppure l’URL claude.ai/code della sessione. Un invio riuscito stampa Sent to cloud session. con l’ID della sessione e un link di visualizzazione. I formati di ID accettati, l’output JSON e i requisiti dell’account e della policy si trovano in Inviare follow-up dalla CLI, poiché il comando funziona allo stesso modo con le sessioni ospitate da Anthropic.

​
Cosa c’è dopo

  • Distribuisci in produzione: indurire la distribuzione, controllare l’egress, configurare le credenziali git, ed eseguire la fleet sotto Kubernetes o Compose
  • Personalizza sessioni: script wrapper, hook del ciclo di vita, runner on-demand, server MCP, e permessi
  • Testa end to end: un test di fumo CI che invia una sessione e legge le risposte di Claude