Cloud Agent Setup

Cloud Agents 執行在 isolated Ubuntu machine。要讓它穩定工作，關鍵是把雲端環境配置到接近真人開發者的狀態。

1. 兩種環境配置方式

官方給出兩條主路徑：

兩種方式都可以生成環境，並設定 update command。update command 會在 agent start 前執行，用於確保 dependencies up to date。

2. Resolution order

Cursor 按這個順序解析環境配置，命中第一個就使用：

1. repo 內 .cursor/environment.json
2. personal environment configuration
3. team environment configuration

這讓 team 可以提供預設環境，個人也能在沒有 repo-level config 時測試新環境。真正要團隊穩定複用的配置，最終應該進入 repo 或 team 配置。

3. Agent-driven setup

推薦流程：

1. 開啟 cursor.com/onboard。
2. 連線 GitHub 或 GitLab。
3. 選擇 repo。
4. 提供安裝依賴和執行程式碼需要的 environment variables / secrets。
5. Cursor 安裝依賴並驗證程式碼能工作。
6. 儲存 VM snapshot，供未來 agents 複用。

這種方式適合先跑通。等環境複雜度升高，再遷移到 .cursor/environment.json（Cursor 環境描述檔案）和 Dockerfile（容器映象定義檔案，描述如何構建一個隔離的執行環境）。

4. Dockerfile setup

高階場景用 Dockerfile。注意官方邊界：

• 可以安裝 system dependencies、compiler versions、debuggers、base OS image。
• 不要 COPY full project；Cursor 會管理 workspace 並 checkout 正確 commit。
• 你配置 Dockerfile，但不能直接拿到 remote machine 的完整訪問權。

最小 .cursor/environment.json 示例：

{
  "build": {
    "dockerfile": "Dockerfile",
    "context": ".."
  },
  "install": "pnpm install && ./custom_script.sh"
}

路徑行為：

• build.dockerfile 和 build.context 相對 .cursor。
• install 從 project root 執行。
• schema 以官方 environment schema 為準。

5. Update、start 和 terminals

官方把新機器啟動過程拆成：

flowchart TD
  Base["Base environment / snapshot"] --> Update["update command / install"]
  Update --> Checkpoint["best-effort cached checkpoint"]
  Checkpoint --> Start["start command"]
  Start --> Terminals["configured terminals in tmux"]
  Terminals --> Agent["Cloud Agent run"]

Update command：

• 在 environment.json 中叫 install。
• 常見內容是 npm install、pnpm install、pip install、bazel build。
• 必須 idempotent，因為可能重複執行，也可能在部分快取狀態上執行。

Start command：

• 機器啟動後執行。
• 適合啟動 agent 執行期間需要常駐的服務。
• 如果需要 Docker daemon，可在 start 中加入 sudo service docker start。

Terminals：

• 用於 app code processes。
• 在你和 agent 共享的 tmux session 中執行。

6. AGENTS.md 雲端說明

Cloud Agents 會讀取 AGENTS.md。官方建議加一個專門章節，例如：

## Cursor Cloud specific instructions

- Install dependencies with pnpm install.
- Run tests with pnpm test -- --runInBand.
- Start the app with pnpm dev.
- Do not modify .env files.

如果內容變長，就把詳細任務說明拆到其他檔案，再在 AGENTS.md 引用。

這部分很關鍵：Cloud Agent 沒有你本機的隱性習慣，必須把安裝、測試、啟動、禁止動作和驗收寫清楚。

7. Secrets 和環境變數

推薦使用 Cursor Settings 的 Secrets tab 管理 secret。官方說明 secrets：

• KMS encrypted at rest。
• 作為 environment variables 暴露給 Cloud Agents。
• workspace / team scoped。

Redacted secrets 額外提供：

• 掃描 agent commits，防止 secret 被提交。
• 在 tool call results 中 redact，避免暴露給 agent 或 chat transcript。

不要把 .env.local 放進 snapshot。官方說明如果建立 snapshot 時包含 .env.local，它可能被儲存；安全上仍推薦 Secrets tab。

8. 登入、2FA 和 monorepo

如果 app 需要登入，把本地使用的 username、email、password 作為 secrets 提供。

如果登入流使用 TOTP-based 2FA，可以把 TOTP shared/root secret 作為 secret，agent 可用 oathtool 生成當前 6 位驗證碼。

Monorepo 有多個 .env.local 時：

• 把所有 app 需要的 values 放到同一個 Secrets tab。
• key 重名時用唯一字首，例如 NEXTJS_*、CONVEX_*。
• 每個 app 再引用對應變數。

9. AWS IAM 和 build secrets

Cursor 支援 Cloud Agents assume customer-provided IAM roles。核心思路是：提供 IAM role ARN，讓 Cursor 使用 external ID 和 STS 臨時憑據，而不是長期 AWS key。

官方會設定：

• AWS_CONFIG_FILE
• AWS_PROFILE=cursor-cloud-agent
• AWS_SDK_LOAD_CONFIG=1

STS credentials 會過期並重新整理。企業接 AWS 時，優先用 IAM role，而不是長期寫入 AWS_ACCESS_KEY_ID。

Dockerfile build secrets 可在 Cloud Agents dashboard 配置 team-level build secrets，並透過 Docker secret mount 在 build step 使用。它們只作用於 build step，不傳給執行中的 agent environment。

10. Docker 和 Tailscale

Docker：

• 簡單 Docker workflows 通常可行。
• 複雜 Docker setup 可能需要 fuse-overlayfs、iptables-legacy 和 docker group 配置。
• 需要 Docker daemon 時在 start 裡啟動服務。

Tailscale：

• 預設 networking mode 不適合 Cloud Agent VMs。
• 使用 userspace networking mode。
• 配合 HTTP / SOCKS proxy 環境變數。
• VM 不能作為 tailnet exit node。

本章自檢

完成本章後，用這 3 個問題檢查自己是否真正理解：

1. .cursor/environment.json、personal config、team config 的優先順序是什麼？
2. 為什麼 update command 必須 idempotent？
3. 為什麼 Secrets tab 比 snapshot 裡的 .env.local 更適合管理 secret？

透過標準：你能為一個 Node monorepo 寫出 Cloud Agent setup plan，包括 install、start、secrets、AGENTS.md 和驗證命令。

官方來源

• Cursor Cloud Agent Setup —— 官方 environment options、resolution order、Dockerfile、update/start、AGENTS.md、secrets、AWS IAM、Docker 和 Tailscale。
• Cursor AGENTS.md Rules —— 官方 AGENTS.md 背景。
• Cursor Cloud Agent Capabilities —— 官方 Cloud Agent 能力背景。

接下來去哪