> ## 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. # Referencia > Comandos de la CLI, endpoints de fleet API y el contrato de creación del worker Referencia completa del ámbito de Outposts: la CLI del worker, la fleet API, la distribución del binario `devin-remote` y el contrato de creación para orquestadores personalizados.
## Autenticación
Los workers y los orquestadores se autentican con un [token de API v3](/es/api-reference/v3/overview) que pertenece a un usuario de servicio. El rol asignado al usuario de servicio concede al token los ámbitos de Outposts correspondientes: | Permiso del rol | Ámbito del token | Otorga | | ----------------------------------------------------- | ------------------------------- | -------------------------------------------------------- | | **Usar la máquina de outpost** (`UseOutpostsMachine`) | `account.outposts.machine` | Leer la cola y reclamar o liberar sesiones | | **Gestionar Outposts** (`ManageOutpostsOrchestrator`) | `account.outposts.orchestrator` | Crear y eliminar outposts (implica el ámbito de máquina) | Outposts está dentro del ámbito de tu **cuenta** y se comparte entre todas sus organizaciones.
## CLI
### `devin worker start`
Sondea la cola de un outpost, reclama sesiones, descarga el binario `devin-remote` correcto y atiende las sesiones. Ejecútalo desde el directorio que contiene los repositorios clonados de la sesión. ```bash theme={null} devin worker start --outpost= ``` | Flag | Variable de entorno | Descripción | | ---------------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--outpost` | — | Solo acepta sesiones de este outpost. Si se omite en una terminal interactiva, el worker te pedirá que elijas entre los outposts de tu cuenta. | | `--session` (alias `--session-id`) | — | Acepta y atiende una sesión específica, y luego sale. | | `--acceptor-id` | `DEVIN_WORKER_ACCEPTOR_ID` | Identidad estable del worker usada para aceptaciones, renovaciones y recuperación tras reinicios. De forma predeterminada, usa un ID generado que se guarda en el directorio de datos del worker. Nunca compartas uno entre máquinas. | | `--token` | `DEVIN_OUTPOSTS_TOKEN` | Token de autenticación del worker. Si no se configura ninguno de los dos, el comando devuelve un error. | | `--once` | — | Sale después de atender una sesión, en lugar de volver a la cola. | | `--api-url` | `DEVIN_API_URL` | URL base de Devin API. De forma predeterminada, es `https://api.devin.ai`. | | `--cache-dir` | `DEVIN_WORKER_CACHE_DIR` | Directorio donde se almacenan en caché los binarios `devin-remote` descargados. De forma predeterminada, es `~/.devin/worker/cache`. | | `--static-base-url` | `DEVIN_WORKER_STATIC_BASE_URL` | URL base donde se publican los binarios `devin-remote`. | | `--gateway-url` | `DEVIN_OUTPOST_GATEWAY_URL` | URL de respaldo del gateway del outpost cuando la respuesta de aceptación no incluye una. | | `--remote-binary-sha` | `DEVIN_WORKER_REMOTE_SHA` | SHA de Git de respaldo para `devin-remote` cuando la sesión no fija uno. Si no se configura ninguno de los dos, se usa el SHA publicado más reciente. | | `--pty-bridge-port` | `DEVIN_PTY_BRIDGE_PORT` | Puerto fijo del bridge de PTY. De forma predeterminada, se usa un puerto libre asignado por sesión. | | `--poll-interval-secs` | — | Segundos entre los sondeos de la cola y las comprobaciones del estado de la sesión. De forma predeterminada, es `5`. | El Environment del worker también puede incluir `DEVIN_CHROME_PATH` para hacer que las sesiones usen un binario de Chrome/Chromium para las funciones del navegador.
### `devin worker outpost create`
Crea un outpost: una cola de sesiones identificada por un nombre y atendida por tu infraestructura. Requiere el ámbito de orquestador. ```bash theme={null} devin worker outpost create --platform --description "..." ``` | Argumento / flag | Descripción | | ---------------- | ----------------------------------------------------------------- | | `` | Nombre único del outpost (por cuenta), p. ej. `rhel`, `gpu-h200`. | | `--platform` | Plataforma de la máquina: `linux`, `macos` o `windows`. | | `--description` | Descripción legible que se muestra en la aplicación web. | Muestra el ID del nuevo outpost (`outpost_env-...`). También puedes crear outposts en la aplicación web, en **Settings → Environment → Outposts**.
### `devin worker outpost delete`
Elimina un outpost. Requiere el ámbito de orquestador. ```bash theme={null} devin worker outpost delete ```
## Fleet API
Todos los endpoints se encuentran en `https://api.devin.ai/opbeta/outposts/` y usan un Bearer token: ```bash theme={null} curl -H "Authorization: Bearer $DEVIN_API_TOKEN" ... ``` Los recursos siguen una estructura de `metadata` / `spec` / `status` al estilo de Kubernetes, y la cola sigue la semántica de Kubernetes de listar primero y luego observar, con entrega de al menos una vez.
### Objetos
#### Entrada de cola (`devins`)
Cada sesión en cola está representada por una entrada de cola: | Campo | Descripción | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | | `metadata.session_id` | El ID de la sesión (`devin`). | | `metadata.outpost_id` | El outpost en el que la sesión está en cola. | | `metadata.created_at` | Cuándo se puso la sesión en cola (marca de tiempo Unix). | | `metadata.updated_at` | Cuándo cambió este objeto por última vez (marca de tiempo Unix). | | `spec.kind` | `new` o `resume`. | | `spec.platform` | Plataforma de la máquina, p. ej. `linux`. | | `spec.remote_binary_sha` | SHA abreviado del commit del binario `devin-remote` que debe ejecutar el worker; `null` significa usar el predeterminado del worker. | | `spec.network_policy` | La política de red efectiva de la sesión (ver más abajo). | | `status.phase` | Fase de la cola: `pending` o `claimed`. | | `status.acceptor_id` | Worker que actualmente tiene la reclamación, si la hay. | | `status.claim_deadline` | Cuándo vence la reclamación actual y la sesión vuelve a la cola. | | `status.session_status` | Estado general de la sesión subyacente: `pending`, `running`, `suspended` o `terminated`. | | `status.connect_token` | Token de conexión del gateway; solo se devuelve tras una reclamación correcta. | | `status.gateway_url` | URL pública de WebSocket del gateway del outpost; solo se devuelve tras una reclamación correcta. | `spec.network_policy` indica si el acceso de red de la sesión está restringido (`enabled`) y cuáles son los destinos permitidos (`allow`): patrones de hostname con comodines (`{"hostname": ...}`), direcciones/CIDR IPv4 (`{"ipv4": ...}`) o direcciones/CIDR IPv6 (`{"ipv6": ...}`).
#### Outpost
| Campo | Descripción | | ---------------------- | --------------------------------------------------------------------- | | `metadata.outpost_id` | El ID del outpost (`outpost_env-...`). | | `metadata.account_id` | Cuenta a la que pertenece el outpost. | | `metadata.created_at` | Cuándo se creó el outpost (marca de tiempo Unix). | | `spec.name` | Nombre único del outpost (por cuenta). | | `spec.platform` | Plataforma de la máquina; `null` indica la plataforma predeterminada. | | `spec.description` | Descripción legible. | | `status.queue_depth` | Número de sesiones pendientes (aún no reclamadas) en la cola. | | `status.active_claims` | Número de reclamos vigentes en poder de los workers. |
### Listar sesiones en cola
``` GET /opbeta/outposts/devins ``` | Parámetro de consulta | Descripción | | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `outpost` | Filtra por ID de outpost. Se aplica tanto a la operación de listado como a `watch`. | | `phase` | Filtra por la fase de la cola (`pending` o `claimed`). Se ignora al usar `watch`. | | `acceptor_id` | Filtra por el worker que reclamó la sesión. Se ignora al usar `watch`. | | `first` | Número máximo de filas por página en el listado, de 1 a 200. El valor predeterminado es 100. | | `cursor` | Cursor opaco de una respuesta de listado anterior o de un evento de `watch` (ambos son intercambiables). En un listado, devuelve las filas en esta posición o posteriores; en `watch`, reproduce los cambios posteriores antes de transmitir los cambios en vivo. | | `watch` | Transmite cambios como SSE en lugar de listar. | Respuesta de ejemplo: ```json theme={null} { "items": [ { "metadata": { "session_id": "devin-...", "outpost_id": "outpost_env-...", "created_at": 1781050000, "updated_at": 1781050000 }, "spec": { "kind": "new", "platform": "linux", "remote_binary_sha": null }, "status": { "phase": "pending", "acceptor_id": null, "claim_deadline": null, "session_status": "pending" } } ], "cursor": "djE6MTc4MTA1MDAwMC4w", "has_next_page": false, "total": 1 } ``` Semántica de paginación y entrega: * Pasa el `cursor` de cada respuesta a la siguiente solicitud mientras `has_next_page` sea `true`. * La entrega es de al menos una vez: una sesión en el límite entre páginas puede aparecer en ambas, así que actualiza o inserta las entradas por `metadata.session_id` en lugar de tratar cada elemento como nuevo (el CAS de reclamo hace que los duplicados no causen problemas). * Cuando `has_next_page` pase a ser `false`, guarda el cursor devuelto como posición inicial de un watch.
### Detectar cambios
``` GET /opbeta/outposts/devins?watch=true&cursor= ``` Transmite eventos enviados por el servidor. Los eventos `MODIFIED` se emiten cuando cambia la entrada en cola de una sesión (las sesiones que acaban de ponerse en cola también llegan como `MODIFIED`); los eventos `DELETED` se emiten cuando esta se elimina. Cada campo `data` de SSE contiene: ```json theme={null} { "type": "MODIFIED", "object": { "metadata": { "session_id": "devin-...", "outpost_id": "outpost_env-...", "created_at": 1781050000, "updated_at": 1781050100 }, "spec": { "kind": "new", "platform": "linux", "remote_binary_sha": null }, "status": { "phase": "pending", "acceptor_id": null, "claim_deadline": null, "session_status": "pending" } }, "cursor": "djE6MTc4MTA1MDEwMC4w" } ``` Semántica de watch: * Conserva el `cursor` de nivel superior de cada evento después de procesarlo; vuelve a conectarte con el último cursor guardado para reproducir los cambios que ocurrieron mientras estabas desconectado. * La entrega es de al menos una vez; admite eventos duplicados. * Los flujos terminan al cabo de un máximo de cinco minutos; se espera un bucle de watch con reconexión. * Los filtros `phase` y `acceptor_id` se ignoran cuando `watch=true`; filtra los eventos recibidos por watch usando los campos del `object` de cada evento. * Si omites el cursor, se empieza desde el principio, así que usa listar y luego watch para una reconciliación normal.
### Obtener una entrada de la cola
``` GET /opbeta/outposts/devins/{session_id} ``` Devuelve la entrada en la cola correspondiente a una sesión.
### Reclamar una sesión
``` POST /opbeta/outposts/devins/{session_id}/claim ``` ```json theme={null} { "acceptor_id": "worker-1" } ``` Reclama de forma atómica la sesión para la identidad del worker especificada. Si otro worker la reclamó primero, la solicitud falla con `409`. Si el reclamo se realiza correctamente, la respuesta incluye `status.connect_token` y `status.gateway_url`: las credenciales que `devin-remote` necesita para conectarse (consulta el [contrato de creación](#spawn-contract)). Al reclamarla, se garantiza que un worker estará listo dentro del plazo de reclamo asignado por el servidor (`status.claim_deadline`); los reclamos vencidos vuelven a la cola automáticamente.
### Liberar un reclamo
``` POST /opbeta/outposts/devins/{session_id}/release ``` ```json theme={null} { "acceptor_id": "worker-1" } ``` Libera el reclamo del worker para que la sesión vuelva inmediatamente a la cola (p. ej., si falla el aprovisionamiento).
### Outposts
``` GET /opbeta/outposts/outposts # listar outposts POST /opbeta/outposts/outposts # crear un outpost GET /opbeta/outposts/outposts/{outpost_id} # obtener un outpost DELETE /opbeta/outposts/outposts/{outpost_id} # eliminar un outpost ``` Cuerpo de la solicitud para crear: ```json theme={null} { "name": "my-outpost", "platform": "linux", "description": "Dev boxes in our VPC" } ``` Las operaciones de creación, GET y eliminación requieren el ámbito del orquestador; cada respuesta del outpost informa de `status.queue_depth` y `status.active_claims` en tiempo real.
## Distribución remota del binario
El comando `devin worker start` descarga automáticamente el binario `devin-remote` adecuado. Los orquestadores personalizados que no usan Devin CLI pueden obtenerlo directamente de: ``` https://static.devin.ai/devin-rs/remote/ ``` **Identifica la versión más reciente:** ```bash theme={null} # Devuelve el git SHA del binario publicado más reciente para tu plataforma curl -fsSL "https://static.devin.ai/devin-rs/remote/latest_linux_x64" ``` **Descargar y verificar:** ```bash theme={null} SHA=$(curl -fsSL "https://static.devin.ai/devin-rs/remote/latest_linux_x64") # Descargar el binario curl -fL "https://static.devin.ai/devin-rs/remote/devin-remote_${SHA}_linux_x64" \ -o devin-remote # Descargar y verificar el checksum curl -fsSL "https://static.devin.ai/devin-rs/remote/devin-remote_${SHA}_linux_x64.sha256" \ -o devin-remote.sha256 echo "$(cat devin-remote.sha256) devin-remote" | sha256sum -c chmod +x devin-remote ``` **Plataformas disponibles:** | Sufijo | SO / Arquitectura | | ----------------- | ------------------- | | `linux_x64` | Linux x86\_64 | | `macos_arm64` | macOS Apple Silicon | | `windows_x64.exe` | Windows x86\_64 | Si la entrada de la cola de la sesión incluye un `spec.remote_binary_sha`, usa ese SHA en lugar de `latest`; esto fija la sesión a una versión probada específica.
## Contrato de creación
Si tu orquestador inicia `devin-remote` por sí mismo en lugar de usar `devin worker start`, créalo de la siguiente manera: ```bash theme={null} devin-remote serve ``` con las siguientes variables de entorno: | Variable | Obligatoria | Descripción | | ----------------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `DEVIN_OUTPOST_GATEWAY_URL` | Sí | URL base del gateway del outpost, p. ej. `wss://outpost-gateway.devin.ai`. | | `DEVIN_OUTPOST_CONNECT_TOKEN` | Sí | Token Bearer de conexión para el gateway, obtenido de la respuesta al reclamar. | | `DEVIN_OUTPOST_SESSION_ID` | Sí | El ID de sesión que se está atendiendo. Las tres variables `DEVIN_OUTPOST_*` deben configurarse juntas. | | `DEVIN_REMOTE_STATE_DIR` | Muy recomendada | Directorio de estado por sesión donde el remoto almacena sus credenciales, tokens y archivos de integración del shell. Usa un directorio único por sesión (p. ej. `~/.devin/worker/sessions/`, que es lo que usa `devin worker`). Si no se configura, el remoto recurre a un valor predeterminado compartido para todo el sistema (`/opt/.devin` en Linux, `~/.devin` en macOS, `C:\ProgramData\devin` en Windows), que entonces debe existir y tener permisos de escritura, y que expone el estado de cada sesión entre sesiones concurrentes. Configura esto siempre. | | `DEVIN_CHROME_PATH` | Opcional | Ruta a un binario de Chrome/Chromium en la máquina para la herramienta Browser (no hay ningún Chrome gestionado por Devin en Outposts). | | `DEVIN_OUTPOST_DESKTOP` | Opcional | Establécelo en `true` para habilitar la transmisión del escritorio (VNC). En el lado remoto funciona bajo demanda: no se captura nada hasta que se conecta un visor, por lo que es seguro habilitarlo incondicionalmente. | Proporciona al remoto un entorno limpio que contenga solo las variables anteriores más las variables básicas del sistema (`PATH`, `HOME`, `USER`, `LOGNAME`, `TMPDIR`, `LANG`, `TZ` y — para la captura de pantalla de la transmisión del escritorio en Linux/X11 — `DISPLAY`, `WAYLAND_DISPLAY`, `XAUTHORITY`). No expongas al remoto nada que el agente no deba poder ver: el shell del agente lo hereda. Expectativas adicionales del ciclo de vida: * **Directorio de trabajo**: inicia el remoto desde el directorio que contiene los repositorios de la sesión (la misma regla que `devin worker start`). * **Fin de la sesión**: cuando la sesión termina (se suspende o finaliza), Devin notifica al remoto y este sale por sí solo con estado 0. Trata una salida limpia como el fin de la sesión: confirma que `status.session_status` de la entrada de la cola sea `suspended` o `terminated` (la actualización de estado puede retrasarse unos segundos respecto de la salida, así que vuelve a consultarlo unas cuantas veces), luego libera el reclamo. Como fallback, también sondea `status.session_status` mientras el remoto está en ejecución y finaliza el proceso tú mismo una vez que llegue a `terminated` (o desaparezca la entrada de la cola).