Pular para o conteúdo principal
Um orquestrador monitora a API do Outposts em busca de sessões aguardando em um outpost, provisiona uma VM ou um contêiner para cada uma e inicia o worker dentro dele. Esta página descreve o loop de orquestração: consultar a fila, reivindicar sessões, executar workers e encerrar as máquinas. Se você só quer processar sessões usando uma máquina que já tem, comece pelo guia de início rápido — nenhum orquestrador é necessário. Se você usa uma plataforma compatível, uma integração talvez já implemente esse loop para você. Para ver toda a superfície da API e da CLI, consulte a referência.
Vai executar no Kubernetes? O devin-outpost-k8s é um operador de código aberto que implementa esse loop para você: ele monitora a fila, reivindica sessões pendentes e executa cada uma como um pod de worker em qualquer cluster certificado (GKE, EKS, …). Instale-o com seu chart Helm em vez de criar seu próprio orquestrador.

​
O fluxo principal

​
1. Registrar um outpost

Um outpost é uma fila nomeada de sessões operada por vários workers na sua infraestrutura (por exemplo, rhel, gpu-h200 ou my-outpost). Crie um com devin worker outpost create:
Depois de registrado, o outpost aparece como uma opção de máquina no Devin Cloud (ao lado de Ubuntu, Windows etc.) ao iniciar uma sessão. As sessões destinadas a ele ficam na fila até que um worker as reivindique.
Na fleet API, os outposts são representados como recursos outposts, no escopo da sua conta (compartilhados entre todas as suas organizações). Consulte os endpoints de outposts.

​
2. Monitore a fleet API em busca de sessões em espera

Seu orquestrador lista as sessões pendentes dos outposts aos quais ele atende:
Em seguida, ele mantém a visualização atualizada com um watch de Server-Sent Events (SSE), retomando a partir do cursor final da lista:
Este é o padrão padrão do Kubernetes de listar e depois acompanhar: percorra a lista em páginas com o cursor da resposta e, em seguida, inicie um acompanhamento a partir de onde a lista terminou, persistindo o cursor de cada evento para que você possa se reconectar sem perder mudanças. A entrega ocorre pelo menos uma vez, então faça upsert por metadata.session_id e tolere duplicatas. Consulte Listar sessões na fila e Acompanhar mudanças para ver os parâmetros de consulta, os formatos de resposta e a semântica completa da paginação.

​
3. Reivindique antes do provisionamento

Antes de iniciar uma máquina para uma sessão, reivindique-a atomicamente para que nenhum outro worker a pegue. Informe um acceptor_id — uma identidade informada pelo próprio worker:
As reivindicações são atômicas: se outro worker reivindicou a sessão primeiro, você recebe um 409. Ao reivindicar, você garante que um worker estará pronto até o prazo de reivindicação atribuído pelo servidor (status.claim_deadline); reivindicações expiradas retornam automaticamente à fila. Se o provisioning falhar, libere a reivindicação para que a sessão retorne à fila imediatamente.

​
4. Inicie uma máquina e execute o worker

Para cada sessão atribuída, provisione uma VM ou contêiner a partir da sua imagem. Dentro dela, execute o worker no diretório em que os repositórios da sessão já estão clonados:
Use o mesmo --acceptor-id que você usou na reivindicação via API e forneça o token por --token ou DEVIN_OUTPOSTS_TOKEN (consulte a lista completa de flags). O worker se conecta à nuvem do Devin, marca a sessão como pronta e começa a executar chamadas de ferramenta.

​
5. Encerre a máquina quando o worker for finalizado

Quando devin worker start é encerrado, a sessão termina (ou é suspensa). Encerre a VM ou o contêiner. Se o seu outpost for retomável, crie um snapshot da máquina antes de encerrá-la para poder restaurá-la se a sessão for retomada. Seu orquestrador pode acompanhar as sessões que reivindicou e seus estados:
Cada entrada apresenta um status.session_status de pending, running, suspended ou terminated.

​
Agendamento sem centralização

Planeja executar mais de ~16 coordenadores (workers ou orquestradores monitorando e reivindicando de um outpost)? Entre em contato primeiro com a equipe responsável pela sua conta — frotas maiores ampliam a contenção de reivindicações e a carga de leitura da fila, e queremos garantir que o outpost esteja provisionado para isso.
Você não precisa de um agendador central para operar uma frota. A API da fila foi projetada para que muitos workers independentes possam atender o mesmo outpost sem se comunicar entre si:
  • As reivindicações são o único mecanismo de coordenação. Cada worker monitora a fila de forma independente e disputa a reivindicação de sessões pendentes. A reivindicação é um compare-and-swap atômico no servidor: exatamente um worker vence, e todos os demais recebem um 409 e simplesmente passam para a próxima sessão pendente. Perder essa disputa de reivindicação é uma condição normal de operação, não um erro.
  • Cada worker tem sua própria identidade. O acceptor_id limita as reivindicações, renovações e a recuperação após reinicialização ao próprio worker. devin worker start gera e persiste um automaticamente por máquina, então uma frota não precisa de configuração de identidade. Nunca compartilhe um ID de acceptor (ou um diretório de dados de worker copiado) entre máquinas — workers em conflito roubarão as reivindicações uns dos outros.
  • As falhas se autorrecuperam. Se um worker parar depois de reivindicar, sua reivindicação expira no prazo de reivindicação e a sessão volta para a fila para que outro worker a assuma. Não é necessário monitoramento de integridade no nível da frota.
Isso significa que escalar horizontalmente é simplesmente executar o worker em mais máquinas apontadas para o mesmo outpost: N máquinas atendem N sessões simultâneas, e o restante aguarda como pendente.

​
Criando um orquestrador personalizado

Tudo o que devin worker start faz está disponível diretamente na fleet API, então você pode substituir totalmente a CLI: faça o download do binário devin-remote da distribuição estática do Devin e inicie-o você mesmo com o ambiente documentado. Consulte Distribuição do binário remoto e o contrato de spawn na referência.