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

# Orquestación

> Aprovisiona máquinas y ejecuta workers automáticamente a medida que las sesiones se ponen en cola

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](/es/cloud/outposts/quickstart): no necesitas ningún orquestador. Si ejecutas en una plataforma compatible, es posible que una [integración](/es/cloud/outposts/overview#integrations) ya implemente este bucle por ti. Para ver la referencia completa de la API y la CLI, consulta la [referencia](/es/cloud/outposts/reference).

<Note>
  ¿Ejecutas en Kubernetes? [devin-outpost-k8s](https://github.com/CognitionAI/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.
</Note>

<div id="the-core-flow">
  ## El flujo principal
</div>

<div id="1-register-an-outpost">
  ### 1. Registrar un outpost
</div>

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

```bash theme={null}
devin worker outpost create <name> --platform <platform> --description "..."
```

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.

<Note>
  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](/es/cloud/outposts/reference#outposts).
</Note>

<div id="2-watch-the-fleet-api-for-waiting-sessions">
  ### 2. Supervisa la fleet API para ver las sesiones en espera
</div>

Tu orquestador lista las sesiones pendientes de los outposts que atiende:

```bash theme={null}
curl -H "Authorization: Bearer $DEVIN_API_TOKEN" \
  "https://api.devin.ai/opbeta/outposts/devins?outpost=<outpost_id>&phase=pending"
```

Luego mantiene esta vista actualizada con una suscripción a Server-Sent Events (SSE), que retoma desde el cursor final de la lista:

```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>"
```

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](/es/cloud/outposts/reference#list-queued-sessions) y [Watch for changes](/es/cloud/outposts/reference#watch-for-changes) para conocer los parámetros de consulta, los formatos de respuesta y la semántica completa de la paginación.

<div id="3-claim-before-provisioning">
  ### 3. Reclamar antes del aprovisionamiento
</div>

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:

```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"
```

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](/es/cloud/outposts/reference#release-a-claim) para que la sesión vuelva a la cola de inmediato.

<div id="4-spawn-a-machine-and-run-the-worker">
  ### 4. Crear una máquina y ejecutar el worker
</div>

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:

```bash theme={null}
cd /path/to/repos
devin worker start --session=<session_id> --outpost=<outpost_id> --acceptor-id=<worker_id>
```

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](/es/cloud/outposts/reference#devin-worker-start)). El worker se conecta a la nube de Devin, marca la sesión como lista y comienza a ejecutar invocaciones de herramientas.

<div id="5-terminate-the-machine-when-the-worker-exits">
  ### 5. Termina la máquina cuando el worker finalice
</div>

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:

```bash theme={null}
curl -H "Authorization: Bearer $DEVIN_API_TOKEN" \
  "https://api.devin.ai/opbeta/outposts/devins?phase=claimed&acceptor_id=worker-1"
```

Cada entrada indica un `status.session_status` de `pending`, `running`, `suspended` o `terminated`.

<div id="centralization-free-scheduling">
  ## Programación sin centralización
</div>

<Note>
  ¿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.
</Note>

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.

<div id="building-a-custom-orchestrator">
  ## Crear un orquestador personalizado
</div>

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](/es/cloud/outposts/reference#remote-binary-distribution) y el [spawn contract](/es/cloud/outposts/reference#spawn-contract) en la referencia.