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 sessione è 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 sessione riprende.

​
Directory da rendere persistenti

Una sessione sospesa può essere ripresa in seguito e si aspetta di ritrovare i propri file dove li ha lasciati. Ripristina queste directory prima di avviare il worker per una sessione ripresa: Uno snapshot dell’intera macchina le include entrambe. Se rendi persistente solo una parte del filesystem (ad esempio un volume per la home directory), assicurati che entrambe le directory si trovino su quel volume e, alla ripresa, avvia il worker nella stessa directory di lavoro. All’avvio di una sessione, Devin scrive un piccolo file di marcatura in ciascuna di queste directory: .devin-outpost-stamps/<session_id> nella directory di lavoro e outpost_stamp nella directory di stato della sessione. Se alla ripresa della sessione manca un file di marcatura, significa che la directory non è stata resa persistente: in tal caso Devin pubblica nella sessione un avviso che la segnala. Una ripresa che parte da una macchina vuota non è adatta alla produzione: la sessione perde i checkout, il lavoro non salvato in un commit e le dipendenze installate. Il tuo orchestratore può monitorare le sessioni riservate e i relativi stati:
Ogni voce riporta un status.session_status con valore 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.