> ## 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. # Referência > Comandos da CLI, endpoints da fleet API e o contrato de spawn do worker Referência completa do escopo do Outposts: a CLI do worker, a fleet API, a distribuição do binário `devin-remote` e o contrato de spawn para orquestradores personalizados.
## Autenticação
Workers e orquestradores se autenticam com um [token de API v3](/pt-BR/api-reference/v3/overview) pertencente a um usuário de serviço. A função atribuída ao usuário de serviço concede ao token os escopos do Outposts: | Permissão da função | Escopo do token | Permite | | ----------------------------------------------------- | ------------------------------- | ------------------------------------------------------ | | **Usar máquina do outpost** (`UseOutpostsMachine`) | `account.outposts.machine` | Ler a fila e reivindicar/liberar sessões | | **Gerenciar outposts** (`ManageOutpostsOrchestrator`) | `account.outposts.orchestrator` | Criar e excluir outposts (implica o escopo de máquina) | Os Outposts têm escopo no nível da sua **conta** e são compartilhados entre todas as organizações dela.
## CLI
### `devin worker start`
Consulta a fila de um outpost, reivindica sessões, baixa o binário `devin-remote` correto e executa as sessões. Execute-o a partir do diretório que contém os repositórios da sessão já clonados. ```bash theme={null} devin worker start --outpost= ``` | Flag | Variável de ambiente | Descrição | | ---------------------------------- | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--outpost` | — | Assume somente sessões deste outpost. Se omitido em um terminal interativo, o worker solicita que você escolha um dos outposts da sua conta. | | `--session` (alias `--session-id`) | — | Assume e atende uma sessão específica e, em seguida, encerra. | | `--acceptor-id` | `DEVIN_WORKER_ACCEPTOR_ID` | Identidade estável do worker usada para reivindicações, renovações e recuperação após reinicialização. O padrão é um ID gerado e persistido no diretório de dados do worker. Nunca compartilhe um mesmo ID entre máquinas. | | `--token` | `DEVIN_OUTPOSTS_TOKEN` | Token de autenticação do worker. Se nenhum dos dois estiver definido, o comando falha. | | `--once` | — | Encerra após atender uma sessão em vez de retornar à fila. | | `--api-url` | `DEVIN_API_URL` | Base URL da API do Devin. O padrão é `https://api.devin.ai`. | | `--cache-dir` | `DEVIN_WORKER_CACHE_DIR` | Diretório em que os binários `devin-remote` baixados ficam em cache. O padrão é `~/.devin/worker/cache`. | | `--static-base-url` | `DEVIN_WORKER_STATIC_BASE_URL` | Base URL na qual os binários `devin-remote` são publicados. | | `--gateway-url` | `DEVIN_OUTPOST_GATEWAY_URL` | URL do gateway do outpost usada como fallback quando a resposta da reivindicação não inclui uma. | | `--remote-binary-sha` | `DEVIN_WORKER_REMOTE_SHA` | SHA de fallback do Git para o `devin-remote` quando a sessão não fixa um. Quando nenhum dos dois está definido, o SHA publicado mais recente é usado. | | `--pty-bridge-port` | `DEVIN_PTY_BRIDGE_PORT` | Porta fixa da bridge PTY. O padrão é uma porta livre alocada por sessão. | | `--poll-interval-secs` | — | Segundos entre as consultas à fila e as verificações do status da sessão. O padrão é `5`. | O ambiente do worker também pode incluir `DEVIN_CHROME_PATH` para apontar as sessões para um binário do Chrome/Chromium para recursos do navegador.
### `devin worker outpost create`
Cria um outpost — uma fila nomeada de sessões operada pela sua infraestrutura. Requer o escopo de orquestrador. ```bash theme={null} devin worker outpost create --platform --description "..." ``` | Argumento / flag | Descrição | | ---------------- | ------------------------------------------------------------------- | | `` | Nome exclusivo do outpost na conta, por exemplo `rhel`, `gpu-h200`. | | `--platform` | Plataforma da máquina: `linux`, `macos` ou `windows`. | | `--description` | Descrição exibida no app web. | Exibe o ID do novo outpost (`outpost_env-...`). Você também pode criar outposts no app web em **Configurações → Ambiente → Outposts**.
### `devin worker outpost delete`
Exclui um outpost. Requer o escopo do orquestrador. ```bash theme={null} devin worker outpost delete ```
## Fleet API
Todos os endpoints estão em `https://api.devin.ai/opbeta/outposts/` e usam um token Bearer: ```bash theme={null} curl -H "Authorization: Bearer $DEVIN_API_TOKEN" ... ``` Os recursos seguem uma estrutura no estilo do Kubernetes de `metadata` / `spec` / `status`, e a fila segue a semântica list-then-watch do Kubernetes, com entrega de pelo menos uma vez.
### Objetos
#### Entrada da fila (`devins`)
Cada sessão enfileirada é representada por uma entrada da fila: | Campo | Descrição | | ------------------------ | ----------------------------------------------------------------------------------------------------------- | | `metadata.session_id` | O ID da sessão (devin). | | `metadata.outpost_id` | O outpost em que a sessão está na fila. | | `metadata.created_at` | Quando a sessão foi enfileirada (timestamp Unix). | | `metadata.updated_at` | Quando este objeto foi alterado pela última vez (timestamp Unix). | | `spec.kind` | `new` ou `resume`. | | `spec.platform` | Plataforma da máquina, por exemplo `linux`. | | `spec.remote_binary_sha` | SHA curto do commit do binário `devin-remote` que o worker deve executar; `null` indica o padrão do worker. | | `spec.network_policy` | A política de rede efetiva da sessão (veja abaixo). | | `status.phase` | Fase da fila: `pending` ou `claimed`. | | `status.acceptor_id` | Worker que atualmente mantém a reivindicação, se houver. | | `status.claim_deadline` | Quando a reivindicação atual expira e a sessão retorna à fila. | | `status.session_status` | Status geral da sessão subjacente: `pending`, `running`, `suspended` ou `terminated`. | | `status.connect_token` | Token de conexão do gateway; retornado apenas após uma reivindicação bem-sucedida. | | `status.gateway_url` | URL pública de websocket do gateway do outpost; retornada apenas após uma reivindicação bem-sucedida. | `spec.network_policy` informa se o acesso de rede da sessão está restrito (`enabled`) e quais são os destinos permitidos (`allow`): padrões de hostname (`{"hostname": ...}`), endereços/CIDRs IPv4 (`{"ipv4": ...}`) ou endereços/CIDRs IPv6 (`{"ipv6": ...}`).
#### Outpost
| Campo | Descrição | | ---------------------- | ------------------------------------------------------------ | | `metadata.outpost_id` | O ID do outpost (`outpost_env-...`). | | `metadata.account_id` | Conta à qual o outpost pertence. | | `metadata.created_at` | Quando o outpost foi criado (timestamp Unix). | | `spec.name` | Nome exclusivo do outpost dentro da conta. | | `spec.platform` | Plataforma da máquina; `null` indica a plataforma padrão. | | `spec.description` | Descrição legível por pessoas. | | `status.queue_depth` | Número de sessões pendentes (ainda não assumidas) na fila. | | `status.active_claims` | Número de reivindicações ainda válidas em posse dos workers. |
### Listar sessões enfileiradas
``` GET /opbeta/outposts/devins ``` | Parâmetro de consulta | Descrição | | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `outpost` | Filtra por ID do outpost. Aplica-se tanto à listagem quanto ao monitoramento. | | `phase` | Filtra pela fase da fila (`pending` ou `claimed`). Ignorado no monitoramento. | | `acceptor_id` | Filtra pelo worker que reivindicou a sessão. Ignorado no monitoramento. | | `first` | Número máximo de linhas por página da listagem, de 1 a 200. O padrão é 100. | | `cursor` | Cursor opaco de uma resposta de listagem anterior ou de um evento de monitoramento (ambos são intercambiáveis). Em uma listagem, retorna linhas nessa posição ou após ela; no monitoramento, reproduz as alterações posteriores a ela antes de transmitir as alterações em tempo real. | | `watch` | Transmite alterações como SSE em vez de listar. | Exemplo de resposta: ```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 } ``` Paginação e semântica de entrega: * Passe o `cursor` de cada resposta para a próxima requisição enquanto `has_next_page` for `true`. * A entrega segue a semântica at-least-once: uma sessão na fronteira entre páginas pode aparecer em ambas, então faça upsert das entradas por `metadata.session_id` em vez de tratar cada item como novo (o reivindicar CAS torna duplicatas inofensivas). * Quando `has_next_page` se tornar `false`, salve o cursor retornado como posição inicial de um watch.
### Monitorar alterações
``` GET /opbeta/outposts/devins?watch=true&cursor= ``` Transmite Server-Sent Events. Eventos `MODIFIED` são emitidos quando a entrada da fila de uma sessão é alterada (sessões recém-enfileiradas também são recebidas como `MODIFIED`); eventos `DELETED` são emitidos quando ela é removida. Cada campo `data` de SSE contém: ```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 do watch: * Persista o `cursor` de nível superior de cada evento após processá-lo; reconecte-se com o último cursor persistido para receber novamente as alterações que ocorreram enquanto a conexão estava interrompida. * A entrega ocorre pelo menos uma vez — tolere eventos duplicados. * Os fluxos se encerram em, no máximo, cinco minutos; espera-se um loop de watch com reconexão. * Os filtros `phase` e `acceptor_id` são ignorados quando `watch=true`; filtre os eventos monitorados usando os campos do `object` de cada evento. * Omitir o cursor faz com que o processo comece do início, portanto use `list` seguido de `watch` para a reconciliação normal.
### Buscar uma entrada da fila
``` GET /opbeta/outposts/devins/{session_id} ``` Retorna a entrada da fila de uma sessão.
### Reivindicar uma sessão
``` POST /opbeta/outposts/devins/{session_id}/claim ``` ```json theme={null} { "acceptor_id": "worker-1" } ``` Reivindica a sessão de forma atômica para a identidade de worker fornecida. Se outro worker a reivindicou primeiro, a requisição falha com `409`. Uma resposta de reivindicação bem-sucedida inclui `status.connect_token` e `status.gateway_url` — as credenciais de que o `devin-remote` precisa para se conectar (consulte o [contrato de spawn](#spawn-contract)). Ao reivindicar a sessão, o worker se compromete a ficar pronto dentro do prazo de reivindicação atribuído pelo servidor (`status.claim_deadline`); reivindicações expiradas retornam à fila automaticamente.
### Remover uma reivindicação
``` POST /opbeta/outposts/devins/{session_id}/release ``` ```json theme={null} { "acceptor_id": "worker-1" } ``` Libera a reivindicação do worker para que a sessão volte imediatamente para a fila (por exemplo, em caso de falha no provisionamento).
### Outposts
``` GET /opbeta/outposts/outposts # listar outposts POST /opbeta/outposts/outposts # criar um outpost GET /opbeta/outposts/outposts/{outpost_id} # obter um outpost DELETE /opbeta/outposts/outposts/{outpost_id} # excluir um outpost ``` Corpo da requisição para criação: ```json theme={null} { "name": "my-outpost", "platform": "linux", "description": "Dev boxes in our VPC" } ``` Create, get e delete exigem o escopo de orquestrador; cada resposta de outpost informa `status.queue_depth` e `status.active_claims` em tempo real.
## Distribuição remota de binários
O comando `devin worker start` baixa automaticamente o binário `devin-remote` correto. Orquestradores personalizados que não usam o Devin CLI podem baixá-lo diretamente de: ``` https://static.devin.ai/devin-rs/remote/ ``` **Identifique a versão mais recente:** ```bash theme={null} # Retorna o git SHA do binário publicado mais recente para sua plataforma curl -fsSL "https://static.devin.ai/devin-rs/remote/latest_linux_x64" ``` **Baixar e verificar:** ```bash theme={null} SHA=$(curl -fsSL "https://static.devin.ai/devin-rs/remote/latest_linux_x64") # Baixar o binário curl -fL "https://static.devin.ai/devin-rs/remote/devin-remote_${SHA}_linux_x64" \ -o devin-remote # Baixar e verificar o 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 disponíveis:** | Suffix | SO / Arquitetura | | ----------------- | ------------------- | | `linux_x64` | Linux x86\_64 | | `macos_arm64` | macOS Apple Silicon | | `windows_x64.exe` | Windows x86\_64 | Se a entrada na fila da sessão incluir um `spec.remote_binary_sha`, use esse SHA em vez de `latest` — isso mantém a sessão fixada em uma versão específica testada.
## Contrato de spawn
Se o seu orquestrador iniciar o `devin-remote` por conta própria em vez de usar `devin worker start`, inicie-o assim: ```bash theme={null} devin-remote serve ``` com as seguintes variáveis de ambiente: | Variable | Required | Description | | ----------------------------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `DEVIN_OUTPOST_GATEWAY_URL` | Sim | URL base do gateway do Outpost, por exemplo `wss://outpost-gateway.devin.ai`. | | `DEVIN_OUTPOST_CONNECT_TOKEN` | Sim | Token Bearer de conexão para o gateway, obtido na resposta da reivindicação. | | `DEVIN_OUTPOST_SESSION_ID` | Sim | O ID da sessão atendida. Todas as três variáveis `DEVIN_OUTPOST_*` devem ser definidas em conjunto. | | `DEVIN_REMOTE_STATE_DIR` | Fortemente recomendada | Diretório de estado por sessão em que o remoto armazena credenciais, tokens e arquivos de integração com o Shell. Use um diretório exclusivo para cada sessão (por exemplo, `~/.devin/worker/sessions/`, que é o que `devin worker` usa). Se não for definida, o remoto usa como fallback um padrão compartilhado em todo o sistema (`/opt/.devin` no Linux, `~/.devin` no macOS, `C:\ProgramData\devin` no Windows), que nesse caso deve existir e ser gravável — e que expõe o estado de uma sessão às outras em execuções simultâneas. Sempre defina essa variável. | | `DEVIN_CHROME_PATH` | Opcional | Caminho para um binário do Chrome/Chromium na máquina para a ferramenta Browser (não há Chrome gerenciado pelo Devin no Outposts). | | `DEVIN_OUTPOST_DESKTOP` | Opcional | Defina como `true` para ativar o stream de desktop (VNC). No lado remoto, ele é inicializado sob demanda — nada é capturado até que um visualizador se conecte —, portanto é seguro ativá-lo incondicionalmente. | Forneça ao remoto um ambiente limpo contendo apenas as variáveis acima, além das variáveis básicas do sistema (`PATH`, `HOME`, `USER`, `LOGNAME`, `TMPDIR`, `LANG`, `TZ` e — para a captura de tela do stream de desktop no Linux/X11 — `DISPLAY`, `WAYLAND_DISPLAY`, `XAUTHORITY`). Não exponha ao remoto nada que o agente não deva conseguir ver: esse ambiente é herdado pelo shell do agente. Expectativas adicionais do ciclo de vida: * **Diretório de trabalho**: inicie o remoto a partir do diretório que contém os repositórios da sessão (a mesma regra de `devin worker start`). * **Fim da sessão**: quando a sessão termina (entra em suspensão ou é encerrada), o Devin notifica o remoto e ele encerra por conta própria com status 0. Trate um encerramento limpo como o fim da sessão: confirme que `status.session_status` do item da fila é `suspended` ou `terminated` (a atualização de status pode demorar alguns segundos para refletir o encerramento, então consulte novamente algumas vezes) e, em seguida, libere a reivindicação. Como fallback, também consulte `status.session_status` enquanto o remoto estiver em execução e encerre você mesmo o processo assim que ele atingir `terminated` (ou o item da fila desaparecer).