Skip to main content
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, run dei worker e dismissione delle macchine. Se vuoi solo eseguire sessioni da una macchina che hai già, inizia dalla guida rapida — non è necessario alcun orchestrator. Se fai il run su una piattaforma supportata, un’integrazione potrebbe già implementare questo ciclo per te. Per la documentazione completa di API e CLI, consulta il riferimento.
Fai il run su Kubernetes? devin-outpost-k8s è un operatore open source che implementa questo ciclo per te: monitora la coda, rivendica le sessioni in attesa e fa il run di ciascuna come worker pod su qualsiasi cluster certificato (GKE, EKS, …). Installalo con il suo chart Helm invece di sviluppare il tuo orchestrator.

​
Il flusso principale

​
  1. Registra un outpost

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

​
  1. Monitora l’API della flotta per le sessioni in attesa

L’orchestrator elenca le sessioni in attesa per gli outpost che gestisce:
Poi mantiene aggiornata la propria vista con un monitoraggio tramite Server-Sent Events (SSE), riprendendo dal cursor finale dell’elenco:
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 e Watch for changes per i parametri di query, i formati di risposta e la semantica completa della paginazione.

​
  1. Rivendica prima del provisioning

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:
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 in modo che la sessione torni immediatamente nella coda.

​
  1. Avvia una macchina ed esegui il run del worker

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 run del worker dalla directory in cui vuoi che la sessione lavori: i suoi repository si trovano nella sottodirectory repos di tale directory, ovvero $(pwd)/repos/<repo-name>:
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). Il worker si connette al cloud di Devin, segnala che la sessione è pronta e inizia a eseguire le chiamate agli strumenti.

​
  1. Arrestare la macchina quando il worker termina

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

​
Pianificazione decentralizzata

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

​
Creare un orchestrator personalizzato

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 e il contratto di spawn nel riferimento.