> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devinenterprise.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Orchestrazione

> Esegui automaticamente il provisioning delle macchine e avvia i worker quando le sessioni entrano in coda

Un orchestratore monitora l'API di Outposts per le sessioni in attesa su un outpost, esegue il provisioning di una VM o di un container per ciascuna e avvia al suo interno il worker. Questa pagina descrive il ciclo di orchestrazione: polling della coda, rivendicazione delle sessioni, esecuzione dei worker e rimozione delle macchine.

Se vuoi semplicemente gestire sessioni da una macchina che hai già, inizia dalla [guida rapida](/it/onboard-devin/outposts/quickstart) — non serve alcun orchestratore. Se esegui su una piattaforma supportata, un'[integrazione](/it/onboard-devin/outposts#integrations) potrebbe già implementare questo ciclo per te. Per la documentazione completa di API e CLI, consulta il [riferimento](/it/onboard-devin/outposts/reference).

<Note>
  Usi Kubernetes? [devin-outpost-k8s](https://github.com/CognitionAI/devin-outpost-k8s)
  è un operatore open source che implementa questo ciclo per te: monitora la
  coda, rivendica le sessioni in attesa ed esegue ciascuna di esse come pod
  worker su qualsiasi cluster certificato (GKE, EKS, ...). Installalo con il suo
  chart Helm invece di creare il tuo orchestratore.
</Note>

<div id="the-core-flow">
  ## Il flusso principale
</div>

<div id="1-register-an-outpost">
  ### 1. Registra un outpost
</div>

Un outpost è una coda di sessioni denominata, gestita da più worker nella tua infrastruttura (ad esempio, `rhel`, `gpu-h200` o `my-outpost`). Creane uno con `devin worker outpost create`:

```bash theme={null}
devin worker outpost create <name> --platform <platform> --description "..."
```

Una volta registrato, l'outpost appare come opzione di macchina in Devin Cloud (insieme a Ubuntu, Windows, ecc.) all'avvio di una sessione. Le sessioni indirizzate a quell'outpost restano in attesa nella sua coda finché un worker non le prende in carico.

<Note>
  Nell'API della flotta, gli outpost sono rappresentati come risorse `outposts`, nell'ambito del
  tuo account (condivise tra tutte le sue organizzazioni). Vedi gli
  [endpoint degli outpost](/it/onboard-devin/outposts/reference#outposts).
</Note>

<div id="2-watch-the-fleet-api-for-waiting-sessions">
  ### 2. Monitora l'API della flotta per individuare le sessioni in attesa
</div>

L'orchestratore elenca le sessioni in sospeso per gli outpost che gestisce:

```bash theme={null}
curl -H "Authorization: Bearer $DEVIN_API_TOKEN" \
  "https://api.devin.ai/opbeta/outposts/devins?outpost=<outpost_id>&phase=pending"
```

Poi mantiene aggiornata la visualizzazione tramite un monitoraggio con Server-Sent Events (SSE), riprendendo dal `cursor` finale dell'elenco:

```bash theme={null}
curl -N -H "Authorization: Bearer $DEVIN_API_TOKEN" \
  "https://api.devin.ai/opbeta/outposts/devins?outpost=<outpost_id>&watch=true&cursor=<cursor>"
```

Questo segue il pattern standard di Kubernetes list-then-watch: scorri l’elenco pagina per pagina con il cursore della risposta, quindi avvia un watch dal punto in cui l’elenco si è fermato, salvando il cursore di ogni evento così da poterti riconnettere senza perdere modifiche. La consegna è di tipo at-least-once, quindi esegui l’upsert in base a `metadata.session_id` e tollera i duplicati. Consulta [List queued sessions](/it/onboard-devin/outposts/reference#list-queued-sessions) e [Watch for changes](/it/onboard-devin/outposts/reference#watch-for-changes) per i parametri di query, le strutture di risposta e la semantica completa della paginazione.

<div id="3-claim-before-provisioning">
  ### 3. Rivendica prima del provisioning
</div>

Prima di avviare una macchina per una sessione, rivendicala in modo atomico, così nessun altro worker potrà prenderla in carico. Passa un `acceptor_id`, ovvero un'identità autodichiarata del tuo worker:

```bash theme={null}
curl -X POST -H "Authorization: Bearer $DEVIN_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"acceptor_id": "worker-1"}' \
  "https://api.devin.ai/opbeta/outposts/devins/{session_id}/claim"
```

Le operazioni di rivendicazione sono atomiche: se un altro worker ha già rivendicato la sessione, si riceve un `409`. Rivendicare garantisce che un worker sarà pronto entro la scadenza della rivendicazione assegnata dal server (`status.claim_deadline`); le rivendicazioni scadute tornano automaticamente in coda. Se il provisioning non riesce, [rilascia la rivendicazione](/it/onboard-devin/outposts/reference#release-a-claim) in modo che la sessione torni immediatamente in coda.

<div id="4-spawn-a-machine-and-run-the-worker">
  ### 4. Avvia una macchina ed esegui il worker
</div>

Per ogni sessione rivendicata, esegui il provisioning di una VM o di un container a partire dalla tua immagine. Al suo interno, esegui il worker dalla directory in cui è già stato eseguito il checkout dei repository della sessione:

```bash theme={null}
cd /path/to/repos
devin worker start --session=<session_id> --outpost=<outpost_id> --acceptor-id=<worker_id>
```

Passa lo stesso `--acceptor-id` che hai usato per la rivendicazione tramite API e fornisci il token tramite `--token` o `DEVIN_OUTPOSTS_TOKEN` (consulta l’[elenco completo dei flag](/it/onboard-devin/outposts/reference#devin-worker-start)). Il worker si connette al cloud di Devin, contrassegna la sessione come pronta e inizia a eseguire le tool call.

<div id="5-terminate-the-machine-when-the-worker-exits">
  ### 5. Terminare la macchina quando il worker termina
</div>

Quando `devin worker start` termina, la sessione è conclusa (o è stata sospesa). Termina la VM o il container. Se il tuo outpost supporta la ripresa, crea uno snapshot della macchina prima di terminarla, così potrai ripristinarla se la sessione riprende.

Il tuo orchestrator può tenere traccia delle sessioni rivendicate e del loro stato:

```bash theme={null}
curl -H "Authorization: Bearer $DEVIN_API_TOKEN" \
  "https://api.devin.ai/opbeta/outposts/devins?phase=claimed&acceptor_id=worker-1"
```

Ogni voce riporta `status.session_status` con valore `pending`, `running`, `suspended` o `terminated`.

<div id="centralization-free-scheduling">
  ## Pianificazione senza centralizzazione
</div>

<Note>
  Hai in programma di eseguire più di \~16 coordinatori (worker o orchestratori
  che monitorano e rivendicano sessioni da un outpost)? Contatta prima il team del tuo account: flotte
  più grandi aumentano la contesa sulle rivendicazioni e il carico di lettura della coda, e vogliamo
  assicurarci che l'outpost sia dimensionato adeguatamente.
</Note>

Non serve un pianificatore centrale per eseguire una flotta. L'API della coda è progettata in modo che molti worker indipendenti possano servire lo stesso outpost senza comunicare tra loro:

* **Le rivendicazioni sono l'unico meccanismo di coordinamento.** Ogni worker monitora la coda in modo indipendente e compete per rivendicare le sessioni in attesa. La rivendicazione è un'operazione atomica di compare-and-swap sul server: vince un solo worker, mentre tutti gli altri ricevono un `409` e passano semplicemente alla sessione in attesa successiva. Perdere la corsa alla rivendicazione è un comportamento normale, non un errore.
* **Ogni worker ha una propria identità.** `acceptor_id` limita le rivendicazioni, i rinnovi e il ripristino dopo il riavvio al solo worker a cui appartiene. `devin worker start` ne genera e memorizza automaticamente uno per ogni machine, quindi una flotta non richiede alcuna configurazione dell'identità. Non condividere mai un acceptor ID (o una directory dati del worker copiata) tra machine diverse: worker in conflitto si sottrarrebbero a vicenda le rivendicazioni.
* **Gli errori si risolvono automaticamente.** Se un worker si arresta dopo aver rivendicato una sessione, la sua rivendicazione scade alla claim deadline e la sessione torna nella coda perché un altro worker la possa recuperare. Non è necessario alcun monitoraggio dello stato di salute a livello di flotta.

Questo significa che per scalare orizzontalmente basta eseguire il worker su più machine che puntano allo stesso outpost: N machine servono N sessioni simultanee, mentre le altre restano in attesa.

<div id="building-a-custom-orchestrator">
  ## Creare un orchestratore personalizzato
</div>

Tutto ciò che fa `devin worker start` è disponibile direttamente tramite l'API della flotta, quindi puoi sostituire completamente la CLI: scarica il file binario `devin-remote` dalla distribuzione statica di Devin e avvialo direttamente con l'ambiente documentato. Consulta [Distribuzione remota del binario](/it/onboard-devin/outposts/reference#remote-binary-distribution) e il [contratto di spawn](/it/onboard-devin/outposts/reference#spawn-contract) nella documentazione di riferimento.