---
title: "Self-hosted Pool"
description: "基于 Cursor 官方 Self-hosted Pool 文档解释企业 worker fleet、service account、pool labels、触发规则、监控和安全边界。"
verifiedAt: "2026-05-09"
---

Self-hosted Pool 是企业版 Cloud Agent 的共享 worker fleet，不是个人 My Machines 的批量复制。

> [!NOTE]
> **阅读目标**：读完本章，你应该能判断团队是否需要自托管池，并能设计 worker pool 的认证、标签、网络、监控和触发规则。

## 1. 什么时候需要 pool

个人机器适合单人 devbox。Self-hosted Pool 适合组织统一管理 Cloud Agent 执行环境。

| 需求 | 选择 |
| --- | --- |
| 单人复用自己的 laptop / devbox | My Machines |
| 团队共享容量、统一镜像和统一网络出口 | Self-hosted Pool |
| 需要 Kubernetes、autoscaling 或 fleet management | Self-hosted Pool |
| 需要按 team、repo、env、GPU 等标签路由 | Self-hosted Pool |
| 需要服务账号认证和企业管理员控制 | Self-hosted Pool |

官方当前说明里，Self-hosted Cloud Agents 支持每个用户最多 10 个 worker、每个团队最多 50 个 worker。更大规模部署需要联系 Cursor。

## 2. 架构边界

worker 从公司基础设施向 Cursor cloud 建立长期 outbound HTTPS 连接。推理和编排仍在 Cursor 云端，实际 tool calls 在你的 worker 上执行：终端命令、文件修改、browser actions、内网服务访问。

```mermaid
flowchart TD
  Dashboard["Cloud Agents dashboard / Slack / GitHub / Linear / API"] --> Resolver["Cursor worker resolver"]
  Resolver --> Labels["repo + pool + custom labels"]
  Labels --> Worker["Self-hosted worker in company infra"]
  Worker --> Repo["Repo checkout and build cache"]
  Worker --> Private["Internal services / registries / secrets"]
  Worker --> Result["PR / artifacts / dashboard / metrics"]
```

关键边界：

- 不需要 inbound ports、public IP 或 VPN tunnel。
- repo、build cache、secrets 和工具执行留在公司环境。
- model 推理需要读取任务相关 file chunks。
- screenshots、videos 和 log references 这类 artifacts 会上传到 Cursor-managed storage，方便 PR 和 dashboard 展示。

## 3. 前置条件

上线前至少准备：

- Cursor Enterprise plan。
- 团队管理员在 Cloud Agents dashboard 配置 Self-hosted settings。
- **Allow Self-Hosted Agents**：允许用户按需选择自托管 worker。
- **Require Self-Hosted Agents**：强制 Cloud Agent run 走自托管 worker。
- service account API key。
- worker machine 或 image 中有 `agent` CLI、`git`、目标 repo checkout、依赖工具、package registries、secrets 和内网访问能力。

Pool worker 必须使用 service account API key。个人、团队或组织普通 API key 不能启动 pool worker。

## 4. 启动 worker

常用命令：

| 动作 | 命令 |
| --- | --- |
| 安装 CLI | `curl https://cursor.com/install -fsS \| bash` |
| 检查 CLI | `agent --version` |
| 设置服务账号 key | `export CURSOR_API_KEY="service-account-api-key"` |
| 在 repo 下启动 pool worker | `agent worker start --pool` |
| 完成后空闲释放 | `agent worker start --pool --idle-release-timeout 600` |
| 指定 pool name | `agent worker start --pool --pool-name gpu` |
| 从环境设置 pool | `CURSOR_WORKER_POOL_NAME=gpu agent worker start --pool` |

`--idle-release-timeout` 适合编排环境：session 结束后保留一段时间等待 follow-up，超时后 CLI 以 code 0 退出，方便调度器回收。

`--pool-name` 会给 worker 增加 `pool=<name>` label。没指定时进入 `default` pool。老版本 worker 也会匹配 default pool，便于渐进迁移。

## 5. Labels 和路由

Self-hosted Pool 的调度核心是 labels。每个 pool request 至少包含 `repo=<owner/repo>`；指定 pool 时还包含 `pool=<name>`。

你可以用 CLI 直接加 label：

```bash
agent worker start --pool \
  --label team=backend \
  --label env=production
```

生产环境更适合把 labels 放到 JSON 或 TOML 文件，再用 `--labels-file` 或 `CURSOR_WORKER_LABELS_FILE` 注入。

保留 label 不要手动设置：

| Label | 来源 |
| --- | --- |
| `repo` | worker 启动目录的 git remote |
| `pool` | `--pool-name` 或默认 `default` |

## 6. 触发规则

团队成员可以从 dashboard 选择 pool，也可以在集成入口写 self-hosted hints。

| 入口 | 写法 |
| --- | --- |
| Slack | `@Cursor self_hosted=true ...`、`self_hosted`、`selfhosted`、`pool=<name>` |
| GitHub | `@cursoragent self_hosted=true ...` 或 `@cursoragent pool=<name> ...` |
| Linear | issue body 写 `pool=<name>` 或 `[pool=<name>]`，也可用 parent label `pool` + child label |
| API | 使用 `usePrivateWorker` 和 `labels` 字段 |

策略处理要分入口看：

- Slack：Allow 关闭时拒绝自托管 opt-in；Require 打开时所有 Slack mention 都走自托管。
- GitHub：repo `OWNER` 和 `COLLABORATOR` 可以路由到 self-hosted；其他评论者在 public repo 中会受保护逻辑限制。
- Linear：Allow 关闭时显式 self-hosted request 会被拒绝，并在 issue 活动中提示管理员调整。

要按个人机器名路由，不要用 `pool=`，用 My Machines 的 `worker=` 或 `machine=`。

## 7. Hooks、MCP 和 artifacts

Self-hosted workers 会运行 repo 中的 `.cursor/hooks.json`。Enterprise 还支持 team hooks 和 enterprise-managed hooks。

MCP transport 路由：

| Transport | 运行位置 | 边界 |
| --- | --- | --- |
| Command / stdio | worker | 可访问内网 API、本地代理、私有服务 |
| HTTP / SSE URL | Cursor backend | Cursor 处理 OAuth、session cache 和 HTTP 连接 |

artifacts 默认开启。worker 在本地生成 artifacts，再上传到 Cursor-managed storage。如果阻断 `cloud-agent-artifacts.s3.us-east-1.amazonaws.com`，session 继续，但截图、视频、PR embeds 和通知附件可能缺失。

## 8. 网络、监控和扩容

worker 需要 outbound HTTPS：

| Host | 用途 |
| --- | --- |
| `api2.cursor.sh` | agent session |
| `api2direct.cursor.sh` | agent session |
| `cloud-agent-artifacts.s3.us-east-1.amazonaws.com` | artifacts |

Kubernetes 场景使用官方 Helm chart 和 operator。非 Kubernetes 场景可用 fleet management API 查看 worker 列表、summary 和单个 worker 状态。

启动 worker 时加 `--management-addr ":8080"` 后，会暴露：

| Endpoint | 用途 |
| --- | --- |
| `/healthz` | 健康检查 |
| `/readyz` | readiness 检查 |
| `/metrics` | Prometheus metrics |

关键 metrics 包括连接状态、session active 状态、last activity、connect attempts、retry 次数和 session end reasons。

## 9. 安全验收

商业级上线前至少检查：

- 是否只使用 service account API key 启动 pool worker。
- 是否能解释每个 pool / label 的用途。
- 是否把 worker image、secrets、registry 和内网权限限制到必要范围。
- 是否清楚 file chunks 与 artifacts 哪些会离开公司网络。
- 是否关闭或限制包含敏感信息的 artifacts 上传。
- 是否有 `/metrics`、日志和 worker summary 用于容量判断。
- 是否有 idle release 或 autoscaling 策略，避免空闲 worker 常驻。

<details>
<summary>深读：Self-hosted 不等于“完全离线”</summary>

Self-hosted Pool 把代码执行、依赖、cache、secrets 和内网访问留在你的基础设施里，但 Cloud Agent 的推理和编排仍然依赖 Cursor cloud。采购、安全评审和法务评审要基于这个真实边界，而不是把它理解成纯本地 agent。
</details>

## 本章自检

1. 团队是否真的需要共享 fleet，而不是个人 My Machines？
2. Allow / Require Self-Hosted Agents 的策略分别是什么？
3. repo、pool 和 custom labels 如何决定 worker 匹配？
4. metrics、artifacts、secrets 和 outbound hosts 是否已经纳入上线检查？

通过标准：你能为一个团队写出 Self-hosted Pool 上线 runbook，包含 worker image、service account、pool labels、trigger policy、network allowlist、metrics 和回滚策略。

## 官方来源

- [Cursor Self-Hosted Pool](https://cursor.com/docs/cloud-agent/self-hosted-pool.md) —— 官方 pool 架构、启动、labels、triggers、networking、Kubernetes、fleet API、metrics 和 security。
- [Cursor My Machines](https://cursor.com/docs/cloud-agent/my-machines.md) —— 官方个人 worker 对照。
- [Cursor Cloud Agent Security](https://cursor.com/docs/cloud-agent/security-network.md) —— 官方安全与网络边界。
- [Cursor Service Accounts](https://cursor.com/docs/account/enterprise/service-accounts.md) —— 官方服务账号入口。

## 接下来去哪

<Cards>
  <Card title="Bugbot" description="继续学习自动 PR review、rules、autofix 和团队配置。" href="/docs/cursor/official/04-cloud-agents/55-bugbot" />
  <Card title="Cloud Agent Setup" description="回看环境、secrets、Dockerfile、start 和 update 命令。" href="/docs/cursor/official/04-cloud-agents/51-setup" />
</Cards>
