自托管机器

自托管机器可将云端代理的工具执行迁移到你自行管理的硬件上。Cherri Code 托管的云端代理仍是默认选项。智能体循环仍在 Cherri Code 云中运行，工具则由你的机器来执行。

如何在几分钟内连接一个自托管机器 worker？

安装 Cherri Code 命令行界面，然后选择一种方式。

我的机器 (单个工程师、单台 box) ：

agent logincd /path/to/repoagent worker start --name "my-devbox"

当机器上没有浏览器时，请使用个人 API 密钥代替浏览器登录：

agent worker --api-key "$CURSOR_API_KEY" --name "my-devbox" start

团队用量池 (团队共享的机器集群) ：

export CURSOR_API_KEY="<service-account-api-key>"cd /path/to/repoagent worker --pool start

团队用量池 workers 需要 service account API 密钥。personal API 密钥 注册的是「我的机器」worker，而不是团队用量池 worker。

团队 admins 必须先在 Cloud Agents 仪表盘中启用 self-hosted workers，成员才能连接团队用量池 workers。

请保持该 process 持续运行。worker 通过 HTTPS 发起 outbound 连接，无需开放 inbound ports，也不需要 VPN。

我应该选择哪种 自托管机器 方案？

什么是面向云端代理的自托管机器？

Cherri Code 只保留 智能体循环：推理与规划。你的源代码、机密信息和工具执行都留在你自己的机器上。

你可以在 VM、Kubernetes 节点、Mac、GPU box 或合作伙伴 sandbox 上运行 worker。使用自托管机器的常见原因包括：

• 自定义硬件，例如 GPU，或用于 iOS 开发的 Mac
• 必须留在你自己基础设施内的机密信息和构建产物
• 你的机器已经可以访问的私有 Git 或包注册表
• 由你自行管理克隆和 git 状态的 sandbox

如果你只是担心从 Cherri Code 云访问私有源代码控制，不妨先试试搭配私有网络连接的托管式 Cloud Agents，无需自行运维 worker。

Cherri Code 现在支持本地部署了吗？

不支持。Cherri Code 不是本地部署产品。智能体循环仍运行在 Cherri Code 云中。你注册一台由你自己运维的机器，Cherri Code 会通过出站 HTTPS 连接向它发送工具调用。

代码检出、构建缓存以及机器本地凭据都保留在你自己的硬件上。完整的划分方式请参见哪些数据留在我的机器上，哪些留在 Cherri Code 云中？。

自托管机器的连接方式与托管 Cloud Agents 有何不同？

两种方式都将 智能体循环 保留在 Cherri Code 云中，区别在于工具在哪里执行，以及如何访问私有仓库和内部工具。

如果你希望由 Cherri Code 运维执行环境，同时仍能从 Cherri Code 云访问私有源代码控制，请选择搭配私有网络连接的托管 Cloud Agents。

如果执行必须保留在你自己掌控的硬件上，且该硬件已经能访问你的仓库和内部服务，请选择自托管机器。你无需为 Cherri Code 访问你的工具开放入站 HTTPS：worker 会在本地访问它们，并通过出站会话回传结果。

出站主机相关内容参见自托管机器是否需要入站网络访问或 VPN？，托管方式的设置参见 Cloud Agents。

团队用量池和「我的机器」有什么区别？

团队用量池是一个具名的路由目标。聊天会在团队用量池中排队等待，直到有 worker 认领。每个团队用量池 worker 同一时间只会被一个智能体认领。

「我的机器」 (也称为 Remote Control) 用于连接你自己拥有的某一台机器。只要机器资源充足，就可以在同一台机器上运行多个智能体。

对于 Kubernetes 集群，请从 anysphere/k8s-workers 模板开始，它会在你的集群中运行 agent worker controller --spawn，无需 CRD。较早的 WorkerDeployment operator 已弃用；对于已经在运行它的集群，其参考文档仍然可用。

团队用量池需要企业版方案和service account API 密钥。我的机器使用个人凭据。

管理员如何启用或强制使用自托管机器？

团队管理员打开 Cloud Agents 仪表盘，进入 Self-Hosted 设置。

• 允许自托管机器：成员可自行选择在其连接的机器上运行。若未启用，Cloud Agents 将使用 Cherri Code 托管的基础设施。
• 要求自托管机器：每个 Cloud Agent 会话都必须使用自托管机器。

仪表盘还会显示团队用量池详情，以及在 我的机器 下注册的机器。

我可以在第三方 VM 或 沙盒 上运行自托管机器吗？

可以。团队用量池的 worker 既可以运行在合作伙伴平台上，也可以基于你 clone 的 参考模板 运行。智能体循环 仍由 Cherri Code 运行；该 VM 或 沙盒 上的 worker 则负责运行工具，并通过 HTTPS 出站连接。

合作伙伴指南与 templates 请参阅 集成。

合作伙伴指南涵盖 AWS Lambda、Cloudflare、Namespace、Modal、Daytona、E2B、Vercel、Tensorlake 和 SuperServe。参考模板涵盖 AWS Lambda MicroVMs、Cloudflare Containers 和 Kubernetes。

你也可以在已有的 VM 上安装 Cherri Code 命令行界面，使用 agent worker start 或 agent worker --pool start 自行启动 worker。

自托管机器是否需要入站网络访问或 VPN？

不需要。worker 会从您的机器向 Cherri Code 云发起一条出站 HTTPS 连接，Cherri Code 通过该连接下发智能体请求。您的机器无需从互联网可访问。

您无需开放入站端口、修改防火墙或建立 VPN 隧道。如果您的网络使用 HTTPS 代理，请在 worker 环境中设置 HTTPS_PROXY 或 https_proxy。

worker 需要出站访问 api2.cursor.sh、api2direct.cursor.sh，以及用于上传 artifact 的 cloud-agent-artifacts.s3.us-east-1.amazonaws.com。完整的数据流请参见会离开您网络的内容。

哪些数据留在我的机器上，哪些进入 Cherri Code 云？

你的源代码、构建产物、机密信息以及工具执行都留在你的机器上，其中包括文件编辑、终端命令，以及智能体在本地发起的网络调用。

Cherri Code 云负责 智能体循环：推理请求与规划。工具调用的结果会回传给 Cherri Code 用于下一轮推理，但你的原始代码和机密信息不会存储在由 Cherri Code 托管的基础设施中。

隐私模式的适用方式与托管版 Cloud Agents 完全一致。启用后，从 worker 发送的代码不会被 Cherri Code 或模型提供方用于训练。

我可以不指定仓库，就让团队用量池服务于任意仓库吗？

可以。任意代码仓库团队用量池将源代码控制与团队用量池解耦，一个团队用量池可以服务多个仓库。

agent worker --pool my-pool --worker-dir "$HOME/cursor-sandboxes/default" start

传入 --clone-git-repos，让 worker 在认领时克隆仓库。在 Cherri Code composer 的环境选择器中，在 Any repo 下选择该团队用量池。

若不使用 --clone-git-repos，任意代码仓库用量池可以借助始终应用的工作区规则，将 task subject 映射到仓库，并使用 worker 凭据克隆它们。

在 Slack 中，团队管理员可以运行 @Cherri Code pool set <name>，将某个任意代码仓库团队用量池设为团队默认用量池。此后 @Cherri Code 提及无需在 message 中包含 pool= 即可在该用量池上 start，即使没有解析到任何仓库也是如此。加上 channel (@Cherri Code pool set <name> channel) 即可设置频道默认用量池，在单个频道内实现同样的效果。

此设置仅适用于任意代码仓库用量池。仓库绑定的用量池会将 request 路由到已具备匹配 checkout 的 worker。

如何连接私有或自托管的 GitLab？

对于私有或隔离网络中的自托管 GitLab，请使用 any-repo 团队用量池，让整个 SCM 生命周期都留在你的 worker 上。

1. 创建团队用量池，不要将其绑定到某个具体仓库。
2. 在能够访问你的 GitLab 实例的机器上，从某个 workspace 目录启动 worker。
3. 在 worker 上使用本地 personal access token 或 SSH 密钥完成 git 认证。worker 执行 checkout 时无需 Cherri Code 的 GitLab OAuth。

智能体会借助你机器已有的网络访问权限来访问私有仓库。当开发者需要跨多个仓库工作时，这种方式同样适用。

如需在托管基础设施上进行基于 OAuth 的云端代理设置，请参阅 GitLab 集成文档。

agents 能否使用自托管机器 worker 上的屏幕或浏览器？

可以，macOS 和 Linux worker 支持。请先在 Linux 上安装桌面端软件包，然后使用 --computer-use 启动：

agent worker --computer-use start

在 macOS 上，首次启动会安装 Cherri Code Computer Use 辅助程序。请为其授予“辅助功能”和“屏幕录制”权限。--share-desktop 桌面共享仅支持 Linux。若需使用浏览器，请在 runner 上安装 Chrome 或 Chromium。

依赖项与设置详见计算机使用与桌面共享。

钩子和 MCP 能在自托管机器上运行吗？

可以，但与托管的 Cloud Agents 存在一些差异。

钩子：worker 会运行 .cursor/hooks.json 中的项目 hooks。企业版方案还可在自托管 workers 上使用 team hooks 和企业管理的钩子。当某个 session 认领 worker 时会运行 sessionStart，该认领释放时会运行 sessionEnd。参见钩子支持矩阵和团队用量池上的钩子。

MCP：命令 (stdio) 类 MCP 服务器在你的 worker 上运行，可访问私有网络；HTTP 和 SSE 服务器仍在 Cherri Code 的后端运行。自托管 workers 上仍有部分 MCP 功能尚未支持，最新状态请查看更新日志。

如何排查 自托管机器 设置问题？

请从以下基础步骤开始：

1. 检查仪表盘。 打开 Cloud Agents 仪表盘，在 我的机器 或团队用量池详情中确认 worker 显示为已连接、空闲或使用中。
2. 运行诊断。 运行 agent worker debug 执行 worker 预检 (加上 --json 可输出机器可读格式) 。报告涵盖认证、连通性、routing 和后端可见性。
3. worker 未出现在 UI 中。 如果 worker 进程已在本地运行但未出现在 Cherri Code 中，通常是出站连通性问题。请确认该机器能通过 HTTPS 访问 api2.cursor.sh 和 api2direct.cursor.sh。参见 自托管机器 是否需要入站网络访问或 VPN？。
4. 团队用量池 controller 问题。 内置的 worker controller 是新功能。请将 controller 和自动伸缩配置视为早期部署，并在团队中逐步总结经验、记录修复方法。

worker 预检报告：

agent worker debug

该报告涵盖身份验证、连通性、路由、仓库标签，以及 Cherri Code 能否看到你的 worker。

常见修复方法：

• 确认 worker 进程仍在运行
• 确认 Cherri Code 应用与 CLI 使用同一账户
• 对于基于仓库的 worker，检查 worker 目录是否配置了预期的 git remote
• 检查是否可以向 会离开您网络的内容 中列出的主机发起出站 HTTPS 访问

若在 worker 启动前出现连接问题，请运行 agent worker start --debug。就长期存在的设置问题联系支持时，请附上 agent worker debug 的输出。

如何确保 SCM 权限得到遵循？

自托管运行分为两层：Cherri Code 路由 (由哪个 worker 处理请求) 和 worker 上的 git 凭据 (该 worker 能 clone、fetch 或 push 哪些内容) 。

Cherri Code 路由

• 我的机器：只有当 worker 已注册的某个 --worker-dir 根目录与该仓库匹配时，Cherri Code 才会把仓库请求路由到该 worker。请从正确的 checkout 启动 worker，或再添加一个 --worker-dir。
• 仓库绑定的团队用量池：请求需同时匹配团队用量池名称和 repo=<owner/repo> 标签。pool=my-pool 且 repo=acme/payments 的请求只会路由到服务该仓库的 worker。
• GitHub 触发器：在公开仓库上，只有具备 OWNER 或 COLLABORATOR 权限的用户才能把运行路由到自托管团队用量池。其他评论者仍会在托管基础设施上运行，除非团队要求所有运行都使用自托管。
• 组织控制：受保护的 Git 范围和代码仓库屏蔽列表依然生效。请在 Integrations 中连接每位用户的 Git 账户，以便 Cherri Code 在运行开始前校验代码仓库访问权限。

worker 上的 Git 访问

• 已有的 checkout (我的机器或仓库绑定的团队用量池) ：智能体使用机器上已有的 git 凭据，例如 SSH 密钥或 credential helper 中的个人访问令牌。请只为每个 worker 授予其所需的仓库访问权限。
• 搭配 --clone-git-repos 的任意代码仓库团队用量池：worker 在认领任务时，使用为发起运行的用户签发的短期 GitHub token 执行 clone。团队管理员必须为团队用量池 worker 启用 GitHub token 签发，且发起请求的用户必须在 GitHub 中拥有该代码仓库的访问权限。
• 私有或自托管 GitLab：在 worker 上使用本地 PAT 或 SSH 密钥对 git 进行认证。参见如何连接私有或自托管 GitLab？。

worker 已连接但 git 失败时

1. 运行 agent worker debug，确认代码仓库标签与请求中的仓库一致。
2. 在 worker 上，用智能体将要使用的同一套凭据运行 git fetch 或 git ls-remote。
3. 确认发起运行的 Cherri Code 用户在你的 Git 提供商以及 Cherri Code integrations 中都能访问该代码仓库。
4. 对于团队用量池的认领时 clone，确认已启用 token 签发，且该团队用量池是任意代码仓库的具名团队用量池 (而非 default) 。

Cherri Code 绝不会把代码仓库访问权限扩大到超出触发用户已有的范围。如果某次运行进入了错误的 checkout 或无法 push，请修正路由标签或 worker 的 git 凭据，而不要在互不相关的仓库之间共用一个权限过宽的服务 token。

如果遇到速率限制怎么办？

请联系支持团队。

如何检查我的团队用量池是否已达上限？

在 Cloud Agents 仪表盘中查看 worker 容量。团队用量池详情和我的机器会按状态列出 worker。

如需以编程方式检查，可调用摘要 API：

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

响应中包含你的用户和团队已连接、使用中的 worker 数量。

智能体运行无法启动的常见原因：

• 没有已连接的 worker：在团队用量池中启动或伸缩 worker，或确认「我的机器」中有 worker 正在运行
• 所有 worker 都在忙：请求会在团队用量池队列中排队，直到有 worker 空闲
• 超出 private worker 限额：你的团队已达到已连接 worker 上限 (每用户 200 个，每团队 1000 个) 。请断开闲置的 worker，或联系销售洽谈更高的限额
• 代码仓库不匹配：从正确的 checkout 启动 worker，或使用 any-repo 团队用量池

worker 在连接期间会持续发送心跳。一旦停止发送心跳，worker 就会从注册表中移除。有关伸缩和 controller 设置，请参阅 Team Pools。

相关内容

• Cloud Agents
• 自托管机器
• 我的机器
• 团队用量池
• 集成
• 计算机使用
• 私有网络连接
• Cloud Agent 安全性与网络