Outposts

Outposts 目前处于抢先体验阶段。此处介绍的 API 和 CLI 命令可能会发生变化。如需为你的组织启用 Outposts，请联系你的账户团队。

Outposts 让你可以在自己掌控的基础架构中运行 Devin 会话——无论是你自己的 VM、容器、Kubernetes 集群，还是桌子底下的一台 Mac Mini。Devin 的 agent 循环 (推理和规划) 仍在 Devin 云端运行，而所有命令执行、文件编辑和代码仓库访问都在你管理的机器上完成。如果你有以下需求，请使用 Outposts：

让会话在你的网络内部运行，并靠近内部服务、制品仓库和 secrets
自定义硬件配置 (例如 GPU、大内存机器、特定的操作系统镜像)
使用现有的开发机、VM 或 Kubernetes 基础架构承载 Devin 工作负载
对网络访问、构建产物和监控进行企业级控制

工作原理

Outposts 有两层：

工作器 (例如 devin worker start) —— 这是一个你在某台机器上运行的二进制程序，用于处理单个排队中的会话。它会向 Devin 云端发起出站连接，并在本地执行该会话的工具调用。这个二进制程序由 Cognition 提供；你无需自行实现。Devin CLI 包含获取并执行这个二进制程序的逻辑。
编排器 —— 这是用于监控 fleet API 中等待工作器处理的会话、为每个会话预配一个 VM 或容器并在其中启动工作器的软件。我们为常见平台 (如 Kubernetes) 提供了一些参考实现，但你完全可以按需改造它们 (它们是开源的！) 或自行编写。

工作器只需要出站 HTTPS 访问。不需要入站端口、公网 IP 或 VPN 隧道。当用户在 Devin Cloud 中启动会话并选择你注册的某个 outpost 时，该会话会进入该 outpost 的队列。你的编排器会认领该会话、启动一台机器，并运行工作器。会话结束后，工作器会退出，而你的编排器会销毁这台机器。

先决条件

已启用 Outposts 的组织
具有相应 Outposts 作用域的 v3 API 令牌：
- 供管理 outposts 的编排器使用的 account.outposts.orchestrator (也包含 machine 作用域)
- 供工作器读取队列并认领/释放会话的 account.outposts.machine
一个机器镜像 (VM 或容器) ，并满足以下条件：
- 已安装 Devin CLI
- 具备下方的机器依赖
- 已克隆你的代码仓库，并已配置远程仓库
- 可访问你的会话所需的构建工具、软件包注册表、secrets 和内部服务

机器依赖

会话会直接在你的机器上运行，因此工作器依赖于你在该机器上安装的工具。必填

依赖	用途
`git` (位于 `PATH` 中)	用于克隆及所有代码仓库操作

可选 — 安装以下依赖以启用特定功能：

依赖	功能
`ffmpeg` (位于 `PATH` 中)	Devin 的屏幕录制功能。没有它，会话将无法录制屏幕。
Chrome 或 Chromium	`Browser` 和 computer-use 功能。工作器默认会在标准安装位置查找 Chrome；如需覆盖此设置，请在工作器环境中将 `DEVIN_CHROME_PATH` 设为该二进制程序的绝对路径 (例如 `DEVIN_CHROME_PATH=/usr/bin/google-chrome`) 。没有它，浏览器工具将不可用。
无需密码的 `sudo`	让 Devin 能够在会话期间安装所需软件 (例如缺失的构建工具或系统软件包) 。仅当该机器专用于 Devin 且会在每次会话后回收时才授予此权限——切勿在共享机器或长期运行的机器上授予。

快速入门：创建一个 outpost 并运行工作器

本指南将创建一个 outpost，并在单台机器上使用 devin worker start 为其提供服务——无需编排器。这是在开发机上试用 Outposts 的最快方式，而同一个工作器命令也是编排器在大规模运行时使用的。

1. 创建服务用户令牌

工作器 (以及任何编排器) 使用属于服务用户的 v3 API 令牌向 Outposts API 进行身份验证；下面的角色权限会为该令牌授予 Outposts 作用域 (UseOutpostsMachine → account.outposts.machine，ManageOutpostsOrchestrator → account.outposts.orchestrator) 。在 Devin Web 应用中：

创建角色并授予 Outposts 访问权限。在 Settings → Roles 下，添加一个企业级角色，并在 Outpost permissions 下启用 Use outpost machine (UseOutpostsMachine)。如果该服务用户需要创建或删除 outpost，也请启用 Manage outposts (ManageOutpostsOrchestrator)。
预配服务用户。 在 Settings → Devin API → Service users 下，点击 Provision service user，为其命名 (例如 outposts-worker) ，分配步骤 1 中的角色，并设置过期时间。
复制令牌。 cog_... 令牌只会在创建时显示一次——请立即复制；之后无法再次获取。

将其导出，供下面的命令使用：

export DEVIN_OUTPOSTS_TOKEN="cog_..."

2. 创建一个 outpost

outpost 是一个由你的基础架构提供支持的具名会话队列。你可以在任何已安装 Devin CLI 的机器上创建一个：

devin worker outpost create my-outpost --platform linux --description "Dev boxes in our VPC"

该命令会输出新 outpost 的 ID (outpost_env-...) ——请记下它，供下一步使用。你也可以在 web app 的 Settings → Outposts 中创建 outpost，或通过 outposts API 创建。创建后，启动会话时，outpost 会作为 Devin Cloud 中的一个 machine 选项出现 (与 Ubuntu、Windows 等并列) 。

3. 运行工作器

在将用于提供会话服务的机器上，安装 Devin CLI 和机器依赖，然后在存放你已检出代码仓库的目录中启动工作器：

cd /path/to/repos
devin worker start --outpost=<outpost_id>

工作器会轮询 outpost 的队列，接取第一个待处理的会话，下载正确的 devin-remote 二进制程序，并处理该会话。会话结束后，它会返回队列，等待下一个会话。或者，传入 --once 可在处理完一个会话后退出；传入 --session=<session_id> 可接取并处理某个特定会话。如果 --token 和 DEVIN_OUTPOSTS_TOKEN 都未设置，该命令会报错。如果在交互式终端中省略 --outpost，工作器会提示你从你账户的 outpost 中选择。

4. 在 outpost 上启动会话

在 Devin Cloud 中，启动一个新会话，并选择你的 outpost 作为机器。会话会进入队列，由你的工作器认领，然后在你的机器上开始执行。要并发处理更多会话，请在更多指向同一 outpost 的机器上运行工作器——请参阅去中心化调度。

在 Kubernetes 上运行？开源 devin-outpost-k8s operator 可通过 Helm 安装，并可在任何经过认证的集群 (GKE、EKS、…) 上为 outpost 运行工作器。从该 repo 的克隆副本中运行：

helm install outposts charts/devin-outposts-k8s \
  --set defaultPool.enabled=true \
  --set defaultPool.poolId=<outpost_id> \
  --set defaultPool.token.value="$DEVIN_OUTPOSTS_TOKEN"

核心流程

1. 注册一个outpost

outpost是由你的基础架构中的多个工作器提供支持的具名会话队列 (例如 rhel、gpu-h200 或 my-outpost) 。使用 devin worker outpost create 创建一个outpost：

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

注册后，在启动会话时，该 outpost 会作为 Devin Cloud 中的一种机器选项显示出来 (与 Ubuntu、Windows 等并列) 。以该 outpost 为目标的会话会在其队列中等待，直到被某个工作器认领。

在 fleet API 中，outpost 表示为 outposts 资源，作用域限定在你的账户下 (由该账户中的所有组织共享) 。

2. 轮询 fleet API，查找等待中的会话

你的编排器会列出其负责的 Outposts 中的待处理会话：

curl -H "Authorization: Bearer $DEVIN_API_TOKEN" \
  "https://api.devin.ai/opbeta/outposts/devins?outpost=<outpost_id>&phase=pending"

列表响应会将排队中的会话包含在 items 字段中：

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

使用响应中的 cursor 进行分页，避免反复对整个队列做全量同步。将 first 设为页面大小 (最多 200) ，然后在 has_next_page 为 true 时，将每次响应中的 cursor 传入下一次请求：

curl -H "Authorization: Bearer $DEVIN_API_TOKEN" \
  "https://api.devin.ai/opbeta/outposts/devins?outpost=<outpost_id>&first=200&cursor=<cursor>"

该 API 提供至少一次投递。位于分页边界的会话可能会同时出现在两页中，因此应按 metadata.session_id 对条目执行 upsert，而不是将每一项都视为新条目。当 has_next_page 变为 false 时，将返回的游标保存为 watch API 的起始位置。

监听变更

完成初始列出后，使用最终的游标启动一个 Server-Sent Events (SSE) 监听：

curl -N -H "Authorization: Bearer $DEVIN_API_TOKEN" \
  "https://api.devin.ai/opbeta/outposts/devins?outpost=<outpost_id>&watch=true&cursor=<cursor>"

当会话的队列条目发生变化时，流会发送 MODIFIED 事件；当其被移除时，会发送 DELETED 事件。新进入队列的会话也会以 MODIFIED 事件的形式到达。每个 SSE data 字段都包含如下结构的 JSON：

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

在处理完每个事件后，持久化其顶层 cursor。如果连接关闭，请使用上次持久化的游标重新连接，以重放断开期间发生的任何变更。Watch 投递同样也至少一次，因此客户端必须能够容忍重复事件。流最多持续五分钟；因此预期使用可重连的 watch 循环。 outpost 过滤器同时适用于列表请求和 watch 请求。phase 和 acceptor_id 过滤器仅适用于列表请求，并会在 watch=true 时被忽略；请使用每个事件的 object 中的字段来过滤监视到的事件。省略游标会从头开始，因此常规对账请使用先 list 后 watch 的方式。在为会话启动机器之前，先以原子方式将其认领，以免被其他工作器获取。传入一个 acceptor_id —— 这是你的工作器自报的身份标识：

curl -X POST -H "Authorization: Bearer $DEVIN_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"acceptor_id": "worker-1"}' \
  "https://api.devin.ai/opbeta/outposts/devins/{session_id}/claim"

认领操作是原子的：如果另一个工作器先认领了该会话，你会收到 409。认领后，系统会确保在 server 分配的认领截止时间 (status.claim_deadline) 前有一个工作器就绪；过期的认领会自动返回队列。如果预配失败，请释放该认领，以便会话立即返回队列：

curl -X POST -H "Authorization: Bearer $DEVIN_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"acceptor_id": "worker-1"}' \
  "https://api.devin.ai/opbeta/outposts/devins/{session_id}/release"

3. 启动一台机器并运行工作器

对于每个已认领的会话，基于你的镜像预配一个 VM 或容器。在其中，从已检出该会话代码仓库的目录中运行工作器：

cd /path/to/repos
devin worker start --session=<session_id> --outpost=<outpost_id> --acceptor-id=<worker_id>

会话中的所有代码仓库都必须检出到运行 devin worker start 时所在工作目录的相对路径下：

repos

app

.git

infra

.git

在此示例中，你需要在 repos/ 目录下运行 devin worker start，这样该会话就会将 app/ 和 infra/ 识别为相对于其工作目录的路径。常用标志：

Flag	描述
`--session`	标识要提供服务的会话；该会话结束后，工作器会退出。
`--outpost`	标识要为其提供服务的 Outpost。
`--acceptor-id`	为此工作器使用与 API claim 相同的 acceptor ID。
`--token`	工作器的可选身份验证令牌。如果省略，工作器会使用 `DEVIN_OUTPOSTS_TOKEN`；如果两者都未设置，命令会报错。

示例：

devin worker start --session=<session_id> --outpost=<outpost_id> --acceptor-id=<worker_id> --token="<token>"
DEVIN_OUTPOSTS_TOKEN="<token>" devin worker start --session=<session_id> --outpost=<outpost_id> --acceptor-id=<worker_id>

工作器会主动连接到 Devin 云端，将会话标记为就绪，并开始执行工具调用。

4. 直接获取远程二进制程序

devin worker start 命令会自动下载正确的 devin-remote 二进制程序。如果你构建的是不使用 Devin CLI 的自定义编排器，也可以直接从以下位置获取该二进制程序：

https://static.devin.ai/devin-rs/remote/

确认最新版本：

# 返回适用于你平台的最新已发布二进制程序的 git SHA
curl -fsSL "https://static.devin.ai/devin-rs/remote/latest_linux_x64"

下载并验证：

SHA=$(curl -fsSL "https://static.devin.ai/devin-rs/remote/latest_linux_x64")

# 下载二进制文件
curl -fL "https://static.devin.ai/devin-rs/remote/devin-remote_${SHA}_linux_x64" \
  -o devin-remote

# 下载并验证校验和
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

可用平台：

后缀	操作系统 / 架构
`linux_x64`	Linux x86_64
`macos_arm64`	macOS Apple Silicon
`windows_x64.exe`	Windows x86_64

如果该会话的队列条目包含 spec.remote_binary_sha，请使用该 SHA，而不要使用 latest——这会将该会话固定到某个经过测试的特定版本。

启动约定

如果你的编排器自行启动 devin-remote，请按以下方式启动它：

devin-remote serve

使用以下环境变量：

Variable	Required	Description
`DEVIN_OUTPOST_GATEWAY_URL`	是	Outpost 网关的基础 URL，例如 `wss://outpost-gateway.devin.ai`。
`DEVIN_OUTPOST_CONNECT_TOKEN`	是	网关使用的 Bearer 连接令牌，来自认领响应。
`DEVIN_OUTPOST_SESSION_ID`	是	当前提供服务的会话 ID。这三个 `DEVIN_OUTPOST_*` 变量必须同时设置。
`DEVIN_REMOTE_STATE_DIR`	强烈建议	每个会话的状态目录，remote 会在其中存储其凭据、令牌和 shell 集成文件。请为每个会话使用唯一目录 (例如 `~/.devin/worker/sessions/<session_id>`，这也是 `devin worker` 所使用的目录) 。如果未设置，remote 会回退到共享的系统级默认目录 (Linux 上为 `/opt/.devin`，macOS 上为 `~/.devin`，Windows 上为 `C:\ProgramData\devin`) ；此时该目录必须存在且可写，但也会导致并发会话之间泄露各自的会话状态。务必设置此项。
`DEVIN_CHROME_PATH`	可选	机器上供浏览器工具使用的 Chrome/Chromium 二进制程序路径 (Outposts 上没有 Devin 托管的 Chrome) 。
`DEVIN_OUTPOST_DESKTOP`	可选	设为 `true` 以启用桌面 (VNC) 流。它在 remote 端按需工作——在有查看器连接之前不会捕获任何内容——因此可以放心地始终启用。

为 remote 提供一个干净的环境，只包含上述变量以及基础系统变量 (PATH、HOME、USER、LOGNAME、TMPDIR、LANG、TZ，以及——对于 Linux/X11 上桌面流的屏幕捕获——DISPLAY、WAYLAND_DISPLAY、XAUTHORITY) 。不要将任何 Agent 不应看到的内容泄露给 remote：这些内容会被 Agent 的 shell 继承。额外的生命周期要求：

工作目录：从包含该会话代码仓库的目录启动 remote (与 devin worker start 的规则相同) 。
会话结束：当会话结束 (进入休眠或终止) 时，Devin 会通知 remote，随后它会自行以状态码 0 退出。将正常退出视为会话结束：确认队列条目的 status.session_status 为 suspended 或 terminated (状态更新可能会比退出晚几秒，因此请重新读取几次) ，然后释放认领。作为回退方案，还应在 remote 运行期间轮询 status.session_status，并在其变为 terminated 时 (或队列条目消失时) 自行终止该进程。

5. 在工作器退出时终止机器

当 devin worker start 退出时，该会话即告结束 (或已暂停) 。终止 VM 或容器。如果你的 outpost 支持恢复，请在终止前为机器创建快照，以便在会话恢复时还原。你的编排器可以跟踪其已认领的会话及其状态：

curl -H "Authorization: Bearer $DEVIN_API_TOKEN" \
  "https://api.devin.ai/opbeta/outposts/devins?phase=claimed&acceptor_id=worker-1"

每个条目的 status.session_status 值为 pending、running、suspended 或 terminated。

无需中心化的调度

计划运行超过约 16 个协调器 (从 outpost 中 watch 并认领的工作器或编排器) ？请先联系你的账户团队——更大的集群会加剧认领竞争并增加队列读取负载，我们希望确保该 outpost 已为此完成相应容量配置。

你无需中央调度器也能运行一个工作器集群。队列 API 的设计使多个彼此独立的工作器可以在无需相互通信的情况下为同一个 outpost 提供服务：

认领是唯一的协调原语。 每个工作器都会独立 watch 队列，并竞争认领待处理会话。认领是服务器上的原子 compare-and-swap 操作：最终只会有一个工作器成功，其他所有失败者都会收到 409，然后直接继续处理下一个待处理会话。认领竞争失败是正常情况，不是错误。
每个工作器都有自己的身份标识。 acceptor_id 会将工作器的认领、续期和重启恢复限定在该工作器自身。devin worker start 会为每台 machine 自动生成并持久化一个，因此整个集群无需额外配置身份标识。绝不要在多台 machine 之间共享 acceptor ID (或复制的工作器数据 directory) ——发生冲突的工作器会互相抢走对方的认领。
故障可自行恢复。 如果工作器在认领后宕机，其认领会在认领 deadline 到期时失效，该会话会重新回到队列，由其他工作器接手。无需在集群层面跟踪健康状态。

这意味着，横向扩展只需在更多指向同一 outpost 的 machine 上运行工作器：N 台 machine 可同时处理 N 个并发会话，其余会话则保持待处理状态等待。两点操作说明：

使用 watch 端点，而不是反复完整列出。 先执行一次分页 list 来建立初始状态，然后基于返回的游标保持一个 watch stream。如果每个工作器都重复 poll 整个队列，扩展性会很差，还会增加认领延迟；watch stream 会在变更发生时立即传递更新。
单个 outpost 超过约 16 台 machine 前，请先联系我们。 无协调认领在小规模工作器集群下效果很好，但更大的集群会加剧认领竞争并增加队列读取负载。如果你计划让单个 outpost 接入超过约 16 个工作器，请先联系你的账户团队，以便我们确保该 outpost 已为此完成相应容量配置。

API 参考

所有 Outposts 端点均位于 https://api.devin.ai/opbeta 下，并采用统一的资源结构 (metadata / spec / status) 。列表响应会返回 items、cursor、has_next_page 和 total。

Devins (`/outposts/devins`)

端点	描述
`GET /outposts/devins?outpost=...&phase=pending`	列出等待工作器接收的会话。
`GET /outposts/devins?outpost=...&first=...&cursor=...`	从上一个响应的游标继续分页列表。
`GET /outposts/devins?outpost=...&watch=true&cursor=...`	从列表游标或 watch 游标之后开始流式传输 `MODIFIED` 和 `DELETED` 事件。
`GET /outposts/devins?phase=claimed&acceptor_id=...`	列出由指定 acceptor 认领的会话。
`GET /outposts/devins/{session_id}`	获取单个队列条目。
`POST /outposts/devins/{session_id}/claim`	以原子方式认领会话 (如果已被认领则返回 `409`) 。请求体：`{"acceptor_id": "..."}`。
`POST /outposts/devins/{session_id}/release`	释放认领，将会话放回队列。请求体：`{"acceptor_id": "..."}`。

Outposts (`/outposts`)

端点	描述
`GET /outposts`	列出你账户中的 Outposts。
`POST /outposts`	创建 Outpost。请求体：`{"name": "my-outpost", "platform": "linux", "description": "..."}`。
`GET /outposts/{outpost_id}`	获取单个 Outpost 的信息。
`DELETE /outposts/{outpost_id}`	删除 Outpost (存在活动中的认领时返回 `409`) 。

{
  "metadata": {
    "outpost_id": "outpost_env-...",
    "account_id": "...",
    "created_at": 1781050000
  },
  "spec": {
    "name": "my-outpost",
    "platform": "linux",
    "description": "..."
  },
  "status": {
    "queue_depth": 3,
    "active_claims": 2
  }
}

status.queue_depth 和 status.active_claims 是很有用的自动扩缩容指标：如果队列开始积压，你的编排器可以预配更多预热机器。

工作器s 能做什么

在 Outposts 工作器s 上运行的会话都是功能完整的 Devin 会话：skills、Knowledge、MCP 服务器和 secrets 的工作方式与在 Devin Cloud 中完全一致，通过工作器的连接提供。你的代码仓库、构建缓存和工具执行都保留在你的环境中；而截图等会话产物会上传到 Devin Cloud，方便你在会话中和 PR 中查看。

Outpost 会话有严格的就绪超时时限。在你的编排器认领会话后，工作器必须在认领截止时间前完成连接 — 否则认领将失效，而你仍需为超时窗口期间产生的固定费用和按小时计费的费用付费。

开始使用

核心指南

部署并接入 Devin

与 Devin 协作

产品使用指南

集成

Admin

发布说明

工作原理

先决条件

机器依赖

快速入门：创建一个 outpost 并运行工作器

1. 创建服务用户令牌

2. 创建一个 outpost

3. 运行工作器

4. 在 outpost 上启动会话

核心流程

1. 注册一个outpost

2. 轮询 fleet API，查找等待中的会话

监听变更

3. 启动一台机器并运行工作器

4. 直接获取远程二进制程序

启动约定

5. 在工作器退出时终止机器

无需中心化的调度

API 参考

Devins (`/outposts/devins`)

Outposts (`/outposts`)

工作器s 能做什么

​工作原理

​先决条件

​机器依赖

​快速入门：创建一个 outpost 并运行工作器

​1. 创建服务用户令牌

​2. 创建一个 outpost

​3. 运行工作器

​4. 在 outpost 上启动会话

​核心流程

​1. 注册一个outpost

​2. 轮询 fleet API，查找等待中的会话

​监听变更

​3. 启动一台机器并运行工作器

​4. 直接获取远程二进制程序

​启动约定

​5. 在工作器 退出时终止机器

​无需中心化的调度

​API 参考

​Devins (/outposts/devins)

​Outposts (/outposts)

​工作器s 能做什么

工作原理

先决条件

机器依赖

快速入门：创建一个 outpost 并运行工作器

1. 创建服务用户令牌

2. 创建一个 outpost

3. 运行工作器

4. 在 outpost 上启动会话

核心流程

1. 注册一个outpost

2. 轮询 fleet API，查找等待中的会话

监听变更

3. 启动一台机器并运行工作器

4. 直接获取远程二进制程序

启动约定

5. 在工作器退出时终止机器

无需中心化的调度

API 参考

Devins (`/outposts/devins`)

Outposts (`/outposts`)

工作器s 能做什么