《Cursor文檔》-團隊用量池

用量池是一個具名的路由目標，用於將請求與 自託管機器 worker 連接起來。請求會在用量池中等待，直到有可用的 worker 認領。可爲不同的執行環境創建各自的用量池，例如爲需要 GPU 的工作創建 gpu，爲需要 Mac 的工作創建 ios。

團隊用量池適用於希望讓雲端代理運行在公司自有基礎設施中的企業版團隊。管理員無需讓每位開發者都在個人機器上啓動一個 worker，而是統一運營一個 worker 用量池，供整個組織內的智能體分配使用。

用量池是一種基礎設施歸屬方式，不會將智能體循環移出 Cursor 雲。worker 會在你的基礎設施中執行終端命令、文件編輯、瀏覽器操作和其他工具調用，而 Cursor 負責協調、模型訪問以及雲端代理體驗。

對大多數團隊來說，Cursor-managed Cloud Agents 都是推薦方案，包括需要
私有網絡訪問的團隊。在決定自行維護 worker 工作器羣 之前，請先考慮使用具備網絡
控制的託管環境、Tailscale 或類似客戶端，或針對受支持源代碼控制方式的私有網絡連接。請參閱 選擇 Cloud Agents 的運行位置。

當你有以下需求時，請使用用量池：

• 爲團隊或組織集中管理 worker
• 使用服務賬號身份驗證，而不是個人瀏覽器登錄
• 需要 Kubernetes、自動擴縮容或集中管理的容量
• 使用標籤將工作路由到正確的環境、團隊、倉庫或硬件配置
• 使用公司自有主機執行工具調用、生成構建產物，並記錄 worker 日誌和進行監控

如需快速完成個人配置，請參閱 我的機器。有關用量池所需的套餐、憑據、儀表盤設置和機器依賴項，請參閱自託管機器概覽中的 要求。

工作原理¶

worker 會向 Cursor 雲建立一個長期保持的出站 HTTPS 連接。智能體循環 (包括推理和規劃) 在 Cursor 雲中運行，並通過該連接發送工具調用。worker 會在你的基礎設施中執行這些工具調用：終端命令、文件編輯、瀏覽器操作，以及對內部服務的訪問。

你的倉庫、構建緩存、機密信息和工具執行都會保留在你的環境中，而 Cursor 負責協調、模型訪問以及雲端代理體驗。雲端代理的產物 (如截圖和視頻) 會上傳到 Cursor，以便你在 PR 和儀表盤中查看。

worker 只需要出站訪問。無需入站端口、公共 IP 或 VPN 隧道。所需主機的完整列表，請參閱網絡。

自託管機器支持每位用戶最多 200 個 worker、每個團隊最多 1000 個。若需更大規模的公司級部署，請聯繫我們討論伸縮方案。

前提條件¶

• 已開通 Cursor 企業版方案
• 由團隊管理員在 Cloud Agents 儀表盤 中配置自託管設置：
• 允許自託管機器 允許用戶啓用自託管運行。
• 要求自託管機器 會將每次 Cloud Agent 運行都路由到自託管 worker。
• 用於用量池 worker 身份驗證的 服務賬戶 API 密鑰
• 滿足以下條件的 worker 機器或鏡像：
• 已安裝 agent 命令行界面
• 已安裝 git，且可在 PATH 中使用 (當 worker 需要處理 git remote 或使用 --clone-git-repos 時爲必需；若由你自己的腳本處理 SCM，則對 任意代碼倉庫用量池 而言爲可選)
• 一個 workspace 目錄 (已克隆並配置了 remote 的代碼倉庫，或一個 any-repo 目錄)
• 可訪問智能體所需的構建工具、包註冊表、機密信息和內部服務

安裝命令行界面¶

# macOS、Linux 和 WSL
curl https://cursor.com/install -fsS | bash

# Windows PowerShell
irm 'https://cursor.com/install?win32=true' | iex

確認 CLI 可用：

agent --version

worker 身份認證¶

用量池 worker 必須使用 服務賬戶 API 密鑰 進行認證。

用戶、個人、團隊和組織 API 密鑰都不能啓動用量池 worker。個人 worker 請在 我的機器 中使用個人或用戶 API 密鑰。

export CURSOR_API_KEY="your-service-account-api-key"

也可以直接傳入密鑰：

agent worker --api-key "your-service-account-api-key" start

啓動一個用量池 worker¶

在其要服務的 workspace 中運行該 worker (可以是 git 倉庫 root，或一個 any-repo 目錄)：

cd /path/to/repo
agent worker --pool start

--pool 會將 worker 註冊爲可供用量池分配。可傳入一個可選名稱以加入具名用量池 (例如 --pool gpu)。省略名稱時，worker 會加入 default。每個雲端代理會話一次只會佔用一個 worker。

對於編排環境，請將其與 --idle-release-timeout 結合使用，以便進程在工作完成後正常退出：

agent worker --pool gpu --idle-release-timeout 600 start

--idle-release-timeout 會在會話結束後的一段時間內 (以秒爲單位) 讓 worker 繼續保持運行，以處理後續消息。默認值爲 3600 秒。有關釋放與重新連接的工作方式，請參閱會話生命週期。

啓用計算機使用¶

傳入 --computer-use，讓已認領的 agents 可以在 worker 上進行點擊、輸入、截屏以及操作應用：

agent worker --pool gpu --computer-use start

在 macOS 上，首次啓動會安裝 Cursor Computer Use 輔助應用。爲其授予輔助功能和屏幕錄製權限，用一個截屏任務進行驗證，然後爲該機器創建快照，這樣從該鏡像恢復的每個 worker 都可直接使用。在 Linux 上，請將桌面端軟件包打包進 worker 鏡像。macOS 權限步驟、MDM 配置文件指南以及 Linux 顯示選項，參見計算機使用與桌面共享。

註冊多個倉庫根目錄¶

自託管多倉庫支持可在 worker 啓動時通過註冊多個工作區根目錄進行配置。爲每個本地倉庫根目錄各傳遞一次 --worker-dir。第一個根目錄會作爲主代碼倉庫，用於分配標識和儀表盤顯示。所有根目錄都會暴露給智能體運行時，而具有有效 git origin 的根目錄會註冊代碼倉庫路由元數據。

--worker-dir`` 最多可重複指定 20 個路徑。每個路徑都必須已存在且爲目錄。如果未傳遞–worker-dir`，CLI 會使用當前工作目錄。

開始前，請先在 Dashboard > Cloud Agents > Self-Hosted 中啓用自託管 workers。除非你自己的機器鏡像能保證其他可寫位置，否則請使用 $HOME 下的可寫路徑。

示例設置：

export WORKER_ROOT="$HOME/cursor-repos/my-org"
mkdir -p "$WORKER_ROOT"

git clone git@github.com:my-org/app.git "$WORKER_ROOT/app"
git clone git@github.com:my-org/infra.git "$WORKER_ROOT/infra"

export CURSOR_API_KEY="<key>"

啓動 worker 前，先運行預檢：

agent worker \
  --pool app-infra \
  --name app-infra-worker \
  --worker-dir "$WORKER_ROOT/app" \
  --worker-dir "$WORKER_ROOT/infra" \
  debug --json

使用相同根目錄啓動 worker：

agent worker \
  --pool app-infra \
  --name app-infra-worker \
  --worker-dir "$WORKER_ROOT/app" \
  --worker-dir "$WORKER_ROOT/infra" \
  start --verbose

將 worker 選項放在 start 或 debug 之前。讓該進程在 systemd、tmux、launchd、Kubernetes 或你自己的進程管理器等監管程序下持續運行。

詳細的啓動日誌是判斷已註冊根目錄的權威依據。成功的 multi-repo worker 會顯示每個派生倉庫的標籤、工作區路徑以及代碼倉庫 URL：

repo=my-org/app
repo=my-org/infra
workspacePaths: [app, infra]
x-repository-urls: ["git@github.com:my-org/app.git","git@github.com:my-org/infra.git"]

儀表盤當前會在其主倉庫下顯示一個自託管 worker。
門戶中目前還沒有具名的自託管多倉庫環境對象。
這可能會讓人覺得只有第一個倉庫已註冊。請檢查詳細日誌中的 workspacePaths
和 x-repository-urls 以確認所有根目錄。若要讓另一個
倉庫成爲主倉庫，請將它的 --worker-dir 放在最前面。

使用 --name 和 --pool <name>，讓多倉庫 worker 在儀表盤和觸發器中更容易識別。

在用量池模式下，一次只有一個雲端代理會佔用該 worker。不使用 --pool 時，則允許共享分配。需要爲編排器提供 /healthz、/readyz 和 /metrics 時，請在 start 前添加 --management-addr 0.0.0.0:8080。

非 git 目錄也可以作爲執行根目錄，但它們不會提供倉庫路由元數據。智能體所需的所有倉庫都必須在進程啓動前完成克隆，且 worker 能夠訪問。worker 進程還需要具備對每個根目錄的文件系統和 SCM 訪問權限。

任意代碼倉庫用量池¶

用量池有兩種倉庫配置。repo-backed 用量池會將用量池綁定到一個或多個倉庫：請求帶有 repo=<owner/repo> 標籤，匹配服務該倉庫的 worker，並在儀表盤中顯示在對應代碼倉庫下。any-repo 用量池則將源代碼控制交由你自行處理：請求僅按用量池名稱匹配，且該用量池在儀表盤中顯示在 Any repo 下。

如果你希望自行管理源代碼控制，可以創建一個不綁定倉庫的用量池。pool worker 不需要 git remote。如果你希望由智能體 (或你自己的 image、鉤子和腳本) 來管理克隆和 git 狀態，只需將 --worker-dir 指向任意已有目錄即可：

mkdir -p "$HOME/cursor-sandboxes/default"
agent worker --pool sandbox --worker-dir "$HOME/cursor-sandboxes/default" start

在該目錄中添加 .cursor/rules 文件，以告知 Cursor 這些機器上有哪些目錄和工具可用。

若要讓 worker 在 claim 時克隆所 claim 智能體的倉庫，請傳入 --clone-git-repos。該行爲需顯式啓用 (opt-in) ，默認的 any-repo 行爲不會執行克隆。

agent worker --pool sandbox --clone-git-repos start

--clone-git-repos 隱含 --mint-github-token。clone 會使用簽發出的短期 GitHub token。團隊管理員必須爲 Team Pool worker 啓用 GitHub token 簽發，且 git 必須在 PATH 中。

此 flag 僅可用於任意代碼倉庫用量池 worker：即非 default 的具名 --pool，且未綁定代碼倉庫 (repo=) 、未綁定機器 (name=) 。若用於已綁定代碼倉庫的 worker、具名機器、default 用量池或個人 我的機器 worker，CLI 會報出明確錯誤並退出。

分支名通過 --branch 進行 clone。完整的 40 字符 commit SHA 會在 clone 後執行 detached checkout。請使用 HTTPS 形式的 GitHub remote，以便籤發的 token 能夠完成認證。

若 clone 失敗，請求會繼續留在隊列中。操作者只會看到通用的 clone 失敗信息。

--clone-git-repos、--mint-github-token 和 --sync-dashboard-secrets 均假定每個容器或操作系統用戶只運行一個 worker。不支持在同一用戶下同時部署多個已啓用憑據的 worker。

任意代碼倉庫用量池不帶 repo= 路由標籤。針對這類用量池啓動 agents 時，將 env.type 設爲 "pool"、env.name 設爲用量池名稱，並省略 repos (參見 Create An Agent) 。在 cursor.com/agents 的 Any repo 下選擇該用量池。

管理用量池¶

用量池是持久的。即使最後一個 worker 斷開連接，用量池依然保持註冊狀態且可被選擇，因此你可以縮容到零，等請求到來時再恢復容量。用新的用量池名稱啓動 worker 會隱式創建該用量池。也可以通過 Cloud Agents API 提前管理用量池：

• POST /v0/private-workers/pools：在任何 worker 連接之前預先註冊用量池。若爲 repo-backed 用量池，需包含 repoOwner、repoName 和 repoUrl；若爲 any-repo 用量池，則省略這些字段。
• GET /v0/private-workers/pools：列出用量池，並顯示已連接和使用中的 worker 數量。
• DELETE /v0/private-workers/pools：軟刪除用量池，不會影響當前已連接到該用量池的機器。

可藉助 List Pools 和待處理請求判斷何時重新擴容 worker。

用量池名稱¶

當你希望將會話路由到特定子集 (例如 GPU 機器、預發佈環境機器組或團隊專用的構建機器) 時，可以按名稱對用量池中的 worker 進行分組。

將名稱傳給 --pool：

agent worker --pool gpu start

如果省略名稱，worker 會加入 default 用量池。較早的 CLI 版本僅支持 boolean 類型的 --pool 加上獨立的 --pool-name，這些版本仍可繼續使用；--pool-name 是 --pool <name> 的已棄用別名。

當 orchestrator 注入 config 時，可以從 environment 設置用量池名稱：

export CURSOR_WORKER_POOL_NAME=gpu
agent worker --pool start

可複用的 worker (啓動時未加 --pool) 不屬於任何用量池。

啓動會話或編輯自動化時，可在 Cloud Agents 儀表盤 的 worker 選擇器中選擇一個用量池。你也可以在 Slack、GitHub 或 Linear 觸發器中添加 pool=<name>。會話只會路由到以該用量池名稱註冊的 worker。

觸發用量池代理¶

當你希望雲端代理在團隊共享的 worker 工作器羣 上運行時，請使用用量池觸發器。對於集中管理的容量、自動擴縮容、類 CI runner 以及倉庫範圍的基礎設施，用量池 worker 是合適的目標。

團隊管理員可在 Cloud Agents 儀表盤 的“自託管”部分控制自託管路由。允許自託管機器允許用戶按請求啓用自託管。不啓用時，運行會使用 Cursor 的託管基礎設施。要求自託管機器會將雲端代理 run 路由到自託管 worker。

當 Cursor 啓動一個用量池代理時，會根據標籤匹配 workers。每個用量池請求都包含一個 repo=<owner/repo> label。發往指定名稱用量池的請求還會包含 pool=<name>。

用量池 workers 會處理：

• 受 要求自託管機器 約束的運行，除非請求通過 worker= 或 machine= 指定了某個特定的“我的機器” worker
• 帶有 self_hosted=true、self_hosted 或 selfhosted 的請求
• 帶有 pool=<name> 的請求，這也會選中對應的命名用量池
• 從觸發表面進行代碼倉庫選擇的自託管請求，例如在支持的情況下使用 repo=<owner/repo>

repo= 用於爲 run 選擇代碼倉庫。對於團隊用量池運行，該代碼倉庫會成爲 repo=<owner/repo> worker 標籤。它不會指向個人機器。

通過集成使用以下選項來啓動用量池代理：

• Slack：提及 @Cursor，並附帶 self_hosted=true、單獨的 self_hosted、selfhosted 或 pool=<name>。舊版別名如 private_worker=true、useprivateworker 和 useprivateworkers=false 仍然可用。
• GitHub：在 issue、PR 或評審評論中評論 @cursoragent self_hosted=true ... 或 @cursoragent pool=<name> ...。舊版 private_worker=true 別名仍然可用。
• Linear：在 issue 正文中添加 pool=<name> 或 [pool=<name>]。你也可以使用 issue 或項目標籤，其中父標籤爲 pool，子標籤爲對應的值。Linear 不會解析單獨的 self_hosted=true。

策略處理取決於請求從哪裏發起：

• Slack：當“允許自託管機器”關閉時，會拒絕自託管啓用請求，並在 Slack 中回覆。如果“要求自託管機器”開啓，則每次 Slack 提及都會以自託管方式運行。
• GitHub：代碼倉庫中的 OWNER 和 COLLABORATOR 用戶可以將運行路由到自託管 workers。其他評論者在啓用時會在託管基礎設施上運行；如果“要求自託管機器”已開啓，則會被跳過。這樣可以保護公共倉庫，避免外部貢獻者通過評論觸發運行。
• Linear：當“允許自託管機器”關閉時，會拒絕顯式的自託管請求。該 issue 會收到一條代理活動錯誤，提示管理員開啓自託管 workers，或移除該提示以改爲在 Cursor 的託管基礎設施上運行。

若要按名稱定位到你自己的某臺機器，請使用我的機器並配合 worker= 或 machine=。

Cloud Agent API 使用相同的解析器以及 usePrivateWorker 和 labels 字段。有關端點詳情，請參閱 Cloud Agent API 文檔。

Hooks¶

自託管機器 worker 會在雲端代理會話期間運行基於命令的鉤子，並從該 worker 所服務的工作區中加載配置。

• 項目 hooks。 將 .cursor/hooks.json 及其引用的腳本提交到 worker 所用的代碼倉庫或工作區目錄中，即 git checkout、--worker-dir 根目錄，或你爲 any-repo pool 傳入的目錄。
• 團隊和企業級管理的 hooks。 在企業版中，worker 還會運行在網頁儀表盤中配置的鉤子。

Hooks 參考文檔介紹了 schema、事件和示例。Cloud agent 支持列出了 Cloud Agent 循環會運行哪些事件。

以下 Cloud Agent 限制同樣適用於這些執行工具的 worker：

• 僅支持基於命令的鉤子。 基於提示的鉤子不會運行。
• 不支持僅限 IDE 的鉤子。 Tab 鉤子 (beforeTabFileRead、afterTabFileEdit) 和 workspaceOpen 不會在 worker 上運行。

sessionStart 和 sessionEnd 會在自託管機器 worker 上運行：當雲端代理會話認領該 worker 時以及該認領被釋放時觸發。Cursor 託管的 Cloud Agents 會跳過這些鉤子。

Kubernetes 及其他編排平臺上的 worker 使用相同的鉤子模型。

標籤¶

標籤是用於描述 worker 的鍵值對。它們決定雲端代理會話會被路由到哪個用量池。

CLI 標誌¶

適合快速測試或小型用量池：

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

JSON 文件¶

更適合生產環境，此時標籤通常作爲配置來管理：

{
  "team": "backend",
  "env": "production",
  "capabilities": ["docker", "gpu"]
}

agent worker --pool --labels-file labels.json start

TOML 文件¶

與 JSON 相同，只是格式不同：

team = "backend"
env = "production"
capabilities = ["docker", "gpu"]

agent worker --pool --labels-file labels.toml start

環境變量¶

當路徑由編排器注入時，這種方式很有用：

export CURSOR_WORKER_LABELS_FILE=/path/to/labels.json
agent worker --pool start

repo 和 pool 標籤爲保留項。repo 在存在時來自 worker 目錄的 Git remote。pool 由 --pool 設置。不要手動設置其中任一項。

MCP 服務器¶

自託管 workers 上的 MCP 服務器會按傳輸方式路由：

如果你的 MCP 服務器需要訪問私有網絡中的端點，請使用命令 (stdio) 傳輸方式。該進程會直接在 worker 上運行，並共享其網絡環境。對於基於 HTTP 的 MCP 服務器，Cursor 會通過其後端管理連接，並處理 OAuth 和會話緩存。

產物¶

產物在自託管 worker 和 Cursor 託管的智能體上的行爲完全一致。智能體在 worker 內生成產物，再由 worker 通過 HTTPS 將其上傳到 Cursor 管理的存儲。所有下游內容 (PR 嵌入、儀表盤預覽、通知附件) 都由 Cursor 的後端處理，不依賴 worker 運行在何處。

產物默認啓用。有關其在 UI 中的顯示效果，請參閱 能力。

要禁用產物上傳，請阻止發往 cloud-agent-artifacts.s3.us-east-1.amazonaws.com 的出站流量。智能體會話會繼續工作；但在該會話期間生成的產物將無法上傳。

網絡¶

worker 需要具備對以下地址的出站 HTTPS 訪問權限：

• 用於智能體會話的 api2.cursor.sh 和 api2direct.cursor.sh
• 用於命令行界面更新以及在 macOS 上首次安裝 Cursor Computer Use 的 downloads.cursor.com
• 用於上傳產物的 cloud-agent-artifacts.s3.us-east-1.amazonaws.com

如果你的防火牆只能匹配通配符，*.s3.us-east-1.amazonaws.com 可以覆蓋該產物主機，但也會同時開放該區域中的所有其他存儲桶。若防火牆支持，建議優先使用精確主機規則。

不需要入站端口、公網 IP 或 VPN 隧道。如果你使用代理，請在 worker 環境中設置 HTTPS_PROXY 或 https_proxy。

失效情況¶

先決條件 部分介紹了 worker 在智能體運行期間需要訪問的更多主機 (Git 主機、包註冊表、內部 API) 。

在 Kubernetes 上部署¶

如果希望由平臺來負責調度、健康檢查和 Pod 生命週期，可以在 Kubernetes 上運行用量池 worker。可以從 anysphere/k8s-workers 開始：這是一個 Helm 示例，用於在你的集羣中以 --spawn 方式運行 worker 控制器。spawn 鉤子會爲每個已認領的請求創建一個 worker Pod，或者由控制器通過 --warm-idle 保持空閒的熱備 Pod。無需 CRD。

Cursor Kubernetes operator 和 WorkerDeployment Helm chart 已棄用。如果你的集羣已經在運行
operator，它仍可繼續工作，operator 參考也仍然可用。新的
Kubernetes 部署應使用 k8s-workers 模板。

其他主機的運行方式也一樣：任何能安裝 Cursor 命令行界面、並可通過出站 HTTPS 訪問 Cursor 的 VM、容器或裸金屬機器，都可以在 systemd、Docker 或你自己的進程管理器下運行用量池 worker。如需查看涵蓋 AWS Lambda、Cloudflare、Namespace、Modal、Daytona、E2B、Vercel 和 Coder 的合作伙伴指南與參考模板，請參閱 Integrations。

Worker controller¶

agent worker controller 通過 --spawn 鉤子啓動 worker。該鉤子可以派生進程、啓動容器，或像 k8s-workers 模板那樣創建 Kubernetes Pod。--warm-idle 是預熱容量路徑：controller 會爲每個缺失的空閒 worker 運行一次鉤子，而不是修改 Deployment 或 HPA。WorkerDeployment.spec.readyReplicas 屬於已棄用的 Kubernetes operator；只有已經在運行它的集羣才需要該控制方式。

--spawn <path> 爲必填項。該鉤子在成功認領後運行一次，或爲每個缺失的預熱 worker 運行一次。鉤子環境包含 CURSOR_API_KEY、CURSOR_API_URL、CURSOR_API_ENDPOINT、CURSOR_AGENT_WORKER_ID 以及請求字段。請通過 --api-key 或 CURSOR_API_KEY 使用服務賬戶密鑰進行身份驗證。該密鑰會綁定所屬團隊，不使用會話登錄。

spawn 鉤子所需的全部信息均以環境變量形式提供：

spawn 鉤子應使用相同的 worker ID 啓動 worker：

#!/usr/bin/env bash
set -euo pipefail
agent worker --pool "$CURSOR_POOL" --worker-id "$CURSOR_AGENT_WORKER_ID" start

worker CLI 也會從環境變量中讀取 CURSOR_AGENT_WORKER_ID，因此啓動容器的 spawn 鉤子可以改爲直接傳入這些變量：

#!/usr/bin/env bash
set -euo pipefail

docker run -d \
  -e CURSOR_API_KEY \
  -e CURSOR_AGENT_WORKER_ID \
  -e CURSOR_WORKER_POOL_NAME="$CURSOR_POOL" \
  your-worker-image \
  agent worker --pool start

Claim-then-spawn¶

默認模式。controller 會列出待處理請求，監聽 GET /v0/private-workers/pending-requests/stream，逐個 claim 請求，併爲每次 claim 執行一次 --spawn。

agent worker controller --spawn ./spawn.sh --api-key "$CURSOR_API_KEY" --pool gpu --pool default

Warm pool¶

--warm-idle <count> 會預先啓動 unclaimed worker，從而在每個 --pool 中保持 <count> 個空閒 worker 處於連接狀態。它不會調用 claim。Cursor 會將排隊中的 agents 分配給這些 warm worker。

controller 每 60 秒對 GET /v0/private-workers/pools 執行一次 reconcile。pending-requests SSE stream 僅用於加快 backfill 速度。

Warm mode 必須指定 --pool，且不能與 --all-pools 同時使用。每個 pool 只運行一個 warm controller：服務器端沒有 spawn 租約機制，多個 controller 併發運行時可能會短暫啓動過多 worker。

agent worker controller --spawn ./spawn.sh --api-key "$CURSOR_API_KEY" --pool gpu --warm-idle 5

若想改爲構建自定義 controller，請使用 Cloud Agents API。

會話生命週期¶

一旦某個 worker 與請求匹配成功，Cursor 會將所有智能體工具調用直接轉發到該機器。連接的空閒超時默認爲 1 小時，可按需配置：

agent worker --pool my-pool --idle-release-timeout 600 start

--idle-release-timeout (環境變量 CURSOR_WORKER_IDLE_RELEASE_TIMEOUT) 表示會話結束後 worker 保持連接、等待後續消息的秒數。若收到後續消息，計時器會重置。超時觸發時，CLI 以退出碼 0 退出，便於管理進程回收該機器。傳入 0 可禁用基於空閒的釋放。釋放 claim 是另一個獨立的 API：它只是不再爲該智能體優先選擇該機器，並不會退出 worker CLI。

worker 超時後，Cursor 會將其標記爲已釋放，該機器可以重置並重新進入用量池。如果用戶重新啓動一個已與其機器斷開連接的對話，該對話會連接到用量池中的一臺新機器。除非用量池啓用了休眠，否則原機器上的 workspace 狀態不會延續。

休眠¶

智能體空閒時，用量池中的機器不必一直在線。會話結束後，worker 會等待後續請求，直到空閒超時觸發；而在兩輪之間讓每臺機器都保持運行，成本相當高。

這樣做的代價是工作區不再就近可用。若不啓用休眠，機器釋放後到達的後續請求會重新從用量池獲取容量：智能體會落到一臺全新的機器上，最初幾分鐘可能都在重建它原本已有的工作區。啓用休眠後，機器恢復時工作區完好如初，後續請求可從智能體中斷處繼續。

爲用量池設置重新連接窗口¶

workerReadyTimeoutSeconds 控制 Cursor 在把請求分配給另一個 worker 之前，等待已認領機器重新連接的時長。默認值爲 0：後續請求會立即重新獲取容量。

curl --request POST \
  --url "https://api.cursor.com/v0/private-workers/pools" \
  -u "$CURSOR_API_KEY:" \
  --header 'Content-Type: application/json' \
  --data '{
    "scope": "team",
    "poolName": "gpu",
    "workerReadyTimeoutSeconds": 900
  }'

機器空閒時創建快照¶

縮短 worker 的 --idle-release-timeout，讓機器在智能體空閒後儘快釋放。當 worker 退出時 (空閒釋放時退出碼 0) ，或當 Get An Agent 報告 status 爲 IDLE 時，爲該機器創建快照並將其停止。

識別喚醒信號¶

當某個智能體收到後續請求，而其已認領的機器處於離線狀態時，Cursor 會在重新連接窗口內等待，並把該請求作爲“已認領但離線”的隊列條目發佈。你的 controller 有兩種識別方式：List Pending Pool Requests 會返回帶有 claimedWorkerId 和 wakeTimeoutMs 的條目；事件流則會發出包含相同字段的 claimed_offline 事件。

重新啓動機器¶

在窗口到期前恢復快照，並以相同的 id 啓動 worker：

export CURSOR_AGENT_WORKER_ID="<claimedWorkerId>"
agent worker --pool gpu start

後續請求會在該機器上繼續執行，工作區完好如初。

無法恢復時釋放認領¶

如果機器無法恢復，例如快照已丟失，請釋放認領。請求會立即回到隊列，由替代機器認領。如果不做任何處理，窗口也會自行到期：認領過期後，請求會作爲未認領條目重新發布 (產生一個新的 created 事件) ，任何 worker 都可以處理。

構建你自己的 controller¶

內置 controller 能滿足大多數配置需求。如果你需要自定義邏輯，例如自己的調度、配額或機器分配，可基於 Cloud Agents API 構建 controller。controller 需要做三件事：監聽請求隊列、認領請求，併爲其啓動 worker。這些端點同樣可用於在 Kubernetes 之外監控利用率並實現自動伸縮。

使用用量池的服務賬戶 API 密鑰，通過 Basic 認證或 Bearer token 進行認證。其他類型的 API 密鑰無法管理用量池 worker 的容量。

監控請求隊列¶

先列舉一次隊列，建立待處理請求的視圖，然後通過 Server-Sent Events (SSE) 實時跟蹤變化。

從 GET /v0/private-workers/pending-requests 開始。添加 ?pool=<name> 可只監視單個用量池。分頁讀取直至全部取完，並保留響應中的 streamCursor：

curl --request GET \
  --url "https://api.cursor.com/v0/private-workers/pending-requests?pool=my-pool&limit=50" \
  -u "$CURSOR_API_KEY:"

然後通過 GET /v0/private-workers/pending-requests/stream 打開事件流，傳入該 streamCursor 及相同的篩選條件。隨着事件不斷到達，及時更新你的視圖：收到 created 和 claimed_offline 事件時添加請求，收到 claimed 或 expired 事件時移除請求：

curl --request GET --no-buffer \
  --url "https://api.cursor.com/v0/private-workers/pending-requests/stream?pool=my-pool&cursor=$STREAM_CURSOR" \
  --header 'Accept: text/event-stream' \
  -u "$CURSOR_API_KEY:"

游標會在簽發它的那次 list 請求之後五分鐘過期。當 stream 返回 410 Gone 時，請重新執行 list，並用新的 streamCursor 重新打開 stream。更好的做法是：每五分鐘 (加入少量抖動) 重新 list 一次，而不是等到出現 410。

視圖中的請求數量即爲該用量池的隊列深度。數量上升時，請增加 worker。請把事件視爲提示，把 list 結果視爲 source of truth：事件投遞是盡力而爲的，每次重新 list 都會糾正偏差。完整的投遞保證與游標規則請參閱 Watch Pending Pool Requests。

列出 workers¶

curl --request GET \
  --url "https://api.cursor.com/v0/private-workers?status=idle&scope=team_pool&limit=50" \
  -u "$CURSOR_API_KEY:"

Worker 包含 name、isInUse、連接元數據以及倉庫字段 (對於 any-repo worker，repoOwner/repoName 爲空字符串) 。完整響應參見 API 參考文檔。

列出用量池¶

curl --request GET \
  --url "https://api.cursor.com/v0/private-workers/pools?scope=team_pool" \
  -u "$CURSOR_API_KEY:"

返回持久用量池，包含 connectedWorkerCount、inUseWorkerCount、isStale 以及可選的倉庫字段。任意代碼倉庫用量池不含倉庫字段。請通過此接口獲取各用量池的已連接數量和使用中數量；下方的團隊級 worker 摘要無法替代特定用量池的需求數據。

獲取工作器摘要¶

curl --request GET \
  --url "https://api.cursor.com/v0/private-workers/summary" \
  -u "$CURSOR_API_KEY:"

返回你的用戶和團隊的連接數與使用中數。參見 獲取工作器摘要。可在隊列積壓增長時用此調整響應規模，或在利用率較高時觸發伸縮：

const summary = await response.json();
const team = summary.teamSummary;
if (team && team.totalConnected > 0) {
  const utilization = team.inUse / team.totalConnected;
  if (utilization >= 0.9) {
    // 擴容：預置更多 worker
  }
}

根據 ID 獲取 worker¶

curl --request GET \
  --url "https://api.cursor.com/v0/private-workers/pw_123" \
  -u "$CURSOR_API_KEY:"

認領待處理請求¶

臨時 controller 可以在啓動 worker 之前預留排隊中的請求：

curl --request POST \
  --url "https://api.cursor.com/v0/private-workers/claim" \
  -u "$CURSOR_API_KEY:" \
  --header 'Content-Type: application/json' \
  --data '{
    "id": "bc-00000000-0000-0000-0000-000000000002",
    "workerId": "pw_123"
  }'

然後使用相同的 id 啓動 worker (CURSOR_AGENT_WORKER_ID=pw_123) 。參見 Claim A Pending Request。

釋放 claim¶

刪除將智能體綁定到自託管 worker 的 claim。之後 Cursor 將不再優先把該智能體調度到這臺機器上：

curl --request POST \
  --url "https://api.cursor.com/v0/private-workers/claims/bc-00000000-0000-0000-0000-000000000002/release" \
  -u "$CURSOR_API_KEY:"

當已存在有效 claim 時，再次發起 claim 會被拒絕；請先釋放，再申領新的 workerId。參見 Release A Claim。

監控¶

當使用 --management-addr 啓動 worker 時，管理服務器會提供 GET /metrics、GET /healthz 和 GET /readyz：

agent worker --pool --management-addr ":8080" start

從您的 worker 採集指標：

curl http://localhost:8080/metrics

可用指標¶

Gauge

計數器

會話結束原因¶

cursor_self_hosted_worker_session_ends_total 計數器包含一個 reason 標籤，其值可能爲以下之一：

安全¶

數據流。 有兩類數據會離開您的網絡：一類是模型在推理期間讀取的文件分塊，另一類是 worker 上傳到 Cursor 管理的存儲中的雲端代理 產物 (截圖、視頻和日誌引用) ，以便它們顯示在 PR 和儀表盤中。您的代碼倉庫、構建緩存和機密信息始終保留在您的機器上。

僅出站。 worker 通過 HTTPS 發起出站連接。無需開放入站端口，也無需更改防火牆設置。

隱私模式。 自託管雲端代理遵循 Cursor 的隱私模式設置。啓用隱私模式後，您的代碼不會被用於訓練。

隔離。 每個智能體會話都會分配到專用的 worker。會話不會在不同 worker 之間共享。

身份驗證。 池中的 worker 使用服務賬戶 API 密鑰進行身份驗證。其他類型的 API 密鑰將被拒絕。

儀表盤可見性。 團隊管理員可以查看所有已連接的 worker。團隊成員只能查看分配給自己的 worker。

CLI 參考¶

agent worker [options] start

常見問題¶

如何確定 worker 的規格？¶

worker 沒有固定規格。你可以像爲其服務的倉庫配置 CI
runner 或 devbox 一樣，來確定每個 worker 的規格。

每個 worker 都需要足夠的 CPU、內存、磁盤和網絡訪問能力，以便克隆
倉庫，並運行你的 agents 所需的構建、測試和工具。

可以把技能預置到 worker image 中嗎？¶

可以。.cursor/skills/ 或 .agents/skills/ 中的
項目級技能會自動在自託管 workers 上可用。

如果要在團隊內共享技能，可以將其提交到倉庫中，或預置到
你的自定義 worker image 中。個人技能
同步適用於
managed Cloud Agents，不適用於自託管 workers。

MCP 服務器可以在自託管 workers 上運行嗎？¶

可以。請通過 Cloud Agents 儀表盤配置 MCP 服務器。關於
按不同 transport type 進行 routing 的方式，請參閱
MCP 服務器 部分。

hooks 會在自託管 workers 上運行嗎？¶

會。自託管機器 worker 會運行 .cursor/hooks.json 中的
項目 hooks。在企業版中，它們還會運行團隊和
enterprise-managed hooks。請參閱 Hooks。

多個 agents 可以共用一個 pool worker 嗎？¶

一個 pool worker 同一時間只服務一個智能體。當請求需要等待可用容量時，
請添加 worker 或擴容用量池。

Mac pool workers 可以運行計算機使用嗎？¶

可以。使用 --computer-use 啓動它們。首次啓動會安裝
Cursor Computer Use 輔助應用；請爲其授予 輔助功能 和 屏幕錄製
權限，用一個截圖任務驗證後，再爲該機器創建 快照。
屏幕錄製 無法由 MDM 靜默授予，因此請在 template 上手動批准
一次，再由此製作 image。請參閱計算機使用與桌面
共享。

後續步驟¶

• anysphere/k8s-workers：基於 agent worker controller --spawn 構建的 Kubernetes 模板，支持 認領-then-spawn 與 --warm-idle 模式。
• Integrations：面向其他平臺的合作伙伴指南與參考模板。
• Kubernetes operator (已棄用) ：面向已運行 WorkerDeployment operator 的集羣的參考。
• 計算機使用：讓 agents 在你的 worker 上操控桌面和瀏覽器。
• API 參考文檔：worker、用量池、待處理請求隊列以及 worker token 相關的端點。