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.
  • Una connessione GitHub per la tua organizzazione, in modo che gli sviluppatori possano selezionare repository 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 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. Il canale latest dell’installer nativo porta ogni release non appena viene pubblicata; il canale stable, il cask Homebrew claude-code, e i repository apt, dnf e apk stabili rimangono indietro di circa una settimana. 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 l’output claude --help generale invece; aggiorna con claude update o reinstalla dal canale latest.

​
Configura un ambiente e un runner

Claude Code include una configurazione guidata: una sessione Claude Code interattiva che 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. Eseguilo su una macchina dove hai effettuato l’accesso con claude auth login usando un account che detiene un ruolo Owner; non è disponibile con chiavi API o provider di modelli di terze parti. Su host dove una sessione interattiva non è possibile, usa i passaggi manuali sottostanti invece. Conferma che il controllo della versione è passato per primo: sulle versioni precedenti a 2.1.224, questo comando avvia una sessione Claude ordinaria con le parole come prompt invece della configurazione guidata. Per avviare la configurazione guidata, esegui il subcommand setup e segui i prompt:
Per configurare manualmente invece:
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 passaggio e il successivo richiedono root per il percorso /etc/claude; qualsiasi percorso che il processo runner può leggere funziona, quindi regola entrambi i comandi e il valore --environment-secret-file insieme se ne usi uno diverso.
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.Se il runner non può creare o scrivere nel percorso, esce all’avvio con un errore che nomina la directory invece di registrarsi. Vedi Troubleshooting.Quindi avvia il runner con --environment-secret-file e --base-dir. Il runner si registra con il tuo ambiente e inizia il polling per il lavoro. Se il runner esce, riavvialo manualmente. Le distribuzioni di produzione eseguono il runner sotto un orchestrator che riavvia i runner usciti, normalmente con un filesystem fresco per ogni riavvio; Riutilizza un checkout pre-riscaldato copre la configurazione del disco persistente supportata.
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.
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. Il runner clona con qualsiasi credenziale git che l’host ha già, quindi scegli un repository che questo host può già clonare, o uno pubblico; le opzioni di credenziale per i repository privati in produzione sono su Configura git. 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 rimane in coda invece, vedi Troubleshooting.
Il runner esce per progettazione una volta che le sue sessioni attive finiscono; vedi Runner lifecycle. Per la produzione, distribuiscilo sotto un orchestrator che lo riavvia all’uscita. Vedi Distribuisci in produzione.

​
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>, passate l’ID bare 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 moduli di ID accettati, l’output JSON, i requisiti dell’account e della policy, e il riferimento agli errori si trovano su Send follow-ups from the CLI, poiché il comando funziona allo stesso modo contro 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