> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devinenterprise.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Outposts

> 在你自己的基础架构上运行 Devin 会话

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

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

如果你有以下需求，请使用 Outposts：

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

<div id="how-it-works">
  ## 工作原理
</div>

Outposts 有两层：

1. **工作器 (例如 `devin worker start`)** —— 这是一个你在某台机器上运行的二进制程序，用于处理单个排队中的会话。它会向 Devin 云端发起出站连接，并在本地执行该会话的工具调用。这个二进制程序由 Cognition 提供；你无需自行实现。[Devin CLI](/zh/work-with-devin/devin-cli) 包含获取并执行这个二进制程序的逻辑。

2. **编排器** —— 这是用于监控 fleet API 中等待工作器处理的会话、为每个会话预配一个 VM 或容器并在其中启动工作器的软件。我们为常见平台 (如 Kubernetes) 提供了一些参考实现，但你完全可以按需改造它们 (它们是开源的！) 或自行编写。

工作器只需要**出站** HTTPS 访问。不需要入站端口、公网 IP 或 VPN 隧道。

当用户在 Devin Cloud 中启动会话并选择你注册的某个 outpost 时，该会话会进入该 outpost 的队列。你的编排器会认领该会话、启动一台机器，并运行工作器。会话结束后，工作器会退出，而你的编排器会销毁这台机器。

<div id="prerequisites">
  ## 先决条件
</div>

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

<div id="machine-dependencies">
  ### 机器依赖
</div>

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

**必填**

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

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

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

<div id="quickstart-create-an-outpost-and-run-a-worker">
  ## 快速入门：创建一个 outpost 并运行工作器
</div>

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

<div id="1-create-a-service-user-token">
  ### 1. 创建服务用户令牌
</div>

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

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

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

```bash theme={null}
export DEVIN_OUTPOSTS_TOKEN="cog_..."
```

<div id="2-create-an-outpost">
  ### 2. 创建一个 outpost
</div>

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

```bash theme={null}
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](#outposts-outposts) 创建。

创建后，启动会话时，outpost 会作为 Devin Cloud 中的一个 machine 选项出现 (与 Ubuntu、Windows 等并列) 。

<div id="3-run-the-worker">
  ### 3. 运行工作器
</div>

在将用于提供会话服务的机器上，安装 [Devin CLI](/zh/cli) 和[机器依赖](#machine-dependencies)，然后在存放你已检出代码仓库的目录中启动工作器：

```bash theme={null}
cd /path/to/repos
devin worker start --outpost=<outpost_id>
```

工作器会轮询 outpost 的队列，接取第一个待处理的会话，下载正确的 `devin-remote` 二进制程序，并处理该会话。会话结束后，它会返回队列，等待下一个会话。或者，传入 `--once` 可在处理完一个会话后退出；传入 `--session=<session_id>` 可接取并处理某个特定会话。

如果 `--token` 和 `DEVIN_OUTPOSTS_TOKEN` 都未设置，该命令会报错。如果在交互式终端中省略 `--outpost`，工作器会提示你从你账户的 outpost 中选择。

<div id="4-start-a-session-on-the-outpost">
  ### 4. 在 outpost 上启动会话
</div>

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

<Note>
  在 Kubernetes 上运行？开源
  [devin-outpost-k8s](https://github.com/CognitionAI/devin-outpost-k8s)
  operator 可通过 Helm 安装，并可在任何经过认证的
  集群 (GKE、EKS、...) 上为 outpost 运行工作器。从该 repo 的克隆副本中运行：

  ```bash theme={null}
  helm install outposts charts/devin-outposts-k8s \
    --set defaultPool.enabled=true \
    --set defaultPool.poolId=<outpost_id> \
    --set defaultPool.token.value="$DEVIN_OUTPOSTS_TOKEN"
  ```
</Note>

<div id="the-core-flow">
  ## 核心流程
</div>

<div id="1-register-an-outpost">
  ### 1. 注册一个outpost
</div>

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

```bash theme={null}
devin worker outpost create <name> --platform <platform> --description "..."
```

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

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

<div id="2-poll-the-fleet-api-for-waiting-sessions">
  ### 2. 轮询 fleet API，查找等待中的会话
</div>

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

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

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

```json theme={null}
{
  "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` 传入下一次请求：

```bash theme={null}
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 的起始位置。

<div id="watch-for-changes">
  #### 监听变更
</div>

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

```bash theme={null}
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：

```json theme={null}
{
  "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` —— 这是你的工作器自报的身份标识：

```bash theme={null}
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`) 前有一个工作器就绪；过期的认领会自动返回队列。如果预配失败，请释放该认领，以便会话立即返回队列：

```bash theme={null}
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"
```

<div id="3-spawn-a-machine-and-run-the-worker">
  ### 3. 启动一台机器并运行工作器
</div>

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

```bash theme={null}
cd /path/to/repos
devin worker start --session=<session_id> --outpost=<outpost_id> --acceptor-id=<worker_id>
```

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

<Tree>
  <Tree.Folder name="repos" defaultOpen>
    <Tree.Folder name="app" defaultOpen>
      <Tree.File name=".git" />
    </Tree.Folder>

    <Tree.Folder name="infra" defaultOpen>
      <Tree.File name=".git" />
    </Tree.Folder>
  </Tree.Folder>
</Tree>

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

常用标志：

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

示例：

```bash theme={null}
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 云端，将会话标记为就绪，并开始执行工具调用。

<div id="4-fetching-the-remote-binary-directly">
  ### 4. 直接获取远程二进制程序
</div>

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

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

**确认最新版本：**

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

**下载并验证：**

```bash theme={null}
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`——这会将该会话固定到某个经过测试的特定版本。

<div id="spawn-contract">
  #### 启动约定
</div>

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

```bash theme={null}
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` 时 (或队列条目消失时) 自行终止该进程。

<div id="5-terminate-the-machine-when-the-worker-exits">
  ### 5. 在工作器 退出时终止机器
</div>

当 `devin worker start` 退出时，该会话即告结束 (或已暂停) 。终止 VM 或容器。如果你的 outpost 支持恢复，请在终止前为机器创建快照，以便在会话恢复时还原。

你的编排器可以跟踪其已认领的会话及其状态：

```bash theme={null}
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`。

<div id="centralization-free-scheduling">
  ## 无需中心化的调度
</div>

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

你无需中央调度器也能运行一个工作器集群。队列 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](#watch-for-changes)。如果每个工作器都重复 poll 整个队列，扩展性会很差，还会增加认领延迟；watch stream 会在变更发生时立即传递更新。
* **单个 outpost 超过约 16 台 machine 前，请先联系我们。** 无协调认领在小规模工作器集群下效果很好，但更大的集群会加剧认领竞争并增加队列读取负载。如果你计划让单个 outpost 接入超过约 16 个工作器，请先联系你的账户团队，以便我们确保该 outpost 已为此完成相应容量配置。

<div id="api-reference">
  ## API 参考
</div>

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

<div id="devins-outpostsdevins">
  ### Devins (`/outposts/devins`)
</div>

| 端点                                                       | 描述                                                         |
| -------------------------------------------------------- | ---------------------------------------------------------- |
| `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": "..."}`。                 |

<div id="outposts-outposts">
  ### Outposts (`/outposts`)
</div>

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

```json theme={null}
{
  "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` 是很有用的自动扩缩容指标：如果队列开始积压，你的编排器可以预配更多预热机器。

<div id="what-workers-can-do">
  ## 工作器s 能做什么
</div>

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

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