Vai al contenuto principale
Outposts è in accesso anticipato. Le API e i comandi CLI descritti qui potrebbero cambiare. Contatta il team del tuo account per abilitare Outposts per la tua organizzazione.
Outposts ti consente di eseguire sessioni Devin all’interno dell’infrastruttura che gestisci — le tue VM, i tuoi container, i tuoi cluster Kubernetes o persino un Mac Mini sotto la tua scrivania. Il loop dell’agente Devin (inferenza e pianificazione) continua a essere eseguito nel cloud di Devin, mentre l’esecuzione dei comandi, le modifiche ai file e l’accesso ai repository avvengono interamente su macchine che gestisci tu. Usa Outposts quando hai bisogno di:
  • Eseguire sessioni all’interno della tua rete, accanto a servizi interni, registries e secrets
  • Profili hardware personalizzati (ad es. GPU, macchine con molta memoria, immagini del sistema operativo specifiche)
  • Un’infrastruttura esistente di dev box, VM o Kubernetes per ospitare i carichi di lavoro di Devin
  • Controlli Enterprise sull’accesso alla rete, sugli output di build e sul monitoraggio

​
Come funziona

Outposts ha due livelli:
  1. Il worker (ad es. devin worker start) — un binario che esegui su una macchina per gestire una singola sessione in coda. Apre una connessione in uscita verso il cloud di Devin ed esegue localmente le chiamate agli strumenti della sessione. Cognition fornisce questo binario; non devi mai implementarlo. Devin CLI contiene la logica per recuperare ed eseguire questo binario.
  2. L’orchestratore — software che monitora la API della flotta per individuare le sessioni in attesa di un worker, effettua il provisioning di una VM o di un container per ciascuna di esse e vi avvia il worker. Forniamo alcune implementazioni di riferimento per piattaforme comuni (come Kubernetes), ma puoi tranquillamente adattarle (sono open source!) oppure scriverne una tua.
I worker richiedono solo accesso HTTPS in uscita. Non sono necessarie porte in ingresso, IP pubblici o tunnel VPN. Quando un utente avvia una sessione in Devin Cloud e seleziona uno dei tuoi Outposts registrati, la sessione viene inserita nella coda di quell’Outpost. Il tuo orchestratore la rivendica, avvia una macchina ed esegue il worker. Quando la sessione termina, il worker si arresta e il tuo orchestratore dismette la macchina.

​
Prerequisiti

  • Un’organizzazione con Outpost abilitato
  • Un token API v3 con gli scope Outpost appropriati:
    • account.outposts.orchestrator per gli orchestratori che gestiscono outpost (include anche lo scope machine)
    • account.outposts.machine per i worker che leggono la coda e rivendicano/rilasciano le sessioni
  • Un’immagine della macchina (VM o container) con:
    • Devin CLI installata
    • Le dipendenze della macchina riportate di seguito
    • I repository clonati, con i remote configurati
    • Accesso ai build tools, ai registry di pacchetti, ai secret e ai servizi interni necessari per le sessioni

​
Dipendenze della macchina

Le sessioni vengono eseguite direttamente sulla tua macchina, quindi il worker dipende dagli strumenti che vi installi. Obbligatorio Opzionale — installa questi strumenti per abilitare funzionalità specifiche:

​
Avvio rapido: creare un outpost e avviare un worker

Questa procedura crea un outpost e lo esegue su una singola machine con devin worker start, senza bisogno di un orchestratore. È il modo più rapido per provare Outposts in un ambiente di sviluppo e lo stesso comando del worker è quello che un orchestratore esegue su larga scala.

​
1. Crea un token utente di servizio

Il worker (e qualsiasi orchestratore) si autentica all’API di Outposts con un token API v3 appartenente a un utente di servizio; le autorizzazioni del ruolo riportate di seguito assegnano al token i relativi ambiti di Outposts (UseOutpostsMachine → account.outposts.machine, ManageOutpostsOrchestrator → account.outposts.orchestrator). Nell’app web di Devin:
  1. Crea un ruolo con accesso a Outposts. In Settings → Roles, aggiungi un ruolo Enterprise e abilita Use outpost machine (UseOutpostsMachine) in Outpost permissions. Abilita anche Manage outposts (ManageOutpostsOrchestrator) se questo utente di servizio dovrà creare o eliminare outpost.
  2. Esegui il provisioning dell’utente di servizio. In Settings → Devin API → Service users, fai clic su Provision service user, assegnagli un nome (ad es. outposts-worker), assegna il ruolo del passaggio 1 e imposta una scadenza.
  3. Copia il token. Il token cog_... viene mostrato una sola volta al momento della creazione: copialo subito, perché non potrai più recuperarlo in seguito.
Esportalo per i comandi seguenti:

​
2. Crea un outpost

Un outpost è una coda di sessioni con nome servita dalla tua infrastruttura. Creane uno da qualsiasi macchina su cui sia installato Devin CLI:
Il comando stampa l’ID del nuovo outpost (outpost_env-...) — annotalo per il passaggio successivo. Puoi anche creare outpost nella web app in Settings → Outposts, oppure tramite l’API degli outpost. Una volta creato, l’outpost compare come opzione macchina in Devin Cloud (insieme a Ubuntu, Windows, ecc.) quando avvii una sessione.

​
3. Avvia il worker

Sulla macchina che ospiterà le sessioni, installa Devin CLI e le dipendenze della macchina, quindi avvia il worker dalla directory che contiene i repository di cui hai già eseguito il checkout:
Il worker interroga la coda dell’outpost, rivendica la prima sessione in attesa, scarica il file binario devin-remote corretto e gestisce la sessione. Quando la sessione termina, torna alla coda e attende la successiva. Passa --once per uscire dopo aver gestito una sola sessione, oppure --session=<session_id> per rivendicare e gestire una sessione specifica. Se sia --token sia DEVIN_OUTPOSTS_TOKEN non sono impostati, il comando genera un errore. Se --outpost viene omesso in un terminale interattivo, il worker ti chiede di scegliere tra gli outpost del tuo account.

​
4. Avvia una sessione sull’outpost

In Devin Cloud, avvia una nuova sessione e seleziona il tuo outpost come macchina. La sessione viene messa in coda, il tuo worker la rivendica e l’esecuzione inizia sulla tua macchina. Per gestire più sessioni contemporaneamente, esegui il worker su più macchine che puntano allo stesso outpost — vedi pianificazione decentralizzata.
Usi Kubernetes? L’operatore open source devin-outpost-k8s si installa tramite Helm ed esegue i worker per un outpost su qualsiasi cluster certificato (GKE, EKS, …). Da un clone di quella repo:

​
Flusso principale

​
1. Registrare un outpost

Un outpost è una coda di sessioni con nome, gestita da molti worker sulla 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 che lo usano restano in attesa nella sua coda finché un worker non le prende in carico.
Nell’API della flotta, gli outpost sono rappresentati come risorse outposts, nell’ambito del tuo account (condivise tra tutte le sue organizzazioni).

​
2. Interroga l’API della flotta per le sessioni in attesa

L’orchestratore elenca le sessioni in sospeso per gli Outposts di cui si occupa:
La risposta dell’elenco racchiude le sessioni in coda in items:
Usa il cursore della risposta per scorrere tra le pagine senza dover riconciliare ripetutamente l’intera coda. Imposta first sulla dimensione della pagina (fino a 200), quindi passa il cursor di ogni risposta nella request successiva finché has_next_page è true:
L’API garantisce una consegna almeno una volta. Una sessione al confine tra due pagine può comparire in entrambe, quindi esegui l’upsert delle voci in base a metadata.session_id anziché considerare ogni elemento come nuovo. Quando has_next_page diventa false, salva il cursore restituito come posizione iniziale per l’API watch.

​
Monitora le modifiche

Dopo l’elenco iniziale, avvia un watch tramite Server-Sent Events (SSE) con il cursore finale:
Il flusso invia eventi MODIFIED quando la voce in coda di una sessione subisce una modifica e eventi DELETED quando viene rimossa. Anche le sessioni appena accodate arrivano come eventi MODIFIED. Ogni campo SSE data contiene JSON con questa struttura:
Salva in modo persistente il cursor di primo livello di ogni evento dopo averlo elaborato. Se la connessione si chiude, riconnettiti con l’ultimo cursore salvato per riprodurre eventuali modifiche avvenute durante la disconnessione. Anche il recapito tramite watch avviene almeno una volta, quindi i client devono tollerare eventi duplicati. Gli stream terminano al massimo dopo cinque minuti; è previsto un ciclo di watch con riconnessione. Il filtro outpost si applica sia alle richieste di elenco sia a quelle di watch. I filtri phase e acceptor_id si applicano solo alle richieste di elenco e vengono ignorati quando watch=true; filtra gli eventi ricevuti tramite watch usando i campi nell’object di ciascun evento. Se ometti il cursore, la lettura parte dall’inizio, quindi usa elenco-poi-watch per la riconciliazione normale. 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, ovvero un’identità dichiarata dal worker stesso:
Le operazioni di rivendicazione sono atomiche: se un altro worker ha rivendicato per primo la sessione, viene restituito un 409. La rivendicazione garantisce che un worker sarà pronto entro la scadenza assegnata dal server (status.claim_deadline); le rivendicazioni scadute tornano automaticamente nella coda. Se il provisioning non va a buon fine, rilascia la rivendicazione in modo che la sessione torni immediatamente nella coda:

​
3. Avvia una macchina ed esegui il worker

Per ogni sessione rivendicata, esegui il provisioning di una VM o di un container a partire dalla tua image. Al suo interno, esegui il worker dalla directory in cui è già stato eseguito il checkout delle repository della sessione:
Tutte le repo della sessione devono essere in checkout in percorsi relativi alla directory di lavoro da cui viene invocato devin worker start:
repos
app
.git
infra
.git
In questo esempio, eseguiresti devin worker start da repos/ e la sessione vede app/ e infra/ rispetto alla propria directory di lavoro. Flag utili: Esempi:
Il worker si collega al cloud di Devin, contrassegna la sessione come pronta e inizia a eseguire le chiamate agli strumenti.

​
4. Scaricare direttamente il binario remoto

Il comando devin worker start scarica automaticamente il binario devin-remote corretto. Se stai creando un orchestratore personalizzato che non utilizza Devin CLI, puoi scaricare il binario direttamente da:
Individua la versione più recente:
Scarica e verifica:
Piattaforme disponibili: Se la voce in coda della sessione include un spec.remote_binary_sha, usa quello SHA invece di latest — così la sessione viene bloccata su una versione specifica testata.

​
Contratto di spawn

Se il tuo orchestratore avvia direttamente devin-remote, avvialo come segue:
con le seguenti variabili d’ambiente: Fornisci al processo remoto un ambiente pulito che contenga solo le variabili sopra, più le variabili di sistema di base (PATH, HOME, USER, LOGNAME, TMPDIR, LANG, TZ e — per la cattura dello schermo del flusso desktop su Linux/X11 — DISPLAY, WAYLAND_DISPLAY, XAUTHORITY). Non esporre al processo remoto nulla che l’agente non dovrebbe poter vedere: viene ereditato dalla shell dell’agente. Ulteriori aspettative del ciclo di vita:
  • Directory di lavoro: avvia il processo remoto dalla directory che contiene le repo della sessione (vale la stessa regola di devin worker start).
  • Fine della sessione: quando la sessione termina (va in sleep o si chiude), Devin avvisa il processo remoto e questo esce autonomamente con status 0. Considera un’uscita pulita come la fine della sessione: conferma che status.session_status della voce della coda sia suspended o terminated (l’aggiornamento dello status può arrivare con qualche secondo di ritardo, quindi rileggilo alcune volte), quindi rilascia la rivendicazione. Come fallback, fai anche il poll di status.session_status mentre il processo remoto è in esecuzione e termina tu stesso il processo quando raggiunge terminated (o quando la voce della coda scompare).

​
5. Terminare la macchina quando il worker si arresta

Quando devin worker start termina, la sessione è conclusa (o è stata sospesa). Termina la VM o il container. Se l’outpost supporta la ripresa, crea uno snapshot della macchina prima di terminarla, così da poterla ripristinare se la sessione riprende. L’orchestratore può tenere traccia delle sessioni rivendicate e del loro stato:
Ogni voce riporta un status.session_status con valore pending, running, suspended o terminated.

​
Pianificazione senza centralizzazione

Prevedi di eseguire più di ~16 coordinatori (worker od orchestratori che osservano e rivendicano sessioni da un outpost)? Contatta prima il team 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.
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 doversi coordinare 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 una contesa per una rivendicazione è normale funzionamento, non un errore.
  • Ogni worker ha una propria identità. acceptor_id limita rivendicazioni, rinnovi e recupero dopo il riavvio al singolo worker. devin worker start ne genera e ne salva automaticamente uno per ogni macchina, quindi una flotta non richiede alcuna configurazione dell’identità. Non condividere mai un acceptor ID (o una copia della directory dei dati del worker) tra più macchine: worker in conflitto si sottrarranno a vicenda le rispettive rivendicazioni.
  • Gli errori si risolvono automaticamente. Se un worker si interrompe dopo aver rivendicato una sessione, la sua rivendicazione scade alla scadenza della rivendicazione e la sessione torna in coda perché un altro worker la prenda in carico. Non è necessario alcun monitoraggio dello stato di salute a livello di flotta.
In pratica, scalare orizzontalmente significa semplicemente eseguire il worker su più macchine puntate allo stesso outpost: N macchine gestiscono N sessioni contemporanee, mentre le altre restano in attesa. Due note operative:
  • Usa l’endpoint watch, non liste complete ripetute. Esegui una lista paginata per costruire lo stato iniziale, poi mantieni un watch stream a partire dal cursore restituito. Ripetere il polling dell’intera coda da ogni worker scala male e aggiunge latenza alle rivendicazioni; il watch stream fornisce le modifiche man mano che avvengono.
  • Parla con noi prima di superare ~16 macchine per outpost. Le rivendicazioni senza coordinamento funzionano bene con flotte di piccole dimensioni, ma flotte più grandi aumentano la contesa sulle rivendicazioni e il carico di lettura della coda. Se prevedi di eseguire più di circa 16 worker su un singolo outpost, contatta prima il team account così potremo assicurarci che l’outpost sia dimensionato adeguatamente.

​
Riferimento API

Tutti gli endpoint di Outposts sono disponibili in https://api.devin.ai/opbeta e condividono una struttura di risorsa comune (metadata / spec / status). Le risposte di elenco restituiscono items, cursor, has_next_page e total.

​
Devins (/outposts/devins)

​
Outposts (/outposts)

status.queue_depth e status.active_claims sono segnali utili per l’autoscaling: se la coda si sta allungando, l’orchestratore può effettuare il provisioning di più macchine già pronte.

​
Cosa possono fare i worker

Le sessioni in esecuzione sui worker Outposts sono sessioni Devin complete: skill, Knowledge, server MCP e secret funzionano tutti allo stesso modo di Devin Cloud, tramite la connessione del worker. Le tue repo, le cache di build e l’esecuzione dei tool restano nel tuo ambiente; gli artefatti della sessione, come gli screenshot, vengono caricati su Devin Cloud così puoi visualizzarli nella sessione e nelle PR.
Le sessioni Outpost hanno timeout di disponibilità rigorosi. Dopo che il tuo orchestratore rivendica una sessione, il worker deve connettersi prima della scadenza della rivendicazione — altrimenti la rivendicazione scade e ti vengono comunque addebitati i costi fissi e orari maturati durante la finestra di timeout.