Saltar al contenido principal
Un orquestador observa la API de Outposts en busca de sesiones en espera en un outpost, aprovisiona una VM o un contenedor para cada una e inicia el worker dentro de él. Esta página describe el bucle de orquestación: sondear la cola, reclamar sesiones, ejecutar workers y desaprovisionar máquinas. Si solo quieres atender sesiones desde una máquina que ya tienes, empieza con la guía de inicio rápido: no necesitas ningún orquestador. Si ejecutas en una plataforma compatible, es posible que una integración ya implemente este bucle por ti. Para ver la referencia completa de la API y la CLI, consulta la referencia.
¿Ejecutas en Kubernetes? devin-outpost-k8s es un operador de código abierto que implementa este bucle por ti: vigila la cola, reclama las sesiones pendientes y ejecuta cada una como un pod de worker en cualquier clúster certificado (GKE, EKS, …). Instálalo con su chart de Helm en lugar de crear tu propio orquestador.

​
El flujo principal

​
1. Registrar un outpost

Un outpost es una cola de sesiones con un nombre específico, atendida por varios workers en tu infraestructura (por ejemplo, rhel, gpu-h200 o my-outpost). Crea uno con devin worker outpost create:
Una vez registrado, el outpost aparece como una opción de máquina en Devin Cloud (junto con Ubuntu, Windows, etc.) al iniciar una sesión. Las sesiones destinadas a él esperan en su cola hasta que un worker las reclame.
En la fleet API, los outposts se representan como recursos outposts, dentro del ámbito de tu cuenta (compartidos entre todas sus organizaciones). Consulta los endpoints de outposts.

​
2. Supervisa la fleet API para ver las sesiones en espera

Tu orquestador lista las sesiones pendientes de los outposts que atiende:
Luego mantiene esta vista actualizada con una suscripción a Server-Sent Events (SSE), que retoma desde el cursor final de la lista:
Este es el patrón estándar de Kubernetes de listar y luego observar: recorre la lista por páginas con el cursor de la respuesta y luego inicia una observación desde donde terminó la lista, guardando el cursor de cada evento para poder reconectarte sin perder cambios. La entrega se realiza al menos una vez, así que haz upsert por metadata.session_id y tolera duplicados. Consulta List queued sessions y Watch for changes para conocer los parámetros de consulta, los formatos de respuesta y la semántica completa de la paginación.

​
3. Reclamar antes del aprovisionamiento

Antes de iniciar una máquina para una sesión, reclámala de forma atómica para que ningún otro worker la tome. Pasa un acceptor_id: una identidad autodeclarada para tu worker:
Las reclamaciones son atómicas: si otro worker reclamó la sesión primero, recibirás un 409. Al reclamar, se garantiza que un worker estará listo dentro del plazo de reclamación asignado por el servidor (status.claim_deadline); las reclamaciones vencidas vuelven a la cola automáticamente. Si el aprovisionamiento falla, libera la reclamación para que la sesión vuelva a la cola de inmediato.

​
4. Crear una máquina y ejecutar el worker

Para cada sesión asignada, aprovisiona una VM o un contenedor a partir de tu imagen. En su interior, ejecuta el worker desde el directorio donde ya estén clonados los repositorios de la sesión:
Pasa el mismo --acceptor-id que usaste para reclamar mediante la API y proporciona el token con --token o DEVIN_OUTPOSTS_TOKEN (consulta la lista completa de flags). El worker se conecta a la nube de Devin, marca la sesión como lista y comienza a ejecutar invocaciones de herramientas.

​
5. Termina la máquina cuando el worker finalice

Cuando devin worker start finalice, la sesión habrá terminado (o se habrá suspendido). Termina la VM o el contenedor. Si tu outpost admite reanudación, crea una instantánea de la máquina antes de terminarla para poder restaurarla si la sesión se reanuda. Tu orquestador puede hacer seguimiento de las sesiones que ha reclamado y de sus estados:
Cada entrada indica un status.session_status de pending, running, suspended o terminated.

​
Programación sin centralización

¿Planeas ejecutar más de ~16 coordinadores (workers u orquestadores que supervisan y reclaman sesiones de un outpost)? Ponte en contacto primero con tu equipo de cuenta: las flotas más grandes aumentan la contención de reclamaciones y la carga de lectura de la cola, y queremos asegurarnos de que el outpost esté aprovisionado para ello.
No necesitas un planificador central para ejecutar una flota. La API de la cola está diseñada para que muchos workers independientes puedan atender el mismo outpost sin comunicarse entre sí:
  • Las reclamaciones son el único mecanismo de coordinación. Cada worker supervisa la cola de forma independiente y compite por reclamar las sesiones pendientes. La reclamación es una operación atómica de compare-and-swap en el servidor: exactamente un worker gana, y cada perdedor recibe un 409 y simplemente pasa a la siguiente sesión pendiente. Perder una carrera por una reclamación es parte del funcionamiento normal, no un error.
  • Cada worker tiene su propia identidad. El acceptor_id restringe las reclamaciones, renovaciones y la recuperación tras reinicio de un worker únicamente a ese worker. devin worker start genera y guarda uno automáticamente por máquina, por lo que una flota no necesita configuración de identidad. Nunca compartas un ID de acceptor (ni un directorio de datos de un worker copiado) entre máquinas: los workers en conflicto se robarán las reclamaciones entre sí.
  • Los fallos se recuperan solos. Si un worker se detiene después de reclamar, su reclamación vence al llegar el plazo de reclamación y la sesión vuelve a la cola para que otro worker la recoja. No hace falta seguimiento de estado a nivel de flota.
Esto significa que escalar horizontalmente consiste simplemente en ejecutar el worker en más máquinas que apunten al mismo outpost: N máquinas atienden N sesiones concurrentes, y el resto quedan en espera como pendientes.

​
Crear un orquestador personalizado

Todo lo que hace devin worker start está disponible directamente a través de la fleet API, por lo que puedes reemplazar por completo la CLI: descarga el binario devin-remote desde la distribución estática de Devin y ejecútalo tú mismo con las variables de entorno documentadas. Consulta Distribución del binario remoto y el spawn contract en la referencia.