Self-hosted Pool
基于 Cursor 官方 Self-hosted Pool 文档解释企业 worker fleet、service account、pool labels、触发规则、监控和安全边界。
Self-hosted Pool 是企业版 Cloud Agent 的共享 worker fleet，不是个人 My Machines 的批量复制。
阅读目标：读完本章，你应该能判断团队是否需要自托管池，并能设计 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、内网服务访问。
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 中有
agentCLI、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：
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 常驻。
深读：Self-hosted 不等于“完全离线”
Self-hosted Pool 把代码执行、依赖、cache、secrets 和内网访问留在你的基础设施里，但 Cloud Agent 的推理和编排仍然依赖 Cursor cloud。采购、安全评审和法务评审要基于这个真实边界，而不是把它理解成纯本地 agent。
本章自检
- 团队是否真的需要共享 fleet，而不是个人 My Machines？
- Allow / Require Self-Hosted Agents 的策略分别是什么？
- repo、pool 和 custom labels 如何决定 worker 匹配？
- metrics、artifacts、secrets 和 outbound hosts 是否已经纳入上线检查？
通过标准：你能为一个团队写出 Self-hosted Pool 上线 runbook，包含 worker image、service account、pool labels、trigger policy、network allowlist、metrics 和回滚策略。
官方来源
- Cursor Self-Hosted Pool —— 官方 pool 架构、启动、labels、triggers、networking、Kubernetes、fleet API、metrics 和 security。
- Cursor My Machines —— 官方个人 worker 对照。
- Cursor Cloud Agent Security —— 官方安全与网络边界。
- Cursor Service Accounts —— 官方服务账号入口。