Referência

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

devin worker start --outpost=<outpost_id>

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.

devin worker outpost create <name> --platform <platform> --description "..."

Argumento / flag	Descrição
`<name>`	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.

devin worker outpost delete <outpost_id>

Fleet API

Todos os endpoints estão em https://api.devin.ai/opbeta/outposts/ e usam um token Bearer:

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:

{
  "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=<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:

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

{ "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). 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

{ "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:

{
  "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:

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

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:

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/<session_id>`, 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).

Introdução

Diretrizes fundamentais

Integração do Devin

Trabalhando com o Devin

Guias do produto

Integrações

Admin

Notas de versão

Autenticação

CLI

`devin worker start`

`devin worker outpost create`

`devin worker outpost delete`

Fleet API

Objetos

Entrada da fila (`devins`)

Outpost

Listar sessões enfileiradas

Monitorar alterações

Buscar uma entrada da fila

Reivindicar uma sessão

Remover uma reivindicação

Outposts

Distribuição remota de binários

Contrato de spawn

​Autenticação

​CLI

​devin worker start

​devin worker outpost create

​devin worker outpost delete

​Fleet API

​Objetos

​Entrada da fila (devins)

​Outpost

​Listar sessões enfileiradas

​Monitorar alterações

​Buscar uma entrada da fila

​Reivindicar uma sessão

​Remover uma reivindicação

​Outposts

​Distribuição remota de binários

​Contrato de spawn

Autenticação

CLI

`devin worker start`

`devin worker outpost create`

`devin worker outpost delete`

Fleet API

Objetos

Entrada da fila (`devins`)

Outpost

Listar sessões enfileiradas

Monitorar alterações

Buscar uma entrada da fila

Reivindicar uma sessão

Remover uma reivindicação

Outposts

Distribuição remota de binários

Contrato de spawn