在 sandbox 中运行 Cursor Cloud Agents

通过自托管机器 ↗ 在 Cloudflare 上运行 Cursor Cloud Agents。分配给该部署的每个 Cursor session 都在自己的 Linux sandbox 中运行：由一个 Durable Object 为该 session 启动的 Container。

Cursor 托管 Agent 循环、推理和规划。Cloudflare 在你控制的基础设施中运行命令、文件编辑、仓库操作和其他工具。

前提条件

你需要：

已开启自托管机器的 Cursor Enterprise 计划
具有 agent 范围的 Cursor 团队服务账户 API key
可访问 Containers 和 R2 的 Cloudflare Workers 付费账户
Node.js 20 ↗ 或更高版本
用于部署和本地开发的正在运行的 Docker ↗ daemon

配置 Cursor 团队 pool

要创建团队 pool，请在 shell 中设置 CURSOR_API_KEY。然后使用 Cursor Agent CLI 启动本地 worker：

CURSOR_API_KEY="$CURSOR_API_KEY" agent worker --pool cloudflare-test start

该命令会注册 pool，并暂时将你的本地机器作为 worker 连接。pool 出现在 Cursor 中后，用 Ctrl+C 停止 worker，并运行 unset CURSOR_API_KEY。记录 pool 名称以用于 CURSOR_POOL。测试 Cloudflare 部署时请保持本地 worker 停止，以免它领取 Agent 请求。

更多信息请参阅 Cursor team pools ↗。

部署模板

该模板会部署 Worker、Durable Object 命名空间、container 应用、R2 bucket 绑定以及 cron 触发器。

克隆模板并安装依赖：

git clone https://github.com/anysphere/cloudflare-workers.git
cd cloudflare-workers
npm install

登录你的 Cloudflare 账户：
```
npx wrangler login
```
创建用于可选仓库 snapshot 的 R2 bucket：
```
npx wrangler r2 bucket create cursor-pool-worker-snapshots
```
若要使用其他 bucket 名称，请更新 wrangler.jsonc 中的 bucket_name。
将所需的 Cursor 服务账户 key 存储为 Worker secret：
```
npx wrangler secret put CURSOR_API_KEY
```
输入具有 agent 范围的团队服务账户 key。个人 API key 无法用于 pool worker。
要访问私有仓库，请将 Git 凭据存储为 Worker secret：
```
npx wrangler secret put GIT_USERNAME
npx wrangler secret put GIT_TOKEN
```
对于 GitHub，将 GIT_USERNAME 设为 x-access-token。将 GIT_TOKEN 设为可访问 Agent 所用仓库的 token。
在 wrangler.jsonc 中，将 vars.CURSOR_POOL 设为 Cursor 团队 pool 名称：
```
{
  "vars": {
    "CURSOR_POOL": "default"
  }
}
```
将 containers[].max_instances 设为部署必须支持的最大并发 session 数。
部署 Worker 和 container：
```
npx wrangler deploy
```
Wrangler 会构建镜像并部署 Worker、Durable Object、container 应用和 cron 触发器。

新的 container 镜像滚动发布会停止正在运行的 container。部署更新前，请等待活动的 Cursor session 完成。

运行绑定仓库的 Agent

绑定仓库的 Agent 会按 Git remote 和团队 pool 名称路由工作。

前往 Cursor Cloud Agents ↗。
启动 Agent 并选择仓库。
选择 Self-hosted，然后选择 CURSOR_POOL 中配置的名称。
等待 Cursor 将会话分配给该部署。然后 Worker 会为该 session 启动 container。首次计划的 controller 运行最多可能需要五分钟才开始。

请求会提供仓库 URL。container 会将该仓库恢复或克隆到 $HOME/workspaces/repo-0。然后它会启动 Cursor worker：

agent worker --worker-dir "$HOME/workspaces/repo-0" --pool "$CURSOR_POOL" start --verbose

Cursor worker 会从 Git remote 派生其仓库标签。不要手动配置 repo= 标签。

运行任意仓库 Agent

任意仓库 Agent 按团队 pool 名称路由工作。它们从一个空工作目录开始，且没有 Git remote。

前往 Cursor Cloud Agents ↗。
启动 Agent 并选择 Any repo 组。
选择 CURSOR_POOL 中配置的团队 pool 名称。

container 会创建没有 Git remote 的 $HOME/workspaces/repo-0。Agent 或项目 hook 可以在 session 期间克隆仓库。

配置仓库 snapshot

仓库 snapshot 是绑定仓库 Agent 的可选缓存。snapshot 会将克隆后的工作树存储在 R2 中。任意仓库 Agent 不会使用此缓存。

存储用于保护 snapshot 路由的 secret：

npx wrangler secret put SNAPSHOT_AUTH_TOKEN

在 wrangler.jsonc 中，将 vars.WORKER_PUBLIC_URL 设为已部署的 Worker URL：

{
  "vars": {
    "CURSOR_POOL": "default",
    "WORKER_PUBLIC_URL": "https://cursor-pool-workers.<ACCOUNT_SUBDOMAIN>.workers.dev"
  }
}

部署更新后的配置：
```
npx wrangler deploy
```

缓存未命中时会执行普通 Git clone。这不会阻止 Agent 启动。

模板如何工作

该模板为每个已分配的 Cursor session 管理一个 container。

cron 触发器每五分钟运行一次 Worker。每次运行会列出等待 CURSOR_POOL 的 session。然后该运行会保持来自 Cursor 的 server-sent events 流打开，直到下一次运行即将开始，因此 Worker 也会收到两次运行之间到达的 session。

Worker 会使用唯一的 worker ID 领取每个 session。然后 Cursor 只会将该 session 分配给该 Worker。该 session 的 Durable Object 会使用 session 环境和仓库信息启动一个 container。

container 会在五分钟无工作后停止，如果你设置了 WORKER_IDLE_RELEASE_TIMEOUT_SECONDS 则使用该值。Durable Object 也会在八小时后停止 container，如果你设置了 MAX_RUN_LIFETIME_SECONDS 则使用该值。

container 会主动连接到 Cursor，因此不需要入站端口或公网 IP 地址。Worker 只暴露其健康检查路由和可选的 snapshot 路由。

安全

每个 session 都在自己的 container 中运行，不会与其他 session 共享文件或进程。container 会收到 CURSOR_API_KEY 服务账户 key。如果你设置了 GIT_USERNAME、GIT_TOKEN 和 SNAPSHOT_AUTH_TOKEN，它也会收到这些值。在 session 中运行的代码可以读取这些值。请仅向 GIT_TOKEN 授予 Agent 所用仓库的访问权限。

更多信息请参阅 Sandbox 安全。

监控部署

要流式查看 controller 和 container 日志，请运行：

npx wrangler tail

如需列出容器实例，请先找到容器应用的 ID，然后列出其实例：

npx wrangler containers list
npx wrangler containers instances <APPLICATION_ID>

要在本地开发期间测试一次计划的 controller 运行，请使用 scheduled-event 测试启动 wrangler：

npx wrangler dev --test-scheduled

在另一个终端中调用计划路由：

curl "http://localhost:8787/cdn-cgi/local/scheduled?cron=*/5+*+*+*+*"

如果更改 cron 间隔，请同时更新 wrangler.jsonc 中的 triggers.crons 和 src/config.ts 中的 CONTROLLER_RUN_BUDGET_MS。

故障排除

现象	原因	解决方法
没有 session 被分配	cron 未运行、key 缺失，或团队 pool 名称不匹配	运行 `npx wrangler tail`。检查 controller 运行、`401` 响应以及配置的团队 pool 名称。
controller 返回 `401`	key 是个人 key 或缺少 agent 范围	将 `CURSOR_API_KEY` 替换为具有 agent 范围的团队服务账户 key。
某个仓库没有团队 pool	worker 启动时没有仓库标签	选择 Any repo，或使用已配置的 Git remote 启动绑定仓库的 Agent。
session 已分配但不启动	container 无法启动、无法克隆仓库或无法认证	运行 `npx wrangler containers list` 并检查 `npx wrangler tail`。检查容量和 Git secrets。
container 以 `Error: Container exited with unexpected exit code: 1` 退出，且更早的日志报告 `cursor-agent CLI not found on PATH`	Cloudflare WARP 或其他 TLS 检查代理可能阻止 Docker 下载 Cursor CLI。未加保护的 shell 管道可能隐藏安装失败并产生不完整镜像。	运行 `npx wrangler tail` 并检查之前的 container 日志。如果缺少 Cursor CLI，请断开 WARP、清除 Docker 构建缓存，然后再次运行 `npx wrangler deploy`。或者配置 Docker 信任你组织的根证书。
首次仓库启动很慢	snapshot 缓存为空或未配置	同时配置 `WORKER_PUBLIC_URL` 和 `SNAPSHOT_AUTH_TOKEN`，或允许冷 Git clone。