Guida rapida agli ambienti self-hosted

Configura il tuo primo ambiente self-hosted: installa Claude Code, crea l'ambiente, avvia un runner e indirizza una sessione ad esso.

[!NOTE]

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.

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:

claude self-hosted-runner --help

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 interattiva di Claude Code e ti guida attraverso il resto. Usa invece i passaggi manuali su un host in cui non è possibile una sessione interattiva. Usali anche quando qualcuno con 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 accompagna nella creazione dell'ambiente nell'interfaccia di amministrazione, avvia un runner locale con il file del secret che salvi, conferma che il runner si registri e scrive un promemoria in ./runner-setup/CHEAT-SHEET.md. Prima di eseguirla, verifica l'accesso e la versione:

• Accesso: eseguila su una macchina in cui hai effettuato l'accesso con claude auth login usando un account con il ruolo Owner. Con solo una chiave API o un provider di modelli di terze parti, la sessione si avvia ma i controlli sull'organizzazione falliscono.
• Versione: verifica che il controllo della versione sia stato superato. Sulle versioni precedenti alla 2.1.224, il comando di configurazione avvia una sessione di Claude usando le parole come prompt invece della configurazione guidata.

Per avviare la configurazione guidata, esegui il sottocomando setup nella tua shell e segui le istruzioni:

claude self-hosted-runner setup

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 funzionare. 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 instrada una sessione verso l'ambiente.

Configura manualmente

Crea l'ambiente su claude.ai, avvia il runner da un terminale sull'host, quindi torna su claude.ai per verificare che il runner compaia e instradarvi una sessione. Se qualcuno con 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. In Self-hosted environments, seleziona New, assegna un nome all'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 chiama environment key. claude.ai mostra il secret una sola volta e non puoi recuperarlo in seguito; scade 365 giorni dopo la creazione. L'ID ccpool_... dell'ambiente resta visibile nella sua finestra di dettaglio; ti servirà per il controllo aud nella verifica dei token e per inviare sessioni di test dalla CI.

Se perdi il secret o devi ruotarlo, crea un nuovo secret dalla scheda Configuration dell'ambiente, distribuisci il nuovo secret ai tuoi runner, quindi revoca quello vecchio. I runner che usano un secret revocato falliscono il successivo polling autenticato ed escono, registrando poll auth failed, e il tuo orchestratore 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 i privilegi di root, e il file del 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, usando al posto di /etc/claude una directory in cui quell'utente possa scrivere, e passa lo stesso percorso a --environment-secret-file. Va bene qualsiasi percorso che il processo del runner possa leggere.

mkdir -p /etc/claude

Scrivi il secret dell'ambiente in un file. Il comando seguente legge dal tuo terminale, così il secret resta fuori dalla cronologia della shell: incolla il valore che hai copiato, premi Enter, poi Ctrl-D, e l'umask della subshell rende il file leggibile solo dal suo proprietario.

(umask 077 && cat > /etc/claude/environment-secret)

Scegli una directory di base, sostituendo <writable-dir> nel comando del runner qui sotto con un percorso assoluto in cui il runner possa scrivere o che possa creare. Il runner crea la directory all'avvio, quindi vi esegue il checkout dei repository e crea al suo interno le directory per ogni sessione. Senza --base-dir usa /workspace, che funziona solo se quella directory esiste già ed è scrivibile oppure se avvii il runner come root.

[!WARNING]

Usa una directory dedicata al runner, non la tua directory home né una directory con i tuoi cloni. Il runner considera come proprio clone qualunque cosa trovi in <writable-dir>/<repo-owner>/<repo> e può reimpostarla e sovrascrivere o eliminare file al suo interno.

Se il runner non riesce a creare la directory di base o a scriverci, esce all'avvio con un errore che indica la directory invece di registrarsi. Consulta Risoluzione dei problemi.

Quindi avvia il runner con --environment-secret-file e --base-dir:

claude self-hosted-runner --environment-secret-file '/etc/claude/environment-secret' --base-dir '<writable-dir>'

Il runner registra Registered: runner_id=<runner-id> una volta che si è registrato presso il tuo ambiente, quindi inizia a fare polling in attesa di 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. Consulta Se il runner esce per sapere quando succede e cosa registra il runner.

3. Verifica che il runner compaia

Torna alla pagina Cloud environments. Lo stato del tuo ambiente passa 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 la stessa indicazione.

4. Instrada una sessione verso l'ambiente

Avvia una sessione su claude.ai/code e seleziona il tuo ambiente dal selettore degli ambienti, dove gli ambienti self-hosted compaiono accanto a quelli ospitati da Anthropic. Come repository, scegli quello indicato nei prerequisiti: un repository pubblico, oppure uno che questo host può già clonare tramite il suo URL HTTPS senza che vengano richieste credenziali.

Il successivo runner disponibile prende in carico la sessione in coda e registra Picked up session <session-id> insieme al numero di sessioni attive e alla capacità, così puoi verificare dall'output del runner stesso quale host ha preso la sessione. Osserva la sessione al lavoro e leggi le risposte di Claude su claude.ai/code.

Se la sessione non inizia a lavorare, individua il caso corrispondente a ciò che vedi:

• La sessione resta in coda: consulta Risoluzione dei problemi.
• La sessione non si avvia e mostra un errore di 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: consulta Configura git
  • Clona invece tramite SSH: se l'host del runner ha già una chiave SSH, consulta Riscrivi gli URL di 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 è fallita diverse volte, attendi alcuni minuti finché il runner non registra 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 potrebbe prendere in carico 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 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 oppure con poll auth failed. Se il runner perde il contatto con Anthropic per un po', ad esempio perché l'host va in sospensione, può uscire la volta successiva in cui raggiunge Anthropic.

Un turno completato non termina 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 dover prima riavviare il runner.

In produzione, distribuisci il runner sotto un orchestratore che lo riavvii quando esce e che attenda più a lungo tra un riavvio e l'altro quando il runner continua a uscire subito dopo l'avvio. Consulta 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:

claude -p "your message" --cloud <session-id>

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