---
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="/docs/cursor/official/04-cloud-agents/52-capabilities" />
  <Card title="Cloud Agent 总览" description="回到启动入口和 repo 工作方式。" href="/docs/cursor/official/04-cloud-agents/50-cloud-agent" />
</Cards>
