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 能力背景。

接下来去哪