---
title: "Cloud Agent Setup"
description: "配置 Cloud Agent 的 Ubuntu VM、environment.json、update/start、secrets、Docker 和 Tailscale。"
verifiedAt: "2026-05-09"
---

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

> [!NOTE]
> **閱讀目標**：讀完本章，你應該能為一個 repo 設計 Cloud Agent 環境：依賴怎麼裝、secret 怎麼管、update/start 怎麼寫、Dockerfile 何時需要。

## 1. 兩種環境配置方式

官方給出兩條主路徑：

| 方式 | 適合 |
| --- | --- |
| Agent-driven setup | 推薦起步路徑，讓 Cursor 在 `cursor.com/onboard` 幫你配置 |
| Dockerfile manual setup | 高階場景，需要系統依賴、特定編譯器、debuggers 或 OS image |

兩種方式都可以生成環境，並設定 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](https://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` 示例：

```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

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

```mermaid
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`。官方建議加一個專門章節，例如：

```markdown
## 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。

<details>
<summary>深讀：update script 裡不要放什麼</summary>

不要把很少執行但很重的工作都塞進 update script，例如啟動多個服務、構建大型 Docker images、跑全量 E2E。

update 的價值是快取基礎依賴。具體任務需要什麼服務和測試，寫進 AGENTS.md 或任務 prompt，讓 agent 按需啟動和驗證。
</details>

## 本章自檢

完成本章後，用這 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](https://cursor.com/docs/cloud-agent/setup.md) —— 官方 environment options、resolution order、Dockerfile、update/start、AGENTS.md、secrets、AWS IAM、Docker 和 Tailscale。
- [Cursor AGENTS.md Rules](https://cursor.com/docs/rules.md#agentsmd) —— 官方 AGENTS.md 背景。
- [Cursor Cloud Agent Capabilities](https://cursor.com/docs/cloud-agent/capabilities.md) —— 官方 Cloud Agent 能力背景。

## 接下來去哪

<Cards>
  <Card title="Cloud Agent Capabilities" description="繼續學習 computer use、artifacts、remote desktop、MCP 和 CI autofix。" href="/zh-Hant/docs/cursor/official/04-cloud-agents/52-capabilities" />
  <Card title="Cloud Agent 總覽" description="回到啟動入口和 repo 工作方式。" href="/zh-Hant/docs/cursor/official/04-cloud-agents/50-cloud-agent" />
</Cards>
