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

# Orchestrazione

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

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

Se vuoi solo eseguire sessioni da una macchina che hai già, inizia dalla [guida rapida](/it/cloud/outposts/quickstart) — non è necessario alcun orchestrator. Se esegui su una piattaforma supportata, un'[integrazione](/it/cloud/outposts/overview#integrations) potrebbe già implementare questo ciclo per te. Per la documentazione completa di API e CLI, consulta il [riferimento](/it/cloud/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 come worker pod su
  qualsiasi cluster certificato (GKE, EKS, ...). Installalo con il suo chart
  Helm invece di sviluppare il tuo orchestrator.
</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 con nome, 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.) quando avvii una sessione. Le sessioni indirizzate a quell'outpost restano in attesa nella sua coda finché un worker non le rivendica.

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

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

L'orchestrator elenca le sessioni in attesa 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 propria vista con un monitoraggio tramite 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 è il pattern standard di Kubernetes list-then-watch: scorri l'elenco per pagine usando il cursor della risposta, quindi avvia un watch dal punto in cui l'elenco si è fermato, salvando il cursor di ogni evento così da poterti riconnettere senza perdere modifiche. La consegna avviene almeno una volta, quindi esegui l'upsert in base a `metadata.session_id` e tollera i duplicati. Consulta [List queued sessions](/it/cloud/outposts/reference#list-queued-sessions) e [Watch for changes](/it/cloud/outposts/reference#watch-for-changes) per i parametri di query, i formati 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ì che nessun altro worker la prenda in carico. Specifica un `acceptor_id` — un'identità dichiarata dal worker stesso:

```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 rivendicazioni sono atomiche: se un altro worker ha rivendicato per primo la sessione, si ottiene un `409`. La rivendicazione garantisce che un worker sarà pronto entro la scadenza della rivendicazione assegnata dal server (`status.claim_deadline`); le rivendicazioni scadute tornano automaticamente nella coda. Se il provisioning non riesce, [rilascia la rivendicazione](/it/cloud/outposts/reference#release-a-claim) in modo che la sessione torni immediatamente nella coda.

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

Per ogni sessione presa in carico, 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 i repository della sessione sono già stati clonati:

```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` (vedi l’[elenco completo dei flag](/it/cloud/outposts/reference#devin-worker-start)). Il worker si connette al cloud di Devin, segnala che la sessione è pronta e inizia a eseguire le chiamate agli strumenti.

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

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

Il tuo orchestrator può tenere traccia delle session rivendicate e dei rispettivi stati:

```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 un `status.session_status` impostato su `pending`, `running`, `suspended` o `terminated`.

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

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

Non serve uno scheduler centrale per gestire 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 osserva 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` circoscrive le rivendicazioni, i rinnovi e il recupero dopo il riavvio al solo worker a cui appartiene. `devin worker start` ne genera e salva automaticamente uno per ogni macchina, quindi una flotta non richiede alcuna configurazione dell'identità. Non condividere mai un acceptor ID (o una directory dei dati del worker copiata) tra macchine: worker in conflitto si ruberanno a vicenda le rivendicazioni.
* **I problemi 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 possa prenderla. Non è necessario alcun monitoraggio dello stato a livello di flotta.

Questo significa che scalare orizzontalmente consiste semplicemente nell'eseguire il worker su più macchine che puntano allo stesso outpost: N macchine servono N sessioni simultanee, mentre le altre restano in attesa.

<div id="building-a-custom-orchestrator">
  ## Creare un orchestrator 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 tu stesso con l'ambiente descritto nella documentazione. Consulta [Distribuzione del file binario remoto](/it/cloud/outposts/reference#remote-binary-distribution) e il [contratto di spawn](/it/cloud/outposts/reference#spawn-contract) nel riferimento.