SpyBara
Go Premium

self-hosted-environments.md 2026-10-22 22:58 UTC to 2026-10-23 22:59 UTC

This page contains 31 additions and 31 deletions.

2026
Thu 1 23:59 Fri 2 22:59 Tue 6 23:59 Sat 10 23:01 Wed 14 22:58 Tue 20 23:00 Thu 22 22:58 Fri 23 22:59 Sat 24 22:59 Thu 29 23:57 Fri 30 23:01

Ambienti self-hosted

Esegui sessioni cloud di Claude Code su infrastrutture che controlli: configura un ambiente self-hosted, distribuisci runner e instrada le sessioni al tuo calcolo.

[!NOTE]

Gli ambienti self-hosted sono in beta pubblica sui piani Team ed Enterprise e sono disabilitati per impostazione predefinita. Vedi Disponibilità e limitazioni per il percorso di abilitazione e cosa è escluso.

Un ambiente self-hosted esegue sessioni cloud di Claude Code su infrastrutture che la tua organizzazione gestisce. Una sessione cloud è qualsiasi sessione che viene eseguita in un luogo diverso dalla macchina dello sviluppatore. Gli sviluppatori le avviano da claude.ai, dalle app mobile e desktop, dal terminale con claude --cloud e dalle attività pianificate cloud. Per impostazione predefinita, le sessioni cloud vengono eseguite sull'infrastruttura di Anthropic.

In un ambiente self-hosted, quelle stesse sessioni vengono eseguite all'interno della tua rete. L'esperienza dello sviluppatore è altrimenti la stessa a parte le differenze in Disponibilità e limitazioni e i problemi noti della pagina di distribuzione.

Se il tuo team non utilizza sessioni cloud, non c'è nulla da configurare qui: le sessioni in un terminale o IDE vengono sempre eseguite sulla macchina dello sviluppatore. Se desideri eseguire Claude Code sulla tua macchina sempre accesa e controllarla da altri dispositivi, utilizza Remote Control, che è disponibile anche sui piani Pro e Max. Quando sei pronto per la configurazione, vai direttamente alla guida rapida; per rivedere prima il profilo di sicurezza, inizia con Distribuisci in produzione. Il resto di questa pagina spiega come funziona il self-hosting e quando sceglierlo.

Come funzionano gli ambienti self-hosted

Il self-hosting ha tre parti:

  • Environment: una destinazione denominata a cui possono essere inviate sessioni cloud. La tua organizzazione crea ambienti nelle impostazioni di amministrazione di claude.ai, e ognuno raggruppa un insieme di runner.
  • Runner: un programma in esecuzione su host all'interno della tua rete. I runner eseguono le sessioni; l'idea è la stessa di un runner CI self-hosted.
  • Session: un'attività Claude Code avviata da uno sviluppatore.

Quando uno sviluppatore avvia una sessione cloud, l'interfaccia utente di avvio della sessione mostra un selettore di ambiente che elenca gli ambienti ospitati da Anthropic insieme a quelli creati dalla tua organizzazione. Se scelgono il tuo, il piano di controllo di Anthropic posiziona la sessione nella coda del tuo ambiente, dove un runner la rivendica, clona il repository scelto dallo sviluppatore e avvia un processo Claude Code sul tuo host per eseguirlo. Il runner si autentica al tuo host git con credenziali che configuri; Configura git copre le opzioni. Le sessioni raggiungono i tuoi servizi interni dall'interno della tua rete, e il tuo host git allo stesso modo quando è interno; il traffico verso Anthropic, il polling della coda, il flusso di eventi della sessione e, per impostazione predefinita, l'inferenza del modello, è HTTPS in uscita verso api.anthropic.com, con il breve elenco di ulteriori host che le sessioni possono raggiungere in Requisiti di rete. Anthropic non si connette mai alla tua rete.

Diagramma dell'architettura di un ambiente self-hosted: il confine della tua rete contiene un runner, due processi di sessione Claude Code al suo interno e il tuo host git, con api.anthropic.com all'esterno che contiene coda, flusso di sessione e inferenza. Il runner esegue il polling della coda e raggiunge l'host git, ogni processo di sessione apre le proprie connessioni di flusso, inferenza e git, e ogni connessione è in uscita dalla tua rete, senza nessuna in entrata.

I due riquadri Claude Code nel diagramma sono processi di sessione: un runner che esegue due sessioni contemporaneamente, fino alla sua capacità configurata. Un runner serve un proprietario alla volta e si blocca a quel proprietario quando rivendica la sua prima sessione, quindi il codice estratto non si mescola mai tra proprietari; Ciclo di vita del runner copre la regola.

Puoi avviare i runner tu stesso e mantenerli in esecuzione, oppure eseguire l'orchestrator di autoscaling, un secondo processo che ospiti, che avvia i runner mentre le sessioni si accodano; ogni runner esce da solo quando il suo lavoro finisce. In entrambi i casi, configuri l'ambiente una volta, e appare nel selettore su ogni superficie supportata.

Disponibilità e limitazioni

Controlla questi punti prima di pianificare un rollout:

Perché fare self-hosting

La maggior parte dei team è meglio servita da ambienti ospitati da Anthropic, che non richiedono infrastrutture da eseguire o mantenere. Il self-hosting è per team le cui esigenze di rete, tooling o conformità richiedono di mantenere l'esecuzione della sessione su infrastrutture che controllano. Se è così, pianifica la proprietà operativa che comporta: costruisci e mantieni l'immagine del runner, gestisci la flotta e controlli la sua rete.

In cambio, il self-hosting ti dà accesso alla rete, tooling personalizzato e controllo della conformità:

  • Accesso alla rete: le sessioni vengono eseguite all'interno della tua rete e possono raggiungere servizi interni, database e registri senza esporli a Internet pubblico
  • Tooling personalizzato: pre-installa compilatori, SDK e CLI interni nella tua immagine di runner in modo che ogni sessione inizi pronta a compilare
  • Conformità: gli estratti di repository e gli artefatti di build rimangono su infrastrutture che controlli. Il contenuto della sessione va comunque a api.anthropic.com.

Ambienti, runner e sessioni

Gli ambienti vengono gestiti sulla pagina Cloud environments nelle impostazioni di amministrazione di claude.ai; i runner sono processi che avvii e gestisci sulla tua infrastruttura.

Concetti chiave

Questi termini appaiono in tutte le pagine self-hosted:

Termine Che cos'è
Environment Un gruppo denominato dei tuoi runner, creato nelle impostazioni di claude.ai. Le sessioni vengono instradate a un ambiente, non a un singolo runner.
Environment secret La singola credenziale condivisa che i runner utilizzano per autenticarsi e registrarsi con l'ambiente. Mostrata una sola volta alla creazione dell'ambiente, etichettata come environment key nell'interfaccia di amministrazione.
Runner Il processo di lunga durata che distribuisci. Un runner si registra con l'ambiente, riceve un token di runner e esegue il polling per le sessioni.
Session Un'attività Claude Code, avviata da claude.ai, dall'app mobile o da un'altra superficie Anthropic come un'attività pianificata o un agente. Ogni sessione viene eseguita come un processo Claude Code figlio che il runner genera.

Nei campi API, nelle rivendicazioni di token e nei nomi delle metriche, l'ambiente appare come pool, e l'ID dell'ambiente è il pool_id. Il riferimento mappa i due nomi, inclusi i nomi di flag pool deprecati.

Un runner serve un proprietario alla volta. La prima sessione che un runner raccoglie blocca il runner a quel proprietario della sessione, e il runner quindi esegue sessioni solo per quel proprietario, fino a una capacità configurata. Chi è il proprietario dipende da come è stata avviata la sessione:

  • Sessioni avviate da un utente: il proprietario è l'account di quell'utente.
  • Sessioni del canale Claude Tag: Claude le esegue senza alcun account utente allegato, quindi il proprietario è l'agente Claude Tag che ha avviato la sessione. Ogni sessione di canale che quell'agente avvia ha lo stesso proprietario, chiunque abbia inviato il messaggio Slack, quindi un runner bloccato ad esso serve sessioni che persone diverse hanno avviato quando lo esegui a una --capacity superiore a uno o con un --drain-grace-sec positivo.

La dimensione minima della flotta è quindi il numero di proprietari che ti aspetti siano attivi contemporaneamente, contando utenti e agenti Claude Tag.

Ciclo di vita della sessione

Quando uno sviluppatore avvia una sessione e seleziona il tuo ambiente, il piano di controllo di Anthropic posiziona la sessione nella coda dell'ambiente. Da lì:

  1. Un runner con capacità libera rivendica la sessione e mantiene un lease su di essa.
  2. Il runner clona il repository nella sua directory di lavoro e genera un processo Claude Code figlio.
  3. Il figlio trasmette gli eventi indietro su HTTPS mentre il runner continua a eseguire il polling; ogni polling aggiorna il lease e funge anche da heartbeat.
  4. Se il runner smette di eseguire il polling, il suo lease scade dopo circa 60 secondi. Il server può quindi impiegare alcuni minuti, e a volte di più, per rimettere in coda la sessione per un altro runner.

Il runner assegna a ogni richiesta di polling 10 secondi. Quando una richiesta scade, viene persa o riceve una risposta che il runner non può analizzare, il runner continua a servire le sue sessioni attive e riprova dopo un secondo o due invece di aspettare il prossimo polling programmato. Ad esempio, un proxy di intercettazione che risponde al polling con la sua stessa pagina produce una risposta che il runner non può analizzare. Ogni volta che un'altra richiesta fallisce in uno di questi modi, il runner raddoppia il gap prima del prossimo tentativo, fino a 20 secondi, e accorcia il gap ogni volta che il lease sta per scadere.

Ciclo di vita del runner

La prima sessione che un runner raccoglie blocca il runner a quel proprietario della sessione, e il runner esegue fino a --capacity sessioni concorrenti per quel proprietario. Mentre il runner ha sessioni attive e non ha ricevuto un segnale di arresto o raggiunto il suo tempo di ritiro, il runner continua a rivendicare il lavoro in coda del proprietario bloccato. Quello che succede una volta che finiscono dipende da --drain-grace-sec:

  • Al valore predefinito di 0: il runner esce non appena le sue sessioni attive finiscono, senza eseguire il polling per altri, quindi l'orchestrator che lo distribuisci, come Kubernetes, può riavviarlo con un disco fresco, pronto a servire qualsiasi proprietario.
  • A un valore positivo: il runner continua a eseguire il polling della coda del proprietario bloccato per quel numero di secondi prima di uscire.

Questo ciclo di vita isola il codice estratto di ogni proprietario senza richiedere al runner di eliminare lo stato del disco tra proprietari.

Il modo in cui la tua infrastruttura arresta un runner decide se hai bisogno di --retire-at. Un kill che consegna SIGTERM non ha bisogno di flag: il runner drena come Shutdown timing descrive, o continua a servire le sessioni che già tiene quando imposti --defer-shutdown-max-min. Se la tua infrastruttura invece distrugge gli host a un'ora di parete nota senza un segnale, o con un periodo di grazia troppo breve per drenare, come un limite di durata della sandbox o una reclama di istanza spot, passa --retire-at <epoch-seconds> impostato a pochi minuti prima di quel momento. Al momento del ritiro:

  1. Il runner smette di accettare nuovo lavoro.
  2. Il runner rilascia ogni sessione attiva attraverso lo stesso percorso di rilascio che il flag --release-idle-session-min utilizza, quindi la sessione riprende su un runner fresco quando l'utente invia il suo prossimo messaggio. Quando il runner rilascia ogni sessione dipende dal suo stato:
    • Il runner rilascia una sessione che è a metà turno dopo che quel turno finisce. Prima aspetta che il processo della sessione segnali la fine del turno ad Anthropic, per non più di SELF_HOSTED_RUNNER_POST_TURN_SETTLE_MS. Prima della v2.1.280, il runner rilasciava la sessione non appena il turno finiva.
    • Quando un turno finisce e lascia attività in background in esecuzione, il runner aspetta fino a 60 secondi per loro, quindi rilascia la sessione anche se sono ancora in esecuzione. Se le attività hanno finito ma il turno successivo che legge i loro risultati non è ancora stato eseguito, il runner mantiene la sessione fino a quando quel turno finisce, e aspetta non più di SELF_HOSTED_RUNNER_BG_RESULT_GRACE_MS per l'inizio di quel turno.
  3. Il runner esce 0 una volta che tutte le sue sessioni sono rilasciate.

Un turno che sopravvive al kill è comunque perso; Shutdown timing copre il dimensionamento del margine. Senza --retire-at, un kill di host senza segnale è indistinguibile da un crash: il piano di controllo registra un worker perso piuttosto che un rilascio pulito, e la sessione viene rimessa in coda a un altro runner.

Percorsi di rete

Il runner e le sue sessioni effettuano diversi tipi di connessione in uscita, e non è richiesta alcuna connettività in entrata da Anthropic:

  • Piano di controllo: il runner esegue il polling di api.anthropic.com per il lavoro e pubblica gli eventi di progresso della configurazione e di errore, tutto HTTPS in uscita. Il polling funge anche da heartbeat del runner.
  • Git: il runner clona dal tuo host git e vi esegue il push su HTTPS o SSH, autenticato con credenziali fornite dal tuo deploy. Vedi Configura git per le opzioni, incluse le credenziali coniate per sessione. Con il proxy git Anthropic, il traffico git per i repository su github.com passa invece attraverso api.anthropic.com.
  • Session child: il processo Claude Code figlio mantiene il flusso di eventi della sessione verso api.anthropic.com, ed effettua le proprie chiamate in uscita per l'inferenza del modello e per i comandi git eseguiti durante la sessione. In una sessione che utilizza git gestito da Anthropic, il figlio invia il suo traffico git e gh per github.com tramite una connessione WebSocket che apre verso api.anthropic.com.
  • SCM connector: l'SCM connector facoltativo dell'orchestrator non è disponibile, quindi il suo tunnel non si apre. Il tunnel è una connessione WebSocket verso api.anthropic.com.

Vedi Requisiti di rete per l'elenco completo dell'uscita. Il diagramma sopra mostra questi percorsi, a parte l'SCM connector facoltativo e la connessione git gestita da Anthropic.

Per impostazione predefinita, l'inferenza del modello utilizza l'API Anthropic. Il piano di controllo consegna l'endpoint API a ogni sessione, e la sessione si autentica con un token OAuth emesso da Anthropic e limitato alla sessione. Per inviare invece le richieste del modello al tuo account cloud, vedi Invia le richieste del modello a Bedrock o Agent Platform.

I proxy di uscita aziendali sono supportati. Il runner e l'orchestrator di autoscaling facoltativo rispettano il proxy e le variabili di ambiente mTLS descritte in Configurazione di rete, come HTTPS_PROXY e NO_PROXY; impostale nell'ambiente di ogni processo. Le variabili coprono le chiamate del piano di controllo, il WebSocket SCM connector dell'orchestrator, e il clone integrato per i remote HTTPS, e le sessioni le ereditano dal runner. Lo streaming della sessione utilizza server-sent events su HTTPS, quindi un proxy nel percorso non deve memorizzare le risposte nel buffer.

Se il tuo proxy richiede anche un'intestazione Proxy-Authorization, il runner può aggiungerla a ogni connessione che apre al proxy; vedi Autentica a un proxy di uscita.

Cosa rimane sulla tua infrastruttura

Gli estratti di repository, gli artefatti di compilazione, i segreti e tutti i file che una sessione crea o modifica rimangono sulle macchine che fornisci. La conversazione stessa, inclusi i prompt, le risposte e i risultati degli strumenti, va a api.anthropic.com, e Anthropic archivia la trascrizione della sessione in modo che tu possa riprendere la sessione da un'altra superficie supportata. Quando un runner invia le richieste al modello ad Amazon Bedrock o all'Agent Platform di Google Cloud, la conversazione va comunque a api.anthropic.com nel flusso di eventi della sessione.

Un ambiente self-hosted sposta l'esecuzione della sessione nella tua rete. Il piano di controllo rimane ospitato da Anthropic: l'orchestrazione della sessione, l'accodamento e l'interfaccia di claude.ai continuano a essere eseguiti su infrastrutture di Anthropic.

Inizia

Le pagine degli ambienti self-hosted sono organizzate per quello che stai facendo:

  • Guida rapida: installa Claude Code, crea un ambiente, avvia un runner e instrada la tua prima sessione
  • Distribuisci in produzione: hardening della sicurezza, uscita di rete, credenziali git, ricette Kubernetes e Compose, problemi noti e risoluzione dei problemi
  • Personalizza sessioni: script wrapper per credenziali per sessione, hook del ciclo di vita, runner on-demand, server MCP e autorizzazioni
  • Testa end to end: un test di fumo CI che verifica un'immagine di runner prima di promuoverla
  • Riferimento: ogni flag CLI, variabile di ambiente, metrica e l'endpoint di salute
  • Verifica l'identità della sessione: convalida il token di sessione dai tuoi servizi prima di concedere l'accesso