参考 - Devin Docs

Outposts 的完整参考文档：工作器 CLI、fleet API、devin-remote 二进制程序分发，以及适用于自定义编排器的 spawn 约定。

身份验证

工作器和编排器通过属于某个服务用户的 v3 API 令牌进行身份验证。分配给该服务用户的角色决定了该令牌拥有的 Outposts 作用域：

角色权限	令牌作用域	授予
使用 outpost 机器 (`UseOutpostsMachine`)	`account.outposts.machine`	读取队列以及认领/释放会话
管理 Outposts (`ManageOutpostsOrchestrator`)	`account.outposts.orchestrator`	创建和删除 outpost (隐含包含 machine 作用域)

Outposts 以你的账户为作用域，并在该账户下的所有组织之间共享。

CLI

`devin worker start`

轮询 outpost 的队列，认领会话，下载正确的 devin-remote 二进制程序，并处理这些会话。请在包含该会话已检出代码仓库的目录中运行此命令。

devin worker start --outpost=<outpost_id>

标志	环境变量	描述
`--outpost`	—	仅认领来自此 outpost 的会话。如果在交互式终端中省略，工作器会提示你从你账户的 outpost 中选择。
`--session` (alias `--session-id`)	—	认领并处理一个特定会话，然后退出。
`--acceptor-id`	`DEVIN_WORKER_ACCEPTOR_ID`	用于认领、续期和重启恢复的稳定工作器身份。默认值为生成的 ID，并持久保存在工作器数据目录下。切勿在多台机器之间共享同一个 ID。
`--token`	`DEVIN_OUTPOSTS_TOKEN`	工作器的身份验证令牌。如果两者都未设置，该命令会报错。
`--once`	—	处理完一个会话后退出，而不是返回队列。
`--api-url`	`DEVIN_API_URL`	Devin API 基础 URL。默认为 `https://api.devin.ai`。
`--cache-dir`	`DEVIN_WORKER_CACHE_DIR`	用于缓存已下载 `devin-remote` 二进制程序的目录。默认为 `~/.devin/worker/cache`。
`--static-base-url`	`DEVIN_WORKER_STATIC_BASE_URL`	发布 `devin-remote` 二进制程序的基础 URL。
`--gateway-url`	`DEVIN_OUTPOST_GATEWAY_URL`	当认领响应中未提供 outpost 网关 URL 时使用的回退值。
`--remote-binary-sha`	`DEVIN_WORKER_REMOTE_SHA`	当会话未固定 `devin-remote` 的 git SHA 时使用的回退值。如果两者都未设置，则使用最新发布的 SHA。
`--pty-bridge-port`	`DEVIN_PTY_BRIDGE_PORT`	固定的 PTY bridge 端口。默认情况下，每个会话都会分配一个空闲端口。
`--poll-interval-secs`	—	队列轮询和会话状态检查的间隔秒数。默认为 `5`。

工作器环境还可以包含 DEVIN_CHROME_PATH，用于为会话指定 Chrome/Chromium 二进制程序，以启用浏览器功能。

`devin worker outpost create`

创建一个 outpost——即由你的基础架构提供支持的命名会话队列。需要 orchestrator 作用域。

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

参数 / 开关	描述
`<name>`	唯一的 (每个账户内) outpost 名称，例如 `rhel`、`gpu-h200`。
`--platform`	主机平台：`linux`、`macos` 或 `windows`。
`--description`	显示在 Web 应用中的易读描述。

输出新 outpost 的 ID (outpost_env-...)。你也可以在 Web 应用的 设置 → 环境 → Outposts 中创建 outpost。

`devin worker outpost delete`

删除一个 outpost。需要 orchestrator 作用域。

devin worker outpost delete <outpost_id>

Fleet API

所有端点都位于 https://api.devin.ai/opbeta/outposts/ 下，并使用 Bearer 令牌进行认证：

curl -H "Authorization: Bearer $DEVIN_API_TOKEN" ...

资源采用 Kubernetes 风格的 metadata / spec / status 结构，队列则遵循 Kubernetes 的“先列出再监听”语义，并保证至少一次投递。

对象

队列条目 (`devins`)

每个排队中的会话都对应一个队列条目：

字段	说明
`metadata.session_id`	会话 (devin) 的 ID。
`metadata.outpost_id`	会话排队所在的 outpost。
`metadata.created_at`	会话进入队列的时间 (Unix 时间戳) 。
`metadata.updated_at`	此对象上次变更的时间 (Unix 时间戳) 。
`spec.kind`	`new` 或 `resume`。
`spec.platform`	机器平台，例如 `linux`。
`spec.remote_binary_sha`	工作器应运行的 `devin-remote` 二进制程序的短 commit SHA；`null` 表示使用工作器的默认值。
`spec.network_policy`	会话生效的网络策略 (见下文) 。
`status.phase`	队列阶段：`pending` 或 `claimed`。
`status.acceptor_id`	当前持有认领的工作器 (如果已认领) 。
`status.claim_deadline`	当前认领到期、会话返回队列的时间。
`status.session_status`	底层会话的粗略状态：`pending`、`running`、`suspended` 或 `terminated`。
`status.connect_token`	网关连接令牌；仅在认领成功后返回。
`status.gateway_url`	outpost 网关的公共 websocket URL；仅在认领成功后返回。

spec.network_policy 会说明会话的网络访问是否受限 (enabled) ，以及允许访问的目标 (allow) ：主机名 glob 模式 ({"hostname": ...}) 、IPv4 地址/CIDR ({"ipv4": ...}) 或 IPv6 地址/CIDR ({"ipv6": ...}) 。

Outpost

字段	描述
`metadata.outpost_id`	Outpost ID (`outpost_env-...`) 。
`metadata.account_id`	拥有该 Outpost 的账户。
`metadata.created_at`	Outpost 的创建时间 (Unix 时间戳) 。
`spec.name`	Outpost 名称 (在每个账户内唯一) 。
`spec.platform`	机器平台；`null` 表示默认平台。
`spec.description`	便于人类阅读的描述。
`status.queue_depth`	队列中待处理 (未被认领) 的 session 数量。
`status.active_claims`	工作器持有的未过期认领数。

列出排队会话

GET /opbeta/outposts/devins

查询参数	描述
`outpost`	按 outpost ID 过滤。适用于列出和监听。
`phase`	按队列阶段过滤 (`pending` 或 `claimed`) 。监听时会忽略。
`acceptor_id`	按认领会话的工作器过滤。监听时会忽略。
`first`	每页最多返回的行数，范围为 1–200。默认为 100。
`cursor`	来自先前列出响应或监听事件的不透明游标 (两者可互换) 。对于列出，会返回该位置及之后的行；对于监听，会先重放此游标之后的变更，再流式传输实时变更。
`watch`	以 SSE 流式传输变更，而不是列出结果。

示例响应：

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

分页和投递语义：

当 has_next_page 为 true 时，将每个响应中的 cursor 传入下一次请求。
投递采用至少一次语义：处于页面边界的会话可能会同时出现在前后两个页面中，因此应按 metadata.session_id 对条目执行 upsert，而不要将每一项都视为新项 (claim CAS 会让重复项不会造成影响) 。
当 has_next_page 变为 false 时，将返回的游标保存为监听的起始位置。

监听变更

GET /opbeta/outposts/devins?watch=true&cursor=<cursor>

以流方式传输 Server-Sent Events。会话的队列条目发生变化时会触发 MODIFIED 事件 (新排队的会话也会以 MODIFIED 事件形式到达) ；当该条目被移除时会触发 DELETED 事件。每个 SSE 的 data 字段都包含：

{
  "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=true 时，phase 和 acceptor_id 过滤器会被忽略；请根据每个事件 object 中的字段过滤收到的事件。
省略游标会从头开始，因此常规对账应采用“先列出再监听”的方式。

获取队列条目

GET /opbeta/outposts/devins/{session_id}

返回某个会话对应的队列条目。

认领会话

POST /opbeta/outposts/devins/{session_id}/claim

{ "acceptor_id": "worker-1" }

以原子方式为给定的工作器身份认领该会话。如果它已被另一个工作器抢先认领，该请求会返回 409。认领成功后的响应会包含 status.connect_token 和 status.gateway_url —— 也就是 devin-remote 建立连接所需的凭据 (请参阅 spawn 约定) 。认领表示工作器承诺会在服务器分配的认领截止时间 (status.claim_deadline) 内就绪；过期的认领会自动返回队列。

解除认领

POST /opbeta/outposts/devins/{session_id}/release

{ "acceptor_id": "worker-1" }

释放工作器的认领，使会话立即返回队列 (例如，在预配失败时) 。

Outposts

GET    /opbeta/outposts/outposts                 # 列出 outpost
POST   /opbeta/outposts/outposts                 # 创建 outpost
GET    /opbeta/outposts/outposts/{outpost_id}    # 获取 outpost
DELETE /opbeta/outposts/outposts/{outpost_id}    # 删除 outpost

创建请求体：

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

创建、GET 和删除需要 orchestrator 作用域；每个 outpost 响应都会返回实时的 status.queue_depth 和 status.active_claims。

远程二进制程序分发

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

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

Spawn 约定

如果你的编排器不是使用 devin worker start，而是自行启动 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`	强烈建议	每个会话的状态目录，远程端会在其中存储凭据、令牌和 shell 集成文件。每个会话请使用唯一目录 (例如 `~/.devin/worker/sessions/<session_id>`，这也是 `devin worker` 使用的路径) 。如果未设置，远程端会回退到共享的系统级默认目录 (Linux 上为 `/opt/.devin`，macOS 上为 `~/.devin`，Windows 上为 `C:\ProgramData\devin`) ；此时该目录必须存在且可写，并且会导致并发会话之间泄露各自的会话状态。请始终设置此项。
`DEVIN_CHROME_PATH`	可选	机器上供浏览器工具使用的 Chrome/Chromium 二进制程序路径 (Outposts 上没有由 Devin 管理的 Chrome) 。
`DEVIN_OUTPOST_DESKTOP`	可选	设为 `true` 以启用桌面 (VNC) 流。它在远程端按需启用——在有查看器连接之前不会捕获任何内容——因此始终启用也是安全的。

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

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

开始使用

核心指南

部署并接入 Devin

与 Devin 协作

产品使用指南

集成

Admin

发布说明

参考

身份验证

CLI

`devin worker start`

`devin worker outpost create`

`devin worker outpost delete`

Fleet API

对象

队列条目 (`devins`)

Outpost

列出排队会话

监听变更

获取队列条目

认领会话

解除认领

Outposts

远程二进制程序分发

Spawn 约定

​身份验证

​CLI

​devin worker start

​devin worker outpost create

​devin worker outpost delete

​Fleet API

​对象

​队列条目 (devins)

​Outpost

​列出排队会话

​监听变更

​获取队列条目

​认领会话

​解除认领

​Outposts

​远程二进制程序分发

​Spawn 约定

身份验证

CLI

`devin worker start`

`devin worker outpost create`

`devin worker outpost delete`

Fleet API

对象

队列条目 (`devins`)

Outpost

列出排队会话

监听变更

获取队列条目

认领会话

解除认领

Outposts

远程二进制程序分发

Spawn 约定