Referência da API e CLI do Devin Outposts

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
Leitura de Outposts (`ReadOutposts`)	`account.outposts.read`	Listar outposts e ler a fila de sessões
Gravação de Outposts (`WriteOutposts`)	`account.outposts.write`	Reivindicar/liberar sessões e criar/excluir outposts (implica o escopo de leitura)

Os escopos antigos account.outposts.machine e account.outposts.orchestrator estão obsoletos. As funções que receberam esses escopos ainda funcionam (ambos implicam o escopo de gravação), mas novas funções devem usar Leitura de Outposts / Gravação de Outposts.

Os Outposts têm escopo no nível da sua conta e são compartilhados entre todas as organizações dela. devin worker start também pode ser executado sem um token pré-provisionado usando seu login existente na CLI — consulte Iniciar sem um token.

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 em que você deseja que as sessões trabalhem: os repositórios de uma sessão ficam no subdiretório repos desse diretório, portanto o checkout de your-org/app fica em $(pwd)/repos/app. Os repositórios já presentes ali são reutilizados; os ausentes são clonados no início da sessão.

devin worker start --outpost=<outpost_id>

Flag	Variável de ambiente	Descrição
`--outpost`	—	Reivindique somente sessões deste outpost, informado pelo nome ou ID. Se omitido em um terminal interativo, o worker solicita que você escolha um dos outposts da sua conta.
`--session` (alias `--session-id`)	—	Reivindique e atenda uma sessão específica e, em seguida, encerre.
`--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. Opcional — se nenhum dos dois estiver definido, o worker recorre ao seu login da CLI (consulte Iniciar sem um token).
`--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.

Iniciar sem token

Não é necessário um token do Outposts pré-provisionado. Sem --token nem DEVIN_OUTPOSTS_TOKEN, devin worker start cria um outpost usando seu login atual na CLI e reutiliza o token de worker salvo em execuções posteriores.

Validação da plataforma

O worker verifica se o SO da máquina corresponde à plataforma do outpost e falha com uma mensagem clara em caso de incompatibilidade, em vez de reivindicar e liberar repetidamente sessões enfileiradas. Máquinas Windows x64 são compatíveis: o worker baixa o binário devin-remote correto e repassa o ambiente de sistema do Windows às sessões.

`devin worker outpost create`

Cria um outpost — uma fila nomeada de sessões operada pela sua infraestrutura. Requer o escopo de gravação.

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 de gravação.

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": ...}). A política vem do perfil de segurança que rege a sessão; aplicá-la em suas máquinas é responsabilidade do operador do outpost.

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                 # listar outposts
POST   /opbeta/outposts                 # criar um outpost
GET    /opbeta/outposts/{outpost_id}    # obter um outpost
DELETE /opbeta/outposts/{outpost_id}    # excluir um outpost

Corpo da requisição para criação:

{
  "name": "my-outpost",
  "platform": "linux",
  "description": "Dev boxes in our VPC"
}

criar e excluir exigem o escopo de gravação, get e listar exigem o escopo de leitura; cada resposta de outpost informa status.queue_depth e status.active_claims em tempo real.

Enviar uma mensagem do operador

POST /opbeta/outposts/devins/{session_id}/operator-message

{ "message": "Scheduled maintenance: workers restart at 5pm UTC." }

Exibe um banner de Mensagem do Operador do Outpost na sessão de destino, útil para comunicar problemas de infraestrutura ou janelas de manutenção. Requer o escopo de gravação.

curl -X POST "https://api.devin.ai/opbeta/outposts/devins/<session_id>/operator-message" \
  -H "Authorization: Bearer $DEVIN_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message": "Scheduled maintenance: workers restart at 5pm UTC."}'

Comportamento:

Cada chamada substitui a mensagem anterior — a sessão exibe apenas a mais recente.
Enviar uma string vazia ({"message": ""}) limpa o banner.
As mensagens são exibidas como texto simples (até 2.000 caracteres; mensagens mais longas são rejeitadas com um erro de validação 422) — HTML e Markdown não são interpretados.
IDs de sessão desconhecidos, sessões em um outpost de outra conta e sessões concluídas retornam 404.
Limite de taxa de requisições: uma nova mensagem por sessão a cada 30 segundos (429 caso contrário). Limpar com uma string vazia é sempre permitido.

Resposta:

{
  "session_id": "devin-...",
  "message": "Scheduled maintenance: workers restart at 5pm UTC."
}

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
`linux_arm64`	Linux aarch64
`macos_arm64`	macOS Apple Silicon
`windows_x64.exe`	Windows x86_64

Se a entrada da 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	Descrição
`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 em que deseja que a sessão trabalhe — os repositórios ficam no subdiretório repos, isto é, $(pwd)/repos/<repo-name> (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

Referência da API e CLI do Devin Outposts

Autenticação

CLI

`devin worker start`

Iniciar sem token

Validação da plataforma

`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

Enviar uma mensagem do operador

Distribuição remota de binários

Contrato de spawn

​Autenticação

​CLI

​devin worker start

​Iniciar sem token

​Validação da plataforma

​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

​Enviar uma mensagem do operador

​Distribuição remota de binários

​Contrato de spawn

Autenticação

CLI

`devin worker start`

Iniciar sem token

Validação da plataforma

`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

Enviar uma mensagem do operador

Distribuição remota de binários

Contrato de spawn