63 63
64| Host | Porta | Quando richiesto |64| Host | Porta | Quando richiesto |
65| :- | :- | :- |65| :- | :- | :- |
66| `api.github.com` | 443 | Con o senza `--use-anthropic-git-proxy`, quando l'immagine del runner include la [GitHub CLI](#github-api-access-with-the-github-cli) e fornisci alle sessioni una credenziale github.com, come un `GH_TOKEN` |
66| `downloads.claude.ai` | 443 | Al momento dell'installazione, quando installi o aggiorni Claude Code sull'host con il programma di installazione nativo; lo script `install.sh` stesso viene servito da `claude.ai`. Al momento dell'esecuzione della sessione, solo quando le sessioni installano plugin dal marketplace ufficiale di Anthropic. |67| `downloads.claude.ai` | 443 | Al momento dell'installazione, quando installi o aggiorni Claude Code sull'host con il programma di installazione nativo; lo script `install.sh` stesso viene servito da `claude.ai`. Al momento dell'esecuzione della sessione, solo quando le sessioni installano plugin dal marketplace ufficiale di Anthropic. |
67| `storage.googleapis.com` | 443 | Al momento dell'esecuzione della sessione, per i conteggi di installazione dei plugin e i metadati mostrati in `/plugin`. |68| `storage.googleapis.com` | 443 | Al momento dell'esecuzione della sessione, per i conteggi di installazione dei plugin e i metadati mostrati in `/plugin`. |
68| `code.claude.com` e `claude.com` | 443 | Ricerche di documentazione dall'agente claude-code-guide integrato e richieste WebFetch pre-approvate durante le sessioni. Il blocco di questi host influisce solo sulle ricerche di documentazione. |69| `code.claude.com` e `claude.com` | 443 | Ricerche di documentazione dall'agente claude-code-guide integrato e richieste WebFetch pre-approvate durante le sessioni. Il blocco di questi host influisce solo sulle ricerche di documentazione. |
167 168
168* Il runner imposta `GIT_TERMINAL_PROMPT=0`, in modo che git non chieda un nome utente o una password.169* Il runner imposta `GIT_TERMINAL_PROMPT=0`, in modo che git non chieda un nome utente o una password.
169* Il runner esegue SSH con `BatchMode=yes`, aggiunto al tuo `GIT_SSH_COMMAND` se ne imposti uno, in modo che SSH non chieda una passphrase o una conferma dell'host.170* Il runner esegue SSH con `BatchMode=yes`, aggiunto al tuo `GIT_SSH_COMMAND` se ne imposti uno, in modo che SSH non chieda una passphrase o una conferma dell'host.
170* Il runner imposta `GCM_INTERACTIVE=never`, in modo che Git Credential Manager non apra una finestra di dialogo di accesso.171* Il runner imposta `GCM_INTERACTIVE=never`, in modo che Git Credential Manager non apra una finestra di dialogo di accesso. Prima della v2.1.229, la preparazione del repository poteva bloccarsi su un prompt di Git Credential Manager.
171* Il runner cancella `core.askPass`, quindi se usi un helper askpass, impostalo attraverso la variabile di ambiente `GIT_ASKPASS` invece.172* Il runner cancella `core.askPass`, quindi se usi un helper askpass, impostalo attraverso la variabile di ambiente `GIT_ASKPASS` invece.
172 173
173Se il tuo host git rifiuta la credenziale, o non ne hai configurata una, il runner riprova alcune volte e poi fallisce la preparazione del repository quando il repository è quello in cui la sessione spinge i risultati. Per un repository dal quale la sessione legge solo, [Troubleshooting](#troubleshooting) copre quando il runner lo salta invece. Il runner non passa queste impostazioni nell'ambiente della sessione.174Se il tuo host git rifiuta la credenziale, o non ne hai configurata una, il runner riprova alcune volte e poi fallisce la preparazione del repository quando il repository è quello in cui la sessione spinge i risultati. Per un repository dal quale la sessione legge solo, [Troubleshooting](#troubleshooting) copre quando il runner lo salta invece. Il runner non passa queste impostazioni nell'ambiente della sessione.
287* **`jq`**: installa `jq` nell'immagine se vuoi che `--jq` funzioni288* **`jq`**: installa `jq` nell'immagine se vuoi che `--jq` funzioni
288* **[`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](https://code.claude.com/docs/it/env-vars)**: se l'ambiente della sessione la imposta, Claude Code non fornisce il `gh` integrato e la sessione non ha `gh`289* **[`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](https://code.claude.com/docs/it/env-vars)**: se l'ambiente della sessione la imposta, Claude Code non fornisce il `gh` integrato e la sessione non ha `gh`
289 290
290Quando l'immagine include la GitHub CLI, le sessioni usano quella.291#### Accesso all'API di GitHub con la GitHub CLI
292
293Se l'immagine del tuo runner include la GitHub CLI da far usare alle sessioni, fai in modo che il tuo [script wrapper](https://code.claude.com/docs/it/self-hosted-environments-configuration.md#provision-credentials-scoped-to-the-session-creator) crei per ogni sessione un `GH_TOKEN` a breve durata e con scope minimo per il creatore della sessione. Quando `gh` si trova nel `PATH` con cui Claude Code si avvia, la sessione ha quel `gh` e nessun [`gh` integrato](#github-api-access-without-the-github-cli). Con il token, quel `gh` raggiunge GitHub con qualunque accesso il token conceda e al di fuori di git gestito da Anthropic, quindi consenti [`api.github.com`](#network-requirements).
294
295Con git gestito da Anthropic, lascia la GitHub CLI fuori dall'immagine per usare invece il `gh` integrato.
291 296
292#### Affida un'autorità di certificazione privata a git gestito da Anthropic297#### Affida un'autorità di certificazione privata a git gestito da Anthropic
293 298
343 348
344La riscrittura dell'host viene eseguita per prima, quindi elenca il nome host interno in `--git-ssh-rewrite` se hai bisogno di entrambi. Per il controllo completo del checkout, usa un [`checkout` lifecycle hook](https://code.claude.com/docs/it/self-hosted-environments-configuration#checkout).349La riscrittura dell'host viene eseguita per prima, quindi elenca il nome host interno in `--git-ssh-rewrite` se hai bisogno di entrambi. Per il controllo completo del checkout, usa un [`checkout` lifecycle hook](https://code.claude.com/docs/it/self-hosted-environments-configuration#checkout).
345 350
351### Avvia una sessione su un repository esterno a GitHub
352
353Per eseguire una sessione su un repository di un host git diverso da GitHub, avvia la sessione dal tuo terminale, in un checkout di quel repository. Prima controlla le credenziali git del runner, la rete e il proxy git, l'indirizzo del repository e il tuo branch:
354
355* **Credenziali git e rete**: [fornisci credenziali](#ship-git-config-in-your-image) che [funzionino senza un prompt](#git-must-work-without-a-prompt) per `https://<host>/<owner>/<name>`, l'indirizzo che il runner clona, e consenti al runner di raggiungere il tuo host git, come elencato in [Requisiti di rete](#network-requirements). Per un host git che accetta solo SSH, vedi [`--git-ssh-rewrite`](#rewrite-git-urls-for-private-networks).
356* **Proxy git**: se i runner dell'ambiente usano il proxy git di Anthropic, [disattivalo](#turn-the-anthropic-git-proxy-off).
357* **Indirizzo del repository**: controlla il remote `origin` del checkout. Il suo host deve essere un nome di dominio come `git.example.com`, e il suo percorso deve avere la forma `<owner>/<name>`. Un percorso annidato come `group/subgroup/name` non è accettato.
358* **Branch**: esegui il push del branch su cui ti trovi al tuo host git, perché il runner clona quel branch.
359
360Nel checkout, dopo aver effettuato l'accesso a claude.ai come descritto in [Autenticarsi dalla CI](https://code.claude.com/docs/it/self-hosted-environments-testing.md#authenticate-from-ci), esegui `claude -p` con [`--environment`](https://code.claude.com/docs/it/self-hosted-environments-testing#run-the-test-loop) e l'ID `ccpool_...` del tuo ambiente:
361
362```bash theme={null}
363claude -p "Fix the login bug" --environment ccpool_abc123 --output-format json
364```
365
366Quando la sessione viene creata, il comando stampa una riga di JSON che inizia con `{"ok":true`. Se il remote `origin` non corrisponde ai requisiti, il comando fallisce con `requires a git source, but no GitHub remote was detected`.
367
368Esamina ed esegui il merge sul tuo host git dei branch di cui le sessioni [eseguono il push](https://code.claude.com/docs/it/self-hosted-environments-configuration.md#prompt-sessions-to-push-their-work).
369
346## Costruisci l'immagine del runner370## Costruisci l'immagine del runner
347 371
348Anthropic non pubblica un'immagine runner pre-costruita. Costruisci la tua intorno al binario `claude`, stratificando qualsiasi toolchain di cui i tuoi repository hanno bisogno: runtime di linguaggio, compilatori, gestori di pacchetti, e sidecar [MCP](https://code.claude.com/docs/it/mcp.md).372Anthropic non pubblica un'immagine runner pre-costruita. Costruisci la tua intorno al binario `claude`, stratificando qualsiasi toolchain di cui i tuoi repository hanno bisogno: runtime di linguaggio, compilatori, gestori di pacchetti, e sidecar [MCP](https://code.claude.com/docs/it/mcp.md).
617 641
618### Lascia finire i turni in esecuzione prima di un riavvio642### Lascia finire i turni in esecuzione prima di un riavvio
619 643
620Per lasciare che i turni in esecuzione finiscano prima di un riavvio rolling, imposta `--drain-wait-sec` e aumenta il timeout di arresto ad almeno quell'attesa più 80 secondi. Con l'attesa predefinita di `0`, un riavvio interrompe qualsiasi turno ancora in esecuzione, e la sessione riprende su un altro runner senza il suo [lavoro non pushato](#additional-limitations).644Per lasciare che i turni in esecuzione finiscano prima di un riavvio rolling, imposta `--drain-wait-sec` e aumenta il timeout di arresto ad almeno quell'attesa più 80 secondi. Con l'attesa predefinita di `0`, un riavvio interrompe qualsiasi turno ancora in esecuzione, e la sessione riprende su un altro runner senza il suo [lavoro non pushato](#resumed-sessions-lose-unpushed-work).
621 645
622* **`--drain-wait-sec`**: all'incirca la durata dei turni e delle attività in background che vuoi lasciar finire. È un massimo: l'attesa termina prima se finiscono prima.646* **`--drain-wait-sec`**: all'incirca la durata dei turni e delle attività in background che vuoi lasciar finire. È un massimo: l'attesa termina prima se finiscono prima.
623* **Il tuo timeout di arresto**: `terminationGracePeriodSeconds` in Kubernetes, `stop_grace_period` in Docker Compose. Ad esempio, con `--drain-wait-sec 120`, sostituisci il `90` nella ricetta [Kubernetes](#kubernetes) o [Docker Compose](#docker-compose) con `200`.647* **Il tuo timeout di arresto**: `terminationGracePeriodSeconds` in Kubernetes, `stop_grace_period` in Docker Compose. Ad esempio, con `--drain-wait-sec 120`, sostituisci il `90` nella ricetta [Kubernetes](#kubernetes) o [Docker Compose](#docker-compose) con `200`.
735 759
736Per rilasciare le sessioni inattive, avvia ogni runner con [`--release-idle-session-min`](https://code.claude.com/docs/it/self-hosted-environments-reference#runner-cli-flags) e quel tempo in minuti, ad esempio `--release-idle-session-min 30`. Il runner rilascia quindi qualsiasi sessione che resta inattiva così a lungo, sia che l'abbia avviata un'attività pianificata sia una persona, a meno che tu non la [trattenga per i processi che ha lasciato in esecuzione](#keep-an-idle-session-while-its-processes-run).760Per rilasciare le sessioni inattive, avvia ogni runner con [`--release-idle-session-min`](https://code.claude.com/docs/it/self-hosted-environments-reference#runner-cli-flags) e quel tempo in minuti, ad esempio `--release-idle-session-min 30`. Il runner rilascia quindi qualsiasi sessione che resta inattiva così a lungo, sia che l'abbia avviata un'attività pianificata sia una persona, a meno che tu non la [trattenga per i processi che ha lasciato in esecuzione](#keep-an-idle-session-while-its-processes-run).
737 761
738* **Lavoro non inviato**: una sessione rilasciata riprende al messaggio successivo, senza il lavoro di cui non aveva fatto il push. Per conservarne i commit, consulta [Le sessioni riprese perdono il lavoro non inviato](#additional-limitations).762* **Lavoro non inviato**: una sessione rilasciata riprende al messaggio successivo, senza il lavoro di cui non aveva fatto il push. Per conservarne i commit, consulta [Le sessioni riprese perdono il lavoro non inviato](#resumed-sessions-lose-unpushed-work).
739* **Uscita del runner**: un runner che rilascia la sua ultima sessione avvia una [normale uscita](#when-the-runner-exits). Fai in modo che il tuo supervisor lo riavvii su un filesystem pulito, come descritto in [Rafforza il tuo deploy](#harden-your-deployment).763* **Uscita del runner**: un runner che rilascia la sua ultima sessione avvia una [normale uscita](#when-the-runner-exits). Fai in modo che il tuo supervisor lo riavvii su un filesystem pulito, come descritto in [Rafforza il tuo deploy](#harden-your-deployment).
740* **Sessioni che non diventano mai inattive**: imposta anche [`--kill-session-after-min`](https://code.claude.com/docs/it/self-hosted-environments-reference#runner-cli-flags), perché [alcune sessioni non vengono considerate inattive](#some-sessions-don’t-count-as-idle)764* **Sessioni che non diventano mai inattive**: imposta anche [`--kill-session-after-min`](https://code.claude.com/docs/it/self-hosted-environments-reference#runner-cli-flags), perché [alcune sessioni non vengono considerate inattive](#some-sessions-don’t-count-as-idle)
741 765
811* Se un turno è ancora in esecuzione, il runner aspetta che il turno finisca, o che la sessione aspetti successivamente il suo utente, e poi la rilascia.835* Se un turno è ancora in esecuzione, il runner aspetta che il turno finisca, o che la sessione aspetti successivamente il suo utente, e poi la rilascia.
812* Se la sessione è ancora sul runner quando la finestra di grazia scade, il runner la termina, e il lavoro di qualsiasi turno in esecuzione è perso. Un turno che aspetta un'approvazione richiesta dall'interno di una chiamata di strumento in esecuzione è un modo in cui una sessione sopravvive alla finestra.836* Se la sessione è ancora sul runner quando la finestra di grazia scade, il runner la termina, e il lavoro di qualsiasi turno in esecuzione è perso. Un turno che aspetta un'approvazione richiesta dall'interno di una chiamata di strumento in esecuzione è un modo in cui una sessione sopravvive alla finestra.
813 837
814Una sessione rilasciata riprende da un clone fresco, quindi il lavoro che non aveva spinto è comunque perso; vedi [Le sessioni riprese perdono il lavoro non spinto](#additional-limitations). Prima di v2.1.260, il runner terminava ogni sessione al limite, dopo aver aspettato al massimo la finestra di grazia affinché un turno in esecuzione finisca.838Una sessione rilasciata riprende da un clone fresco, quindi il lavoro che non aveva spinto è comunque perso; vedi [Le sessioni riprese perdono il lavoro non spinto](#resumed-sessions-lose-unpushed-work). Prima di v2.1.260, il runner terminava ogni sessione al limite, dopo aver aspettato al massimo la finestra di grazia affinché un turno in esecuzione finisca.
815 839
816Imposta il flag sopra la tua sessione più lunga prevista, come `--kill-session-after-min 480` per 8 ore. Per liberare slot dalle conversazioni che diventano inattive, usa `--release-idle-session-min` invece.840Imposta il flag sopra la tua sessione più lunga prevista, come `--kill-session-after-min 480` per 8 ore. Per liberare slot dalle conversazioni che diventano inattive, usa `--release-idle-session-min` invece.
817 841
842### Le sessioni riprese perdono il lavoro non spinto
843
844Una sessione che riprende su un nuovo runner perde il lavoro che non aveva spinto, perché quel runner clona di nuovo il repository dal suo branch iniziale.
845
846Per conservare il lavoro di cui è stato fatto il commit, imposta [`--push-outcome-on-release`](https://code.claude.com/docs/it/self-hosted-environments-reference#runner-cli-flags) su ogni runner nell'ambiente. Un runner con il flag esegue un push best-effort dei branch di risultato della sessione prima del rilascio, e la sessione ripresa parte da quei commit. Un runner senza il flag riprende la sessione dal suo branch iniziale. Il push usa le credenziali git proprie dell'host del runner, anche su un runner che usa [git gestito da Anthropic](#use-the-anthropic-git-proxy).
847
848> [!WARNING]
849>
850> Prima di impostare il flag, limita chi può eseguire il push sui ref `claude/*` sul remote di origine. Alla ripresa, il runner recupera il branch precedentemente spinto senza verificare chi ne ha eseguito il push.
851
852Anche con il flag impostato, salva questo lavoro in un altro modo:
853
854* **Modifiche senza commit**: vengono comunque perse. Vedi [Chiedere alle sessioni di eseguire il push del proprio lavoro](https://code.claude.com/docs/it/self-hosted-environments-configuration.md#prompt-sessions-to-push-their-work).
855* **Repository estratti tramite un [hook del ciclo di vita `checkout`](https://code.claude.com/docs/it/self-hosted-environments-configuration#checkout)**: non vengono sottoposti a push. Crea uno snapshot di questi repository dall'[hook `post-session`](https://code.claude.com/docs/it/self-hosted-environments-configuration#post-session).
856* **Commit in una sessione che qualcuno archivia o elimina, o il cui runner viene rilasciato dal menu della sessione**: non fare affidamento sul push del flag. Per salvarli, esegui il push di `HEAD` su un branch di recupero da un [hook `post-session`](https://code.claude.com/docs/it/self-hosted-environments-configuration#post-session). L'esempio presente lì esegue il push solo dopo un commit di snapshot, quindi fai in modo che il tuo esegua il push anche quando non ci sono modifiche senza commit.
857
818### Limitazioni aggiuntive858### Limitazioni aggiuntive
819 859
820* **Le sessioni riprese perdono il lavoro non spinto**: un nuovo runner clona di nuovo il repository dal suo branch iniziale, quindi il lavoro che la sessione non aveva spinto è perso.
821 * **Per conservare il lavoro di cui è stato fatto il commit**: imposta [`--push-outcome-on-release`](https://code.claude.com/docs/it/self-hosted-environments-reference#runner-cli-flags) su ogni runner nell'ambiente, perché un runner senza il flag riprende la sessione dal suo branch iniziale. Un runner con il flag esegue un push best-effort dei branch di risultato della sessione prima del rilascio, e la sessione ripresa parte da quei commit. Il push usa le credenziali git proprie dell'host del runner, anche su un runner che usa [git gestito da Anthropic](#use-the-anthropic-git-proxy).
822 * **Con un hook `checkout`**: i repository estratti tramite un [hook del ciclo di vita `checkout`](https://code.claude.com/docs/it/self-hosted-environments-configuration#checkout) non vengono sottoposti a push. Crea invece uno snapshot di questi repository dall'[hook `post-session`](https://code.claude.com/docs/it/self-hosted-environments-configuration#post-session).
823 * **Prima di abilitare il flag**: limita chi può eseguire il push sui ref `claude/*` sul remote di origine. Alla ripresa, il runner recupera il branch precedentemente spinto senza verificare chi ne ha eseguito il push.
824 * **Le modifiche senza commit vengono comunque perse**: per chiedere a Claude di fare il commit e il push quando finisce di rispondere, vedi [Chiedere alle sessioni di eseguire il push del proprio lavoro](https://code.claude.com/docs/it/self-hosted-environments-configuration.md#prompt-sessions-to-push-their-work)
825* **Un comando interrotto dalla perdita di un runner può essere eseguito di nuovo**: quando la sessione riprende su un altro runner, Claude vede la chiamata allo strumento interrotta con un risultato che indica che il suo esito è sconosciuto.860* **Un comando interrotto dalla perdita di un runner può essere eseguito di nuovo**: quando la sessione riprende su un altro runner, Claude vede la chiamata allo strumento interrotta con un risultato che indica che il suo esito è sconosciuto.
826* **Un repository aggiunto a metà sessione può non riuscire a essere clonato**: Claude lo clona con `git clone` tramite HTTPS. Su un runner senza [`--use-anthropic-git-proxy`](#use-the-anthropic-git-proxy), il clone fallisce con un errore di autenticazione git se nulla sull'host può leggere il repository. Quando possibile, seleziona ogni repository di cui la sessione ha bisogno quando la crei.861* **Un repository aggiunto a metà sessione può non riuscire a essere clonato**: Claude lo clona con `git clone` tramite HTTPS. Su un runner senza [`--use-anthropic-git-proxy`](#use-the-anthropic-git-proxy), il clone fallisce con un errore di autenticazione git se nulla sull'host può leggere il repository. Quando possibile, seleziona ogni repository di cui la sessione ha bisogno quando la crei.
827 * **Quando la sessione riprende**: un [hook `checkout`](https://code.claude.com/docs/it/self-hosted-environments-configuration#checkout) viene eseguito anche per il repository aggiunto, con [`CLAUDE_RUNNER_REPO_REF`](https://code.claude.com/docs/it/self-hosted-environments-configuration#checkout) vuoto, quindi fai in modo che il tuo hook gestisca questo caso.862 * **Quando la sessione riprende**: un [hook `checkout`](https://code.claude.com/docs/it/self-hosted-environments-configuration#checkout) viene eseguito anche per il repository aggiunto, con [`CLAUDE_RUNNER_REPO_REF`](https://code.claude.com/docs/it/self-hosted-environments-configuration#checkout) vuoto, quindi fai in modo che il tuo hook gestisca questo caso.
828* **Alcuni connettori non appaiono nelle sessioni self-hosted**: un connettore che non hai ancora connesso nelle Impostazioni di claude.ai non è elencato in una sessione self-hosted, e la sessione non ti chiederà di connettarlo. Connettilo prima nelle Impostazioni, quindi avvia una sessione fresca. L'aggiunta di un connettore a una sessione già in esecuzione non rende i suoi strumenti disponibili a Claude; avvia una sessione fresca per raccogliere un connettore appena aggiunto.863* **Alcuni connettori non appaiono nelle sessioni self-hosted**: un connettore che non hai ancora connesso nelle Impostazioni di claude.ai non è elencato in una sessione self-hosted, e la sessione non ti chiederà di connettarlo. Connettilo prima nelle Impostazioni, quindi avvia una sessione fresca. L'aggiunta di un connettore a una sessione già in esecuzione non rende i suoi strumenti disponibili a Claude; avvia una sessione fresca per raccogliere un connettore appena aggiunto.
829* **Quando qualcuno archivia o elimina una sessione, o rilascia il suo runner dal menu della sessione**: non fare affidamento sul push di [`--push-outcome-on-release`](https://code.claude.com/docs/it/self-hosted-environments-reference#runner-cli-flags). Per salvare i commit in questi casi, esegui il push di `HEAD` su un branch di recupero da un [hook `post-session`](https://code.claude.com/docs/it/self-hosted-environments-configuration#post-session). Se parti dall'esempio presente lì, fai in modo che esegua il push anche quando non ci sono modifiche senza commit, perché esegue il push solo dopo un commit di snapshot.
830 864
831### Segnala un problema865### Segnala un problema
832 866
