---
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="/zh-Hant/docs/cursor/official/04-cloud-agents/55-bugbot" />
  <Card title="Cloud Agent Setup" description="回看環境、secrets、Dockerfile、start 和 update 命令。" href="/zh-Hant/docs/cursor/official/04-cloud-agents/51-setup" />
</Cards>
