《Cursor文档》-团队用量池

用量池是一个具名的路由目标，用于将请求与 自托管机器 worker 连接起来。请求会在用量池中等待，直到有可用的 worker 认领。可为不同的执行环境创建各自的用量池，例如为需要 GPU 的工作创建 gpu，为需要 Mac 的工作创建 ios。

团队用量池适用于希望让云端代理运行在公司自有基础设施中的企业版团队。管理员无需让每位开发者都在个人机器上启动一个 worker，而是统一运营一个 worker 用量池，供整个组织内的智能体分配使用。

用量池是一种基础设施归属方式，不会将智能体循环移出 Cursor 云。worker 会在你的基础设施中执行终端命令、文件编辑、浏览器操作和其他工具调用，而 Cursor 负责协调、模型访问以及云端代理体验。

对大多数团队来说，Cursor-managed Cloud Agents 都是推荐方案，包括需要
私有网络访问的团队。在决定自行维护 worker 工作器群 之前，请先考虑使用具备网络
控制的托管环境、Tailscale 或类似客户端，或针对受支持源代码控制方式的私有网络连接。请参阅 选择 Cloud Agents 的运行位置。

当你有以下需求时，请使用用量池：

• 为团队或组织集中管理 worker
• 使用服务账号身份验证，而不是个人浏览器登录
• 需要 Kubernetes、自动扩缩容或集中管理的容量
• 使用标签将工作路由到正确的环境、团队、仓库或硬件配置
• 使用公司自有主机执行工具调用、生成构建产物，并记录 worker 日志和进行监控

如需快速完成个人配置，请参阅 我的机器。有关用量池所需的套餐、凭据、仪表盘设置和机器依赖项，请参阅自托管机器概览中的 要求。

工作原理¶

worker 会向 Cursor 云建立一个长期保持的出站 HTTPS 连接。智能体循环 (包括推理和规划) 在 Cursor 云中运行，并通过该连接发送工具调用。worker 会在你的基础设施中执行这些工具调用：终端命令、文件编辑、浏览器操作，以及对内部服务的访问。

你的仓库、构建缓存、机密信息和工具执行都会保留在你的环境中，而 Cursor 负责协调、模型访问以及云端代理体验。云端代理的产物 (如截图和视频) 会上传到 Cursor，以便你在 PR 和仪表盘中查看。

worker 只需要出站访问。无需入站端口、公共 IP 或 VPN 隧道。所需主机的完整列表，请参阅网络。

自托管机器支持每位用户最多 200 个 worker、每个团队最多 1000 个。若需更大规模的公司级部署，请联系我们讨论伸缩方案。

前提条件¶

• 已开通 Cursor 企业版方案
• 由团队管理员在 Cloud Agents 仪表盘 中配置自托管设置：
• 允许自托管机器 允许用户启用自托管运行。
• 要求自托管机器 会将每次 Cloud Agent 运行都路由到自托管 worker。
• 用于用量池 worker 身份验证的 服务账户 API 密钥
• 满足以下条件的 worker 机器或镜像：
• 已安装 agent 命令行界面
• 已安装 git，且可在 PATH 中使用 (当 worker 需要处理 git remote 或使用 --clone-git-repos 时为必需；若由你自己的脚本处理 SCM，则对 任意代码仓库用量池 而言为可选)
• 一个 workspace 目录 (已克隆并配置了 remote 的代码仓库，或一个 any-repo 目录)
• 可访问智能体所需的构建工具、包注册表、机密信息和内部服务

安装命令行界面¶

# macOS、Linux 和 WSL
curl https://cursor.com/install -fsS | bash

# Windows PowerShell
irm 'https://cursor.com/install?win32=true' | iex

确认 CLI 可用：

agent --version

worker 身份认证¶

用量池 worker 必须使用 服务账户 API 密钥 进行认证。

用户、个人、团队和组织 API 密钥都不能启动用量池 worker。个人 worker 请在 我的机器 中使用个人或用户 API 密钥。

export CURSOR_API_KEY="your-service-account-api-key"

也可以直接传入密钥：

agent worker --api-key "your-service-account-api-key" start

启动一个用量池 worker¶

在其要服务的 workspace 中运行该 worker (可以是 git 仓库 root，或一个 any-repo 目录)：

cd /path/to/repo
agent worker --pool start

--pool 会将 worker 注册为可供用量池分配。可传入一个可选名称以加入具名用量池 (例如 --pool gpu)。省略名称时，worker 会加入 default。每个云端代理会话一次只会占用一个 worker。

对于编排环境，请将其与 --idle-release-timeout 结合使用，以便进程在工作完成后正常退出：

agent worker --pool gpu --idle-release-timeout 600 start

--idle-release-timeout 会在会话结束后的一段时间内 (以秒为单位) 让 worker 继续保持运行，以处理后续消息。默认值为 3600 秒。有关释放与重新连接的工作方式，请参阅会话生命周期。

启用计算机使用¶

传入 --computer-use，让已认领的 agents 可以在 worker 上进行点击、输入、截屏以及操作应用：

agent worker --pool gpu --computer-use start

在 macOS 上，首次启动会安装 Cursor Computer Use 辅助应用。为其授予辅助功能和屏幕录制权限，用一个截屏任务进行验证，然后为该机器创建快照，这样从该镜像恢复的每个 worker 都可直接使用。在 Linux 上，请将桌面端软件包打包进 worker 镜像。macOS 权限步骤、MDM 配置文件指南以及 Linux 显示选项，参见计算机使用与桌面共享。

注册多个仓库根目录¶

自托管多仓库支持可在 worker 启动时通过注册多个工作区根目录进行配置。为每个本地仓库根目录各传递一次 --worker-dir。第一个根目录会作为主代码仓库，用于分配标识和仪表盘显示。所有根目录都会暴露给智能体运行时，而具有有效 git origin 的根目录会注册代码仓库路由元数据。

--worker-dir`` 最多可重复指定 20 个路径。每个路径都必须已存在且为目录。如果未传递–worker-dir`，CLI 会使用当前工作目录。

开始前，请先在 Dashboard > Cloud Agents > Self-Hosted 中启用自托管 workers。除非你自己的机器镜像能保证其他可写位置，否则请使用 $HOME 下的可写路径。

示例设置：

export WORKER_ROOT="$HOME/cursor-repos/my-org"
mkdir -p "$WORKER_ROOT"

git clone git@github.com:my-org/app.git "$WORKER_ROOT/app"
git clone git@github.com:my-org/infra.git "$WORKER_ROOT/infra"

export CURSOR_API_KEY="<key>"

启动 worker 前，先运行预检：

agent worker \
  --pool app-infra \
  --name app-infra-worker \
  --worker-dir "$WORKER_ROOT/app" \
  --worker-dir "$WORKER_ROOT/infra" \
  debug --json

使用相同根目录启动 worker：

agent worker \
  --pool app-infra \
  --name app-infra-worker \
  --worker-dir "$WORKER_ROOT/app" \
  --worker-dir "$WORKER_ROOT/infra" \
  start --verbose

将 worker 选项放在 start 或 debug 之前。让该进程在 systemd、tmux、launchd、Kubernetes 或你自己的进程管理器等监管程序下持续运行。

详细的启动日志是判断已注册根目录的权威依据。成功的 multi-repo worker 会显示每个派生仓库的标签、工作区路径以及代码仓库 URL：

repo=my-org/app
repo=my-org/infra
workspacePaths: [app, infra]
x-repository-urls: ["git@github.com:my-org/app.git","git@github.com:my-org/infra.git"]

仪表盘当前会在其主仓库下显示一个自托管 worker。
门户中目前还没有具名的自托管多仓库环境对象。
这可能会让人觉得只有第一个仓库已注册。请检查详细日志中的 workspacePaths
和 x-repository-urls 以确认所有根目录。若要让另一个
仓库成为主仓库，请将它的 --worker-dir 放在最前面。

使用 --name 和 --pool <name>，让多仓库 worker 在仪表盘和触发器中更容易识别。

在用量池模式下，一次只有一个云端代理会占用该 worker。不使用 --pool 时，则允许共享分配。需要为编排器提供 /healthz、/readyz 和 /metrics 时，请在 start 前添加 --management-addr 0.0.0.0:8080。

非 git 目录也可以作为执行根目录，但它们不会提供仓库路由元数据。智能体所需的所有仓库都必须在进程启动前完成克隆，且 worker 能够访问。worker 进程还需要具备对每个根目录的文件系统和 SCM 访问权限。

任意代码仓库用量池¶

用量池有两种仓库配置。repo-backed 用量池会将用量池绑定到一个或多个仓库：请求带有 repo=<owner/repo> 标签，匹配服务该仓库的 worker，并在仪表盘中显示在对应代码仓库下。any-repo 用量池则将源代码控制交由你自行处理：请求仅按用量池名称匹配，且该用量池在仪表盘中显示在 Any repo 下。

如果你希望自行管理源代码控制，可以创建一个不绑定仓库的用量池。pool worker 不需要 git remote。如果你希望由智能体 (或你自己的 image、钩子和脚本) 来管理克隆和 git 状态，只需将 --worker-dir 指向任意已有目录即可：

mkdir -p "$HOME/cursor-sandboxes/default"
agent worker --pool sandbox --worker-dir "$HOME/cursor-sandboxes/default" start

在该目录中添加 .cursor/rules 文件，以告知 Cursor 这些机器上有哪些目录和工具可用。

若要让 worker 在 claim 时克隆所 claim 智能体的仓库，请传入 --clone-git-repos。该行为需显式启用 (opt-in) ，默认的 any-repo 行为不会执行克隆。

agent worker --pool sandbox --clone-git-repos start

--clone-git-repos 隐含 --mint-github-token。clone 会使用签发出的短期 GitHub token。团队管理员必须为 Team Pool worker 启用 GitHub token 签发，且 git 必须在 PATH 中。

此 flag 仅可用于任意代码仓库用量池 worker：即非 default 的具名 --pool，且未绑定代码仓库 (repo=) 、未绑定机器 (name=) 。若用于已绑定代码仓库的 worker、具名机器、default 用量池或个人 我的机器 worker，CLI 会报出明确错误并退出。

分支名通过 --branch 进行 clone。完整的 40 字符 commit SHA 会在 clone 后执行 detached checkout。请使用 HTTPS 形式的 GitHub remote，以便签发的 token 能够完成认证。

若 clone 失败，请求会继续留在队列中。操作者只会看到通用的 clone 失败信息。

--clone-git-repos、--mint-github-token 和 --sync-dashboard-secrets 均假定每个容器或操作系统用户只运行一个 worker。不支持在同一用户下同时部署多个已启用凭据的 worker。

任意代码仓库用量池不带 repo= 路由标签。针对这类用量池启动 agents 时，将 env.type 设为 "pool"、env.name 设为用量池名称，并省略 repos (参见 Create An Agent) 。在 cursor.com/agents 的 Any repo 下选择该用量池。

管理用量池¶

用量池是持久的。即使最后一个 worker 断开连接，用量池依然保持注册状态且可被选择，因此你可以缩容到零，等请求到来时再恢复容量。用新的用量池名称启动 worker 会隐式创建该用量池。也可以通过 Cloud Agents API 提前管理用量池：

• POST /v0/private-workers/pools：在任何 worker 连接之前预先注册用量池。若为 repo-backed 用量池，需包含 repoOwner、repoName 和 repoUrl；若为 any-repo 用量池，则省略这些字段。
• GET /v0/private-workers/pools：列出用量池，并显示已连接和使用中的 worker 数量。
• DELETE /v0/private-workers/pools：软删除用量池，不会影响当前已连接到该用量池的机器。

可借助 List Pools 和待处理请求判断何时重新扩容 worker。

用量池名称¶

当你希望将会话路由到特定子集 (例如 GPU 机器、预发布环境机器组或团队专用的构建机器) 时，可以按名称对用量池中的 worker 进行分组。

将名称传给 --pool：

agent worker --pool gpu start

如果省略名称，worker 会加入 default 用量池。较早的 CLI 版本仅支持 boolean 类型的 --pool 加上独立的 --pool-name，这些版本仍可继续使用；--pool-name 是 --pool <name> 的已弃用别名。

当 orchestrator 注入 config 时，可以从 environment 设置用量池名称：

export CURSOR_WORKER_POOL_NAME=gpu
agent worker --pool start

可复用的 worker (启动时未加 --pool) 不属于任何用量池。

启动会话或编辑自动化时，可在 Cloud Agents 仪表盘 的 worker 选择器中选择一个用量池。你也可以在 Slack、GitHub 或 Linear 触发器中添加 pool=<name>。会话只会路由到以该用量池名称注册的 worker。

触发用量池代理¶

当你希望云端代理在团队共享的 worker 工作器群 上运行时，请使用用量池触发器。对于集中管理的容量、自动扩缩容、类 CI runner 以及仓库范围的基础设施，用量池 worker 是合适的目标。

团队管理员可在 Cloud Agents 仪表盘 的“自托管”部分控制自托管路由。允许自托管机器允许用户按请求启用自托管。不启用时，运行会使用 Cursor 的托管基础设施。要求自托管机器会将云端代理 run 路由到自托管 worker。

当 Cursor 启动一个用量池代理时，会根据标签匹配 workers。每个用量池请求都包含一个 repo=<owner/repo> label。发往指定名称用量池的请求还会包含 pool=<name>。

用量池 workers 会处理：

• 受 要求自托管机器 约束的运行，除非请求通过 worker= 或 machine= 指定了某个特定的“我的机器” worker
• 带有 self_hosted=true、self_hosted 或 selfhosted 的请求
• 带有 pool=<name> 的请求，这也会选中对应的命名用量池
• 从触发表面进行代码仓库选择的自托管请求，例如在支持的情况下使用 repo=<owner/repo>

repo= 用于为 run 选择代码仓库。对于团队用量池运行，该代码仓库会成为 repo=<owner/repo> worker 标签。它不会指向个人机器。

通过集成使用以下选项来启动用量池代理：

• Slack：提及 @Cursor，并附带 self_hosted=true、单独的 self_hosted、selfhosted 或 pool=<name>。旧版别名如 private_worker=true、useprivateworker 和 useprivateworkers=false 仍然可用。
• GitHub：在 issue、PR 或评审评论中评论 @cursoragent self_hosted=true ... 或 @cursoragent pool=<name> ...。旧版 private_worker=true 别名仍然可用。
• Linear：在 issue 正文中添加 pool=<name> 或 [pool=<name>]。你也可以使用 issue 或项目标签，其中父标签为 pool，子标签为对应的值。Linear 不会解析单独的 self_hosted=true。

策略处理取决于请求从哪里发起：

• Slack：当“允许自托管机器”关闭时，会拒绝自托管启用请求，并在 Slack 中回复。如果“要求自托管机器”开启，则每次 Slack 提及都会以自托管方式运行。
• GitHub：代码仓库中的 OWNER 和 COLLABORATOR 用户可以将运行路由到自托管 workers。其他评论者在启用时会在托管基础设施上运行；如果“要求自托管机器”已开启，则会被跳过。这样可以保护公共仓库，避免外部贡献者通过评论触发运行。
• Linear：当“允许自托管机器”关闭时，会拒绝显式的自托管请求。该 issue 会收到一条代理活动错误，提示管理员开启自托管 workers，或移除该提示以改为在 Cursor 的托管基础设施上运行。

若要按名称定位到你自己的某台机器，请使用我的机器并配合 worker= 或 machine=。

Cloud Agent API 使用相同的解析器以及 usePrivateWorker 和 labels 字段。有关端点详情，请参阅 Cloud Agent API 文档。

Hooks¶

自托管机器 worker 会在云端代理会话期间运行基于命令的钩子，并从该 worker 所服务的工作区中加载配置。

• 项目 hooks。 将 .cursor/hooks.json 及其引用的脚本提交到 worker 所用的代码仓库或工作区目录中，即 git checkout、--worker-dir 根目录，或你为 any-repo pool 传入的目录。
• 团队和企业级管理的 hooks。 在企业版中，worker 还会运行在网页仪表盘中配置的钩子。

Hooks 参考文档介绍了 schema、事件和示例。Cloud agent 支持列出了 Cloud Agent 循环会运行哪些事件。

以下 Cloud Agent 限制同样适用于这些执行工具的 worker：

• 仅支持基于命令的钩子。 基于提示的钩子不会运行。
• 不支持仅限 IDE 的钩子。 Tab 钩子 (beforeTabFileRead、afterTabFileEdit) 和 workspaceOpen 不会在 worker 上运行。

sessionStart 和 sessionEnd 会在自托管机器 worker 上运行：当云端代理会话认领该 worker 时以及该认领被释放时触发。Cursor 托管的 Cloud Agents 会跳过这些钩子。

Kubernetes 及其他编排平台上的 worker 使用相同的钩子模型。

标签¶

标签是用于描述 worker 的键值对。它们决定云端代理会话会被路由到哪个用量池。

CLI 标志¶

适合快速测试或小型用量池：

agent worker \
  --pool \
  --label team=backend \
  --label env=production \
  start

JSON 文件¶

更适合生产环境，此时标签通常作为配置来管理：

{
  "team": "backend",
  "env": "production",
  "capabilities": ["docker", "gpu"]
}

agent worker --pool --labels-file labels.json start

TOML 文件¶

与 JSON 相同，只是格式不同：

team = "backend"
env = "production"
capabilities = ["docker", "gpu"]

agent worker --pool --labels-file labels.toml start

环境变量¶

当路径由编排器注入时，这种方式很有用：

export CURSOR_WORKER_LABELS_FILE=/path/to/labels.json
agent worker --pool start

repo 和 pool 标签为保留项。repo 在存在时来自 worker 目录的 Git remote。pool 由 --pool 设置。不要手动设置其中任一项。

MCP 服务器¶

自托管 workers 上的 MCP 服务器会按传输方式路由：

如果你的 MCP 服务器需要访问私有网络中的端点，请使用命令 (stdio) 传输方式。该进程会直接在 worker 上运行，并共享其网络环境。对于基于 HTTP 的 MCP 服务器，Cursor 会通过其后端管理连接，并处理 OAuth 和会话缓存。

产物¶

产物在自托管 worker 和 Cursor 托管的智能体上的行为完全一致。智能体在 worker 内生成产物，再由 worker 通过 HTTPS 将其上传到 Cursor 管理的存储。所有下游内容 (PR 嵌入、仪表盘预览、通知附件) 都由 Cursor 的后端处理，不依赖 worker 运行在何处。

产物默认启用。有关其在 UI 中的显示效果，请参阅 能力。

要禁用产物上传，请阻止发往 cloud-agent-artifacts.s3.us-east-1.amazonaws.com 的出站流量。智能体会话会继续工作；但在该会话期间生成的产物将无法上传。

网络¶

worker 需要具备对以下地址的出站 HTTPS 访问权限：

• 用于智能体会话的 api2.cursor.sh 和 api2direct.cursor.sh
• 用于命令行界面更新以及在 macOS 上首次安装 Cursor Computer Use 的 downloads.cursor.com
• 用于上传产物的 cloud-agent-artifacts.s3.us-east-1.amazonaws.com

如果你的防火墙只能匹配通配符，*.s3.us-east-1.amazonaws.com 可以覆盖该产物主机，但也会同时开放该区域中的所有其他存储桶。若防火墙支持，建议优先使用精确主机规则。

不需要入站端口、公网 IP 或 VPN 隧道。如果你使用代理，请在 worker 环境中设置 HTTPS_PROXY 或 https_proxy。

失效情况¶

先决条件 部分介绍了 worker 在智能体运行期间需要访问的更多主机 (Git 主机、包注册表、内部 API) 。

在 Kubernetes 上部署¶

如果希望由平台来负责调度、健康检查和 Pod 生命周期，可以在 Kubernetes 上运行用量池 worker。可以从 anysphere/k8s-workers 开始：这是一个 Helm 示例，用于在你的集群中以 --spawn 方式运行 worker 控制器。spawn 钩子会为每个已认领的请求创建一个 worker Pod，或者由控制器通过 --warm-idle 保持空闲的热备 Pod。无需 CRD。

Cursor Kubernetes operator 和 WorkerDeployment Helm chart 已弃用。如果你的集群已经在运行
operator，它仍可继续工作，operator 参考也仍然可用。新的
Kubernetes 部署应使用 k8s-workers 模板。

其他主机的运行方式也一样：任何能安装 Cursor 命令行界面、并可通过出站 HTTPS 访问 Cursor 的 VM、容器或裸金属机器，都可以在 systemd、Docker 或你自己的进程管理器下运行用量池 worker。如需查看涵盖 AWS Lambda、Cloudflare、Namespace、Modal、Daytona、E2B、Vercel 和 Coder 的合作伙伴指南与参考模板，请参阅 Integrations。

Worker controller¶

agent worker controller 通过 --spawn 钩子启动 worker。该钩子可以派生进程、启动容器，或像 k8s-workers 模板那样创建 Kubernetes Pod。--warm-idle 是预热容量路径：controller 会为每个缺失的空闲 worker 运行一次钩子，而不是修改 Deployment 或 HPA。WorkerDeployment.spec.readyReplicas 属于已弃用的 Kubernetes operator；只有已经在运行它的集群才需要该控制方式。

--spawn <path> 为必填项。该钩子在成功认领后运行一次，或为每个缺失的预热 worker 运行一次。钩子环境包含 CURSOR_API_KEY、CURSOR_API_URL、CURSOR_API_ENDPOINT、CURSOR_AGENT_WORKER_ID 以及请求字段。请通过 --api-key 或 CURSOR_API_KEY 使用服务账户密钥进行身份验证。该密钥会绑定所属团队，不使用会话登录。

spawn 钩子所需的全部信息均以环境变量形式提供：

spawn 钩子应使用相同的 worker ID 启动 worker：

#!/usr/bin/env bash
set -euo pipefail
agent worker --pool "$CURSOR_POOL" --worker-id "$CURSOR_AGENT_WORKER_ID" start

worker CLI 也会从环境变量中读取 CURSOR_AGENT_WORKER_ID，因此启动容器的 spawn 钩子可以改为直接传入这些变量：

#!/usr/bin/env bash
set -euo pipefail

docker run -d \
  -e CURSOR_API_KEY \
  -e CURSOR_AGENT_WORKER_ID \
  -e CURSOR_WORKER_POOL_NAME="$CURSOR_POOL" \
  your-worker-image \
  agent worker --pool start

Claim-then-spawn¶

默认模式。controller 会列出待处理请求，监听 GET /v0/private-workers/pending-requests/stream，逐个 claim 请求，并为每次 claim 执行一次 --spawn。

agent worker controller --spawn ./spawn.sh --api-key "$CURSOR_API_KEY" --pool gpu --pool default

Warm pool¶

--warm-idle <count> 会预先启动 unclaimed worker，从而在每个 --pool 中保持 <count> 个空闲 worker 处于连接状态。它不会调用 claim。Cursor 会将排队中的 agents 分配给这些 warm worker。

controller 每 60 秒对 GET /v0/private-workers/pools 执行一次 reconcile。pending-requests SSE stream 仅用于加快 backfill 速度。

Warm mode 必须指定 --pool，且不能与 --all-pools 同时使用。每个 pool 只运行一个 warm controller：服务器端没有 spawn 租约机制，多个 controller 并发运行时可能会短暂启动过多 worker。

agent worker controller --spawn ./spawn.sh --api-key "$CURSOR_API_KEY" --pool gpu --warm-idle 5

若想改为构建自定义 controller，请使用 Cloud Agents API。

会话生命周期¶

一旦某个 worker 与请求匹配成功，Cursor 会将所有智能体工具调用直接转发到该机器。连接的空闲超时默认为 1 小时，可按需配置：

agent worker --pool my-pool --idle-release-timeout 600 start

--idle-release-timeout (环境变量 CURSOR_WORKER_IDLE_RELEASE_TIMEOUT) 表示会话结束后 worker 保持连接、等待后续消息的秒数。若收到后续消息，计时器会重置。超时触发时，CLI 以退出码 0 退出，便于管理进程回收该机器。传入 0 可禁用基于空闲的释放。释放 claim 是另一个独立的 API：它只是不再为该智能体优先选择该机器，并不会退出 worker CLI。

worker 超时后，Cursor 会将其标记为已释放，该机器可以重置并重新进入用量池。如果用户重新启动一个已与其机器断开连接的对话，该对话会连接到用量池中的一台新机器。除非用量池启用了休眠，否则原机器上的 workspace 状态不会延续。

休眠¶

智能体空闲时，用量池中的机器不必一直在线。会话结束后，worker 会等待后续请求，直到空闲超时触发；而在两轮之间让每台机器都保持运行，成本相当高。

这样做的代价是工作区不再就近可用。若不启用休眠，机器释放后到达的后续请求会重新从用量池获取容量：智能体会落到一台全新的机器上，最初几分钟可能都在重建它原本已有的工作区。启用休眠后，机器恢复时工作区完好如初，后续请求可从智能体中断处继续。

为用量池设置重新连接窗口¶

workerReadyTimeoutSeconds 控制 Cursor 在把请求分配给另一个 worker 之前，等待已认领机器重新连接的时长。默认值为 0：后续请求会立即重新获取容量。

curl --request POST \
  --url "https://api.cursor.com/v0/private-workers/pools" \
  -u "$CURSOR_API_KEY:" \
  --header 'Content-Type: application/json' \
  --data '{
    "scope": "team",
    "poolName": "gpu",
    "workerReadyTimeoutSeconds": 900
  }'

机器空闲时创建快照¶

缩短 worker 的 --idle-release-timeout，让机器在智能体空闲后尽快释放。当 worker 退出时 (空闲释放时退出码 0) ，或当 Get An Agent 报告 status 为 IDLE 时，为该机器创建快照并将其停止。

识别唤醒信号¶

当某个智能体收到后续请求，而其已认领的机器处于离线状态时，Cursor 会在重新连接窗口内等待，并把该请求作为“已认领但离线”的队列条目发布。你的 controller 有两种识别方式：List Pending Pool Requests 会返回带有 claimedWorkerId 和 wakeTimeoutMs 的条目；事件流则会发出包含相同字段的 claimed_offline 事件。

重新启动机器¶

在窗口到期前恢复快照，并以相同的 id 启动 worker：

export CURSOR_AGENT_WORKER_ID="<claimedWorkerId>"
agent worker --pool gpu start

后续请求会在该机器上继续执行，工作区完好如初。

无法恢复时释放认领¶

如果机器无法恢复，例如快照已丢失，请释放认领。请求会立即回到队列，由替代机器认领。如果不做任何处理，窗口也会自行到期：认领过期后，请求会作为未认领条目重新发布 (产生一个新的 created 事件) ，任何 worker 都可以处理。

构建你自己的 controller¶

内置 controller 能满足大多数配置需求。如果你需要自定义逻辑，例如自己的调度、配额或机器分配，可基于 Cloud Agents API 构建 controller。controller 需要做三件事：监听请求队列、认领请求，并为其启动 worker。这些端点同样可用于在 Kubernetes 之外监控利用率并实现自动伸缩。

使用用量池的服务账户 API 密钥，通过 Basic 认证或 Bearer token 进行认证。其他类型的 API 密钥无法管理用量池 worker 的容量。

监控请求队列¶

先列举一次队列，建立待处理请求的视图，然后通过 Server-Sent Events (SSE) 实时跟踪变化。

从 GET /v0/private-workers/pending-requests 开始。添加 ?pool=<name> 可只监视单个用量池。分页读取直至全部取完，并保留响应中的 streamCursor：

curl --request GET \
  --url "https://api.cursor.com/v0/private-workers/pending-requests?pool=my-pool&limit=50" \
  -u "$CURSOR_API_KEY:"

然后通过 GET /v0/private-workers/pending-requests/stream 打开事件流，传入该 streamCursor 及相同的筛选条件。随着事件不断到达，及时更新你的视图：收到 created 和 claimed_offline 事件时添加请求，收到 claimed 或 expired 事件时移除请求：

curl --request GET --no-buffer \
  --url "https://api.cursor.com/v0/private-workers/pending-requests/stream?pool=my-pool&cursor=$STREAM_CURSOR" \
  --header 'Accept: text/event-stream' \
  -u "$CURSOR_API_KEY:"

游标会在签发它的那次 list 请求之后五分钟过期。当 stream 返回 410 Gone 时，请重新执行 list，并用新的 streamCursor 重新打开 stream。更好的做法是：每五分钟 (加入少量抖动) 重新 list 一次，而不是等到出现 410。

视图中的请求数量即为该用量池的队列深度。数量上升时，请增加 worker。请把事件视为提示，把 list 结果视为 source of truth：事件投递是尽力而为的，每次重新 list 都会纠正偏差。完整的投递保证与游标规则请参阅 Watch Pending Pool Requests。

列出 workers¶

curl --request GET \
  --url "https://api.cursor.com/v0/private-workers?status=idle&scope=team_pool&limit=50" \
  -u "$CURSOR_API_KEY:"

Worker 包含 name、isInUse、连接元数据以及仓库字段 (对于 any-repo worker，repoOwner/repoName 为空字符串) 。完整响应参见 API 参考文档。

列出用量池¶

curl --request GET \
  --url "https://api.cursor.com/v0/private-workers/pools?scope=team_pool" \
  -u "$CURSOR_API_KEY:"

返回持久用量池，包含 connectedWorkerCount、inUseWorkerCount、isStale 以及可选的仓库字段。任意代码仓库用量池不含仓库字段。请通过此接口获取各用量池的已连接数量和使用中数量；下方的团队级 worker 摘要无法替代特定用量池的需求数据。

获取工作器摘要¶

curl --request GET \
  --url "https://api.cursor.com/v0/private-workers/summary" \
  -u "$CURSOR_API_KEY:"

返回你的用户和团队的连接数与使用中数。参见 获取工作器摘要。可在队列积压增长时用此调整响应规模，或在利用率较高时触发伸缩：

const summary = await response.json();
const team = summary.teamSummary;
if (team && team.totalConnected > 0) {
  const utilization = team.inUse / team.totalConnected;
  if (utilization >= 0.9) {
    // 扩容：预置更多 worker
  }
}

根据 ID 获取 worker¶

curl --request GET \
  --url "https://api.cursor.com/v0/private-workers/pw_123" \
  -u "$CURSOR_API_KEY:"

认领待处理请求¶

临时 controller 可以在启动 worker 之前预留排队中的请求：

curl --request POST \
  --url "https://api.cursor.com/v0/private-workers/claim" \
  -u "$CURSOR_API_KEY:" \
  --header 'Content-Type: application/json' \
  --data '{
    "id": "bc-00000000-0000-0000-0000-000000000002",
    "workerId": "pw_123"
  }'

然后使用相同的 id 启动 worker (CURSOR_AGENT_WORKER_ID=pw_123) 。参见 Claim A Pending Request。

释放 claim¶

删除将智能体绑定到自托管 worker 的 claim。之后 Cursor 将不再优先把该智能体调度到这台机器上：

curl --request POST \
  --url "https://api.cursor.com/v0/private-workers/claims/bc-00000000-0000-0000-0000-000000000002/release" \
  -u "$CURSOR_API_KEY:"

当已存在有效 claim 时，再次发起 claim 会被拒绝；请先释放，再申领新的 workerId。参见 Release A Claim。

监控¶

当使用 --management-addr 启动 worker 时，管理服务器会提供 GET /metrics、GET /healthz 和 GET /readyz：

agent worker --pool --management-addr ":8080" start

从您的 worker 采集指标：

curl http://localhost:8080/metrics

可用指标¶

Gauge

计数器

会话结束原因¶

cursor_self_hosted_worker_session_ends_total 计数器包含一个 reason 标签，其值可能为以下之一：

安全¶

数据流。 有两类数据会离开您的网络：一类是模型在推理期间读取的文件分块，另一类是 worker 上传到 Cursor 管理的存储中的云端代理 产物 (截图、视频和日志引用) ，以便它们显示在 PR 和仪表盘中。您的代码仓库、构建缓存和机密信息始终保留在您的机器上。

仅出站。 worker 通过 HTTPS 发起出站连接。无需开放入站端口，也无需更改防火墙设置。

隐私模式。 自托管云端代理遵循 Cursor 的隐私模式设置。启用隐私模式后，您的代码不会被用于训练。

隔离。 每个智能体会话都会分配到专用的 worker。会话不会在不同 worker 之间共享。

身份验证。 池中的 worker 使用服务账户 API 密钥进行身份验证。其他类型的 API 密钥将被拒绝。

仪表盘可见性。 团队管理员可以查看所有已连接的 worker。团队成员只能查看分配给自己的 worker。

CLI 参考¶

agent worker [options] start

常见问题¶

如何确定 worker 的规格？¶

worker 没有固定规格。你可以像为其服务的仓库配置 CI
runner 或 devbox 一样，来确定每个 worker 的规格。

每个 worker 都需要足够的 CPU、内存、磁盘和网络访问能力，以便克隆
仓库，并运行你的 agents 所需的构建、测试和工具。

可以把技能预置到 worker image 中吗？¶

可以。.cursor/skills/ 或 .agents/skills/ 中的
项目级技能会自动在自托管 workers 上可用。

如果要在团队内共享技能，可以将其提交到仓库中，或预置到
你的自定义 worker image 中。个人技能
同步适用于
managed Cloud Agents，不适用于自托管 workers。

MCP 服务器可以在自托管 workers 上运行吗？¶

可以。请通过 Cloud Agents 仪表盘配置 MCP 服务器。关于
按不同 transport type 进行 routing 的方式，请参阅
MCP 服务器 部分。

hooks 会在自托管 workers 上运行吗？¶

会。自托管机器 worker 会运行 .cursor/hooks.json 中的
项目 hooks。在企业版中，它们还会运行团队和
enterprise-managed hooks。请参阅 Hooks。

多个 agents 可以共用一个 pool worker 吗？¶

一个 pool worker 同一时间只服务一个智能体。当请求需要等待可用容量时，
请添加 worker 或扩容用量池。

Mac pool workers 可以运行计算机使用吗？¶

可以。使用 --computer-use 启动它们。首次启动会安装
Cursor Computer Use 辅助应用；请为其授予 辅助功能 和 屏幕录制
权限，用一个截图任务验证后，再为该机器创建 快照。
屏幕录制 无法由 MDM 静默授予，因此请在 template 上手动批准
一次，再由此制作 image。请参阅计算机使用与桌面
共享。

后续步骤¶

• anysphere/k8s-workers：基于 agent worker controller --spawn 构建的 Kubernetes 模板，支持 认领-then-spawn 与 --warm-idle 模式。
• Integrations：面向其他平台的合作伙伴指南与参考模板。
• Kubernetes operator (已弃用) ：面向已运行 WorkerDeployment operator 的集群的参考。
• 计算机使用：让 agents 在你的 worker 上操控桌面和浏览器。
• API 参考文档：worker、用量池、待处理请求队列以及 worker token 相关的端点。