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 —— 官方服務賬號入口。