SpyBara
Go Premium

self-hosted-environments-quickstart.md 2026-10-09 23:02 UTC to 2026-10-10 06:59 UTC

This page contains 45 additions and 7 deletions.

2026
Sun 4 23:58 Sat 10 08:02

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.

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

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 l'output claude --help generale invece; aggiorna con claude update o reinstalla dal canale latest.

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:

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

mkdir -p /etc/claude

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.

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

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:

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 con il tuo ambiente, quindi inizia il polling per il lavoro. Se il runner esce in seguito, riavvialo manualmente. Vedi Se il runner esce per sapere quando succede.

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. Il runner clona con qualsiasi credenziale git che l'host ha già.

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: l'errore appare nella sessione e nel log del runner. Se 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. Vedi Configura git, che copre anche le opzioni di credenziale per i repository privati in produzione.

Se il runner esce

Se il runner esce durante questa guida rapida, avvialo di nuovo con lo stesso comando. Il runner può uscire da solo:

  • Sessioni terminate: il log mostra [runner:exit] account workload drained — exiting. Il runner esce per progettazione una volta che le sue sessioni attive finiscono. Vedi Ciclo di vita del 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:

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