Cursor Self-Hosted Machines 實戰：把 cloud agent 跑在自己的機器上（附 My Machines / Team Pools 完整設定）

瀏覽次數: 1

先講結論，因為這件事很容易被標題騙：Cursor 的 Self-Hosted Machines 不是「程式碼完全不出你家網路」。它把 工具執行（跑指令、改檔案、開瀏覽器）搬到你自己的機器上，但 agent loop——推論、規劃、決定下一步——仍然跑在 Cursor 雲端。模型推論時讀到的檔案內容片段，還是會離開你的網路。

搞清楚這條界線之後，這功能其實非常實用：你終於可以讓 cloud agent 直接在有 GPU 的機器、有 Xcode 的 Mac、或是那台已經 warm 好 build cache 又連得到內網 registry 的 devbox 上幹活，而且整條路只需要一條「往外」的 HTTPS 連線，防火牆一個 inbound port 都不用開。

這篇是手把手實作：從個人五分鐘接一台機器，到團隊級 pool 的 autoscaling、hibernation、監控指標，以及什麼時候你不該自架。

本文大綱

一、這功能在解什麼問題

Cursor 的 cloud agent 預設跑在 Cursor 自家雲端的隔離 VM 上。對大多數團隊這是最省事的選擇，但有三類需求會直接卡死：

工具執行必須在內網裡：source control 是內網的 GitLab、package registry 是內網的 Artifactory、測試要打得到只在 VPC 裡的 service。
需要特殊硬體：GPU 機器、跑 iOS 建置的 Mac、或是你已經在用的 Kubernetes / sandbox 平台。
作業系統或 build pipeline 難以打包：你的 build 依賴一整套自訂映像，塞不進 Cloud Agent build。

時間線上這功能分兩波。第一波是 2026 年 3 月 25 日，Katia Bazzi 在 Cursor 部落格發的〈Run cloud agents in your own infrastructure〉，同日 changelog 上線，把 worker 模型端出來，公開背書的客戶包括 Brex、Money Forward、Notion。第二波是 2026 年 9 月 2 日 Jack Pertschuk 的〈Run cloud agents on machines you manage〉，補上真正讓它能跑生產的東西：pool 依佇列自動擴縮、hibernation、any-repo pool、Linux computer use，以及一票 sandbox 供應商整合。

Cursor 在那篇文裡給了一個內部數字：cloud agent 現在產出他們內部合併 PR 的 超過 60%。這是 Anysphere 自家團隊的數字、自己回報、沒有第三方驗證，別當成你團隊的預期值——但它解釋了為什麼「這些 agent 到底跑在誰的機器上」突然變成一個需要認真回答的問題。

二、運作原理：worker、pool、controller

整個機制只有三個名詞，官方文件的定義是這樣：

Worker：一台你擁有、用 Cursor CLI 註冊上去的機器。agent 真正幹活的地方——改檔案、跑指令、存取程式碼。可能是你 AWS 帳號裡的 Linux VM，也可能是你桌上那台 Mac mini。
Team Pool：一個具名的路由目標。請求會在 pool 裡排隊，直到某個 worker 認領（claim）它；認領之後這個 chat 的所有活動都轉發給那台 worker。例如 gpu pool 只由有 GPU 的機器服務，ios pool 只由 Mac 服務。
Controller：你自己跑的程式，依需求調整 worker 容量。請求進來、pool 裡沒有閒置 worker，controller 就去開一台新機器。

連線方向是這件事的關鍵。你在機器上跑 agent worker start，它會對 Cursor 後端開一條長生命週期的 outbound HTTPS 連線，Cursor 的 tool call 從這條連線送過來。官方文件寫得很直白：「Cursor never connects into your network」——不需要 inbound port、不需要 public IP、不需要 VPN tunnel。

Worker 需要對外連到哪些 host，文件也列得很清楚，方便你寫防火牆規則：

api2.cursor.sh 和 api2direct.cursor.sh：agent session 本身
downloads.cursor.com：CLI 更新、macOS 上第一次安裝 Cursor Computer Use 輔助程式
cloud-agent-artifacts.s3.us-east-1.amazonaws.com：artifacts 上傳

有代理伺服器的話設 HTTPS_PROXY 或 https_proxy 就好。

這裡有個實用的招式：如果你不想讓截圖、影片這類 artifact 上傳到 Cursor 管理的儲存空間，直接在 worker 上封鎖對 S3 那個 host 的 outbound 流量就行。 agent session 和所有 tool call 照常運作，只是 artifact 不會出現在 PR 和 dashboard 上。文件把每個 host 被擋掉的後果做成了失敗模式對照表，這是少見的誠實。

MCP server 的路由規則也值得先記起來，因為它決定你的 MCP 能不能碰到內網：

Transport	跑在哪	適用
Command（stdio）	你的 worker	process 直接起在你機器上，共用它的網路，打得到內網 API 與本機服務
HTTP / SSE（url）	Cursor 後端	Cursor 幫你處理 OAuth、session 快取

要打內網的 MCP，一定要用 stdio transport。 用 url 的話，連線是從 Cursor 後端發起的，你的內網它根本看不到。

三、手把手 A：My Machines，五分鐘接上第一台

這是個人用法，不需要 Enterprise 方案，適合拿來先摸清楚 worker 模型再決定要不要建 pool。

1. 裝 CLI

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

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

agent --version

2. 登入

agent login

devbox 上開不了瀏覽器的話，去 Cursor Dashboard → API Keys 拿一把個人 user API key：

agent worker start --api-key "your-user-api-key"

注意這裡有個常見坑：My Machines 只吃個人憑證（瀏覽器登入、個人 user API key，或 user-scoped token）。service account key 只能啟動 pool worker，team admin key 和 organization key 則完全不能啟動 worker。

3. 起 worker

cd /path/to/repo
agent worker start

保持這個 process 活著。My Machines 的 worker 預設是長生命週期的，你不關它就一直在，可以重複服務後續的 session。

4. 去 cursor.com/agents 派任務，機器會出現在環境下拉選單裡。

幾個馬上會用到的選項

取名字（同一個 repo 有多台機器時必備）：

agent worker start --name "my-devbox"

一台機器服務多個 repo——--worker-dir 可以重複，最多 20 個路徑，每個路徑必須已經存在：

agent worker \
  --worker-dir "$HOME/repos/app" \
  --worker-dir "$HOME/repos/infra" \
  start

第一個 root 會被當成主 repo（決定 dashboard 顯示與指派身分）。文件特別提醒一個會讓人誤判的行為：dashboard 目前只會把 self-hosted worker 顯示在它的主 repo 底下，看起來像只註冊了第一個 repo。要確認全部 root 都吃到了，用 start --verbose 看 log 裡的 workspacePaths 和 x-repository-urls。

開 computer use（注意 --computer-use 要放在 start 前面）：

agent worker --computer-use --name "my-mac" start

macOS 第一次啟動會裝 Cursor Computer Use 輔助程式，你得去「系統設定 → 隱私權與安全性」給它 輔助使用（Accessibility） 和 螢幕錄製（Screen Recording） 兩個權限。踩過的人都知道這裡最容易錯：權限要給 Cursor Computer Use 這個 app，不是給 Terminal、也不是給 Cursor Agent Helper。

Linux 則要先裝桌面套件：

sudo apt-get install -y --no-install-recommends \
  dbus-x11 ffmpeg tigervnc-standalone-server \
  x11-utils x11-xserver-utils xdotool xfce4

Linux 另外有個 --share-desktop 可以讓你從 Cursor 裡看甚至接手控制 agent 的桌面（view 或 view_and_control，後者是預設）。文件強調它用的是 worker 自建的隔離桌面、不是機器本身的登入 session，畫面只走既有那條 outbound 連線出去，不開任何 inbound port，剪貼簿傳輸則是全程封鎖。

從 Slack / GitHub / Linear 指定機器

想讓聊天視窗來的請求跑在特定機器上，用 worker= 或 machine=（這是唯二能指向 My Machines 的觸發選項）：

Slack：@Cursor worker=my-devbox fix the flaky test
GitHub：@cursoragent worker=my-devbox fix the flaky test（你必須是該 repo 的 trusted commenter，且目標機器屬於與你 GitHub 帳號連結的 Cursor 使用者）
Linear：在 issue 內文加 worker=my-devbox

命中規則是三個條件全滿足才會跑：機器屬於發起請求的使用者、--name 對得上、而且機器註冊的 repo 跟觸發來源的目標 repo 一致。第三條最常被忽略。名字對但 repo 不對時，Cursor 會直接拒絕而不是隨便跑：這是刻意設計的——針對 repo A 的請求，絕不應該跑在 repo B 的 checkout 上。

機器沒出現在選單裡就先跑這個：

agent worker debug

它會檢查認證、privacy 路由、repo 標籤，以及 Cursor 到底看不看得到符合條件的 worker。要在啟動前印同樣的診斷，用 agent worker start --debug。

四、手把手 B：Team Pools，真正拿來給團隊用

Pool 需要 Cursor Enterprise 方案，加上一把 service account API key，還要 team admin 先去 Cloud Agents dashboard 打開自架設定（Allow Self-Hosted Machines 讓使用者自己選；Require Self-Hosted Machines 則是強制所有 cloud agent 都走你的 worker）。

export CURSOR_API_KEY="your-service-account-api-key"
cd /path/to/repo
agent worker --pool gpu --idle-release-timeout 600 start

--pool 後面不給名字就會加入 default pool。每個 cloud agent session 一次只認領一個 worker，一台 pool worker 同時只服務一個 agent。

--idle-release-timeout 是最值得調的參數：session 結束後 worker 還會保持連線多久（秒），等後續追問。預設是 3600 秒——也就是說你如果不動它，機器閒置一小時才會釋放，雲端帳單就是這樣長出來的。有後續訊息進來計時器會重置；時間到則 CLI 以 exit code 0 結束，方便 supervisor 回收機器。給 0 是關閉閒置釋放。

用 labels 做路由

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

生產環境建議改用檔案（JSON 或 TOML 都行，--label 和 --labels-file 互斥）：

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

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

或讓 orchestrator 注入路徑：export CURSOR_WORKER_LABELS_FILE=/path/to/labels.json。repo 和 pool 是保留 label，別手動設。

掛上監控

agent worker --pool --management-addr ":8080" start
curl http://localhost:8080/metrics

會拿到 /healthz、/readyz、/metrics 三個端點。指標清單不長但夠用：

cursor_self_hosted_worker_connected（gauge）：對外連線是否活著
cursor_self_hosted_worker_session_active（gauge）：現在有沒有 session 在跑
cursor_self_hosted_worker_last_activity_unix_seconds（gauge）：最後一次收到 frame 或心跳的時間
cursor_self_hosted_worker_session_ends_total（counter）：帶 reason 標籤，值有 stream_end、stream_error、session_closed、session_error、connection_timeout、session_aborted

先建告警的建議：connected 掉到 0 且 connect_retry_total 一直漲，代表出網路徑出問題；session_ends_total{reason="stream_error"} 突增，通常是網路或 proxy 在中間砍連線。

自動擴縮：controller 與 spawn hook

Pool 的自動擴縮靠 agent worker controller，核心是一個你自己寫的 --spawn 腳本：

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

預設是 claim-then-spawn：controller 列出待處理請求、訂閱 GET /v0/private-workers/pending-requests/stream 這條 SSE，認領每個請求，然後每認領一次就執行一次 spawn hook。Hook 拿得到的環境變數包括 CURSOR_REQUEST_ID、CURSOR_USER_ID、CURSOR_REPO_URL／_OWNER／_NAME、CURSOR_POOL、CURSOR_AGENT_WORKER_ID、CURSOR_API_KEY 等。

最小可用的 spawn.sh 就這樣：

#!/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，所以把變數透傳進去就好：

#!/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

另一種是 warm pool，用 --warm-idle <count> 在每個 pool 裡預先放幾台閒置 worker、完全不呼叫 claim，讓 Cursor 自己去指派：

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

兩個實務細節：controller 每 60 秒 對 GET /v0/private-workers/pools 做一次 reconcile，SSE 只是加速補位；還有——warm 模式每個 pool 只能跑一個 controller，因為伺服器端沒有 spawn lease，同時跑多個 controller 會短暫超開機器。

Kubernetes 走的是另一條路：agent worker controller 只管 fork 出來的 process，不會去改 WorkerDeployment。在 K8s 上要維持暖機容量，請用 WorkerDeployment.spec.readyReplicas。

Any-repo pool：source control 你自己管

Pool 有兩種 repo 型態。Repo-backed pool 綁定一到多個 repository，請求帶 repo=<owner/repo> label 做匹配。Any-repo pool 則只靠 pool 名字匹配，在 dashboard 裡歸在 Any repo 底下：

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

招式：在那個目錄放一個 .cursor/rules，告訴 agent 這台機器上有哪些目錄和工具可用。

想讓 worker 在被認領時自己 clone repo，加 --clone-git-repos（預設關閉，會 imply --mint-github-token，需要 team admin 開啟 token minting、git 要在 PATH 上、remote 要用 HTTPS）。這個 flag 只能用在具名的 any-repo pool worker 上——不能是 default pool、不能綁定 repo、不能是具名機器、不能是 My Machines worker，違反的話 CLI 會直接報錯退出。另外 --clone-git-repos、--mint-github-token、--sync-dashboard-secrets 都假設「一個容器或 OS 使用者只有一個 worker」，把多個帶憑證的 worker 塞在同一個使用者底下是不支援的。

五、Hibernation：省錢跟工作區保留之間的取捨

這是 9 月那波更新裡最值得學的一段設計。

問題長這樣：session 結束後 worker 會等到 idle timeout 才釋放，這段時間機器一直開著、一直在燒錢。但如果太早釋放，追問訊息進來時 agent 會落到一台全新的機器上，得花好幾分鐘重建它剛剛已經有的工作區。

Hibernation 的解法是：閒置時把機器快照起來關掉，追問來了再喚醒。四個步驟：

1. 給 pool 一個重連視窗。workerReadyTimeoutSeconds 控制 Cursor 願意等那台被認領的機器重連多久，預設是 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
  }'

2. 閒置就快照。把 --idle-release-timeout 調短，worker 以 exit code 0 結束時（或 Get An Agent 回報 status 為 IDLE 時）快照並停掉機器。

3. 認出喚醒訊號。追問來了但機器離線時，Cursor 會把它當成「已認領但離線」的佇列項目公告出來。你的 controller 有兩個管道認出它：list pending requests 會回傳帶 claimedWorkerId 和 wakeTimeoutMs 的項目，event stream 會發出帶同樣欄位的 claimed_offline 事件。

4. 用同一個 worker id 復活：

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

追問就會在那台機器上、帶著完整工作區繼續。如果快照沒了救不回來，主動呼叫 release claim 讓請求立刻回到佇列；什麼都不做的話，視窗過期後請求會以一個全新的 created 事件重新公告，任何 worker 都能接。

六、數字、上限，跟一個必須講清楚的限制

先把可查證的數字放一起，都來自 Cursor 官方部落格與文件：

項目	數值	出處
Cursor 內部由 cloud agent 產出的合併 PR 佔比	超過 60%	2026-09-02 部落格（Anysphere 自報，非第三方驗證）
Cursor 託管 cloud agent 已能滿足的客戶比例	超過 80%	choose-runtime 文件
Worker 數量上限	每人 200、每團隊 1000	self-hosted 文件（更大規模要聯絡業務）
`--idle-release-timeout` 預設	3600 秒	pool 文件
`workerReadyTimeoutSeconds` 預設	0 秒	pool 文件
Controller reconcile 週期	60 秒	pool 文件
`--worker-dir` 可重複次數	最多 20	CLI reference

然後是那個限制。 Cursor 文件的 Security 段落自己寫得很清楚：有兩樣東西會離開你的網路——模型推論時讀到的檔案片段，以及 worker 上傳到 Cursor 管理儲存空間的 artifacts（截圖、影片、log 參照）。9 月那篇部落格講得更直白：「Tool outputs flow back to Cursor for inference and may contain code, and agent transcripts may be processed and stored by Cursor.」

Coder 的 Matt Vollmer 在 2026 年 5 月 6 日那篇〈Self-Hosted Doesn't Always Mean What It Implies〉直接針對這點開火，主張 agent 層（規劃、編排、模型路由、整個 agent loop）留在 Cursor 雲端，就不該叫 self-hosted。要注意他是競品方，但這個技術判斷跟 Cursor 自己文件寫的是一致的，不是抹黑。

所以請這樣理解定位：Self-Hosted Machines 解的是「執行環境在哪、誰維運、能不能碰到內網與特殊硬體」，不是「資料完全不出網」。 如果你的合規要求是 air-gap 或嚴格的資料落地，這個方案過不了關，別浪費時間評估。Privacy Mode 在兩種架構下都適用（開啟時你的程式碼不會被 Cursor 或模型供應商拿去訓練），但那跟「不出網」是兩件事。

七、什麼時候該用、什麼時候別用

Cursor 自己的文件比很多人以為的更保守，它反覆勸退：託管 cloud agent 是多數團隊的建議路徑。 具體來說，如果你只是要讓 agent 碰到私有資源，先試這四招，都試過再考慮自架：

Cloud Agent environments（setup 指令、Dockerfile、快照、secrets）
網路存取控制：依使用者、團隊、環境限制外連網域的白名單
在環境裡跑 Tailscale 或類似的私網 client，去打你 VPC / 內網的服務
Private connectivity：AWS PrivateLink 或 Cloudflare Tunnel，用來連自架 GitHub Enterprise Server、GitLab Enterprise、Artifactory / Nexus 這類私有 registry

真的該自架的訊號：需要 GPU 或 Mac 這類特殊硬體；build pipeline / OS 映像複雜到打包不進 Cloud Agent build；或是合規要求工具執行必須發生在公司管的主機上（log、build 產物、監控都要留在自家）。

代價要算清楚：文件把維運責任列得毫不客氣——主機、映像、每次跑完的 VM 重置、容量、autoscaling、worker 更新、監控、secrets、網路存取、事故處理，全是你的。成本上也是：託管方案的執行基礎設施含在裡面，自架是模型費照付、機器錢你另外出。而且所有 partner 指南和 reference template 官方都定調為「reference architecture」，worker 映像、基礎設施、secrets、擴縮策略、生產驗證都算你的。

不想從零建 sandbox 層的話，Cursor 有八家合作夥伴：AWS Lambda、Cloudflare、Coder、Daytona、E2B、Modal、Namespace、Vercel，各自維護自己的指南。另外有三個官方 reference template 可以直接 clone：anysphere/aws-lambda-workers（spawn hook 每認領一次開一台 Firecracker 隔離的 Lambda MicroVM）、anysphere/cloudflare-workers（Cloudflare Worker 當 controller，每次認領開一個 Cloudflare Container）、anysphere/k8s-workers（每認領一次建一個 Pod，或維持暖機 Pod，不需要 CRD）。

八、對工程團隊的實際意義

如果你決定要動手，我會照這個順序做：

先用 My Machines 接一台 devbox 跑一週，成本是零、不需要 Enterprise，就能驗證你的 agent 工作流在自家機器上到底順不順。真正該回答的問題是：那些「managed 環境重建很痛」的東西（build cache、內網憑證、跑得慢的依賴），搬到自家機器後省下多少時間。
像規劃 CI runner 一樣規劃 worker 規格。官方 FAQ 就是這樣講的：沒有固定規格，每台 worker 要有足夠的 CPU、記憶體、磁碟和網路，去 clone repo、跑完 build、跑完測試。
把團隊的能力烤進映像。專案層級的 skills（.cursor/skills/ 或 .agents/skills/）在 self-hosted worker 上會自動生效；要跨團隊共用就 check 進 repo 或烤進自訂 worker 映像。Hooks 也會跑——.cursor/hooks.json 的專案 hook，Enterprise 上還會跑團隊與企業層級的 hook。特別留意 sessionStart 和 sessionEnd：它們在 session 認領與釋放 worker 時觸發，而且 Cursor 託管的 cloud agent 不會跑這兩個 hook。這是做「每次跑完自動清乾淨工作區」的正確掛載點。
第一天就設 --idle-release-timeout。預設 3600 秒對按秒計費的雲端機器是很貴的預設值。
--management-addr 一起開，metrics 接進既有的 Prometheus。worker 機隊沒有監控就是黑箱。
確認你的 MCP transport 選對了。要碰內網就用 stdio，不然那條路根本不通。

最後補一個容易忽略的：worker timeout 之後 Cursor 會把它標記為已釋放，機器可以重置後回到 pool。使用者如果重啟一個已經跟機器斷開的 chat，chat 會重連到 pool 裡的一台新機器——原本那台的工作區狀態不會帶過去，除非你做了 hibernation。這條規則會直接影響使用者感受到的「agent 是不是忘記剛剛做過什麼」，值得寫進團隊的內部文件。