Claude Code 云端会话实战指南:每个任务独占一台 VM,可并行跑任务并以分支收尾

来源:Anthropic:Claude.dev 开发者博客(RSS) 2026年10月6日 20:00 AIHOT 评分:82 精选
摘要:Claude Code 推出云端会话:每个任务在独立 VM 上运行,仓库克隆到新分支,可从 claude.ai/code、手机、Desktop、终端和 Slack 启动并跟踪,完成后产出可转 PR 的分支,Pro、Max、Team、Enterprise 计划不额外收费。
推荐理由:作者用四个真实云会话实测并行修复、文档校对和结构化日志,给出本地与云会话的选择边界和七个适用工作流。
# Claude Code 云端会话实战指南:每个任务独占一台 VM,可并行跑任务并以分支收尾 > 原标题:Claude Code in the cloud: a field guide to cloud sessions - 来源:Anthropic:Claude.dev 开发者博客 - 发布时间:2026-10-06T12:00:00.000Z - AIHOT:https://aihot.news/items/sxr71auxicu8uk3e4bqxol02h - 原文:https://claude.dev/blog/claude-code-in-the-cloud/ ## 摘要 Claude Code 推出云端会话:每个任务在独立 VM 上运行,仓库克隆到新分支,可从 claude.ai/code、手机、Desktop、终端和 Slack 启动并跟踪,完成后产出可转 PR 的分支,Pro、Max、Team、Enterprise 计划不额外收费。 ## 推荐理由 作者用四个真实云会话实测并行修复、文档校对和结构化日志,给出本地与云会话的选择边界和七个适用工作流。 ## 正文 · 中文译文 你可能在自己的笔记本电脑上的终端里运行 Claude Code。该会话在三个方面依赖于这台笔记本电脑: - 它共享你的工作树,因此同一仓库上的两个会话可能会编辑相同的文件,并争用同一个端口。 - 它使用你的凭据运行。 - 当你的电脑休眠或 Wi-Fi 断开时,它就会停止。 [云端会话](https://code.claude.com/docs/en/claude-code-on-the-web)在它自己的机器上运行 Claude Code。每个任务都会获得一台全新的虚拟机,你的仓库被克隆到一个新分支上,并且你的环境设置已经完成。 你可以从 [claude.ai/code](https://code.claude.com/docs/en/web-quickstart)、[Claude 移动应用](https://code.claude.com/docs/en/mobile)、[桌面应用](https://code.claude.com/docs/en/desktop#run-long-running-tasks-in-the-cloud)、你的[终端](https://code.claude.com/docs/en/claude-code-on-the-web#from-terminal-to-cloud)以及 [Slack](https://code.claude.com/docs/en/slack) 启动一个会话。然后你可以在浏览器、移动应用和桌面应用中跟进它。工作完成后,它会留在一个分支上,你可以将其变成拉取请求。 云端会话随你的 Pro、Max、Team 或 Enterprise 套餐提供,无需额外费用:云端机器不单独收费,会话使用的用量限制与 Claude Code 其余部分相同。根据你的套餐,组织所有者可能需要先[开启云端会话](https://claude.ai/admin-settings/claude-code)。 **云端会话奖励额度。**现有的个人 Pro 和 Max 订阅者可以在其套餐限制之外,领取一次性的云端会话奖励额度:Pro 为 100 美元,Max 为 250 美元。请在 10 月 7 日前通过 claude.ai/code/claim-credit 或在 Claude Code 中使用 `/claim-credit` 领取。该额度将于 11 月 4 日过期。在使用完或过期后,将适用你套餐的常规用量。它不适用于 Projects 或 Routines。请参阅[促销额度优惠条款](https://www.anthropic.com/legal/promotion-credit-terms)。 在本指南中,我针对一个小型示例仓库运行了四个真实的云端会话。它们的记录、差异和耗时贯穿全文。仓库和截图中的用户是虚构的。工作、输出和数字均来自这些会话。 云端会话的主要优势之一是你可以同时运行多个任务,而它们不会相互干扰。以下是我在 16 秒内启动的三个任务,每个都在自己的机器上运行。在我的笔记本电脑上,我本会一个接一个地运行它们,或者把时间花在让它们互不干扰上。 ![Timeline of three cloud sessions in three VMs, started within 16 seconds of each other. After a hatched setup bar, the flaky-test fix finishes at 65 seconds with the suite run 40 times and 0 failures, the docs rewrite at 62 seconds with 5 doc errors fixed, and the structured-logging change at 87 seconds with JSON logs and 5 new tests.](https://claude.dev/media/58bd02532f8c5914f4dc430c84caddcb4158c4dc7b2905bcf602c9cb439ab5e2.png) **图 A**同一仓库上三个云端会话的真实时间线,以从第一个启动开始的秒数计。阴影条是重建示例仓库的设置步骤(正常使用时由 GitHub 克隆替代),每个点是一次工具调用。 ## 三个任务,一个仓库,三台机器 示例仓库是 **tidepool**,一个小型 Node API,用于预测三个虚构港口的潮汐。它有三个普通问题:一个测试大约每四次运行失败一次,API 文档描述的参数代码已不再读取,以及日志记录器通过拼接字符串来构建其行。 我在 16 秒内启动了三个云端会话,每个问题一个。我以编程方式启动它们,由于 tidepool 不在 GitHub 上,每个会话首先根据其提示中的文件重建仓库。对于真实仓库,你会跳过这一步,而从终端启动时,每个会话就是一条 `claude --cloud` 命令。简而言之,这三个提示是: CODEShell claude --cloud "npm test fails maybe one run in four. Find the flaky test, fix the root cause in the code (not the test), and prove it by running the suite at least 30 times in a row." claude --cloud "docs/API.md is out of date with src/server.js. Rewrite it so every endpoint, parameter, default and response shape matches the code. Start the server and run each curl example to check it." claude --cloud "Make src/logger.js emit one JSON object per line, keep LOG\_LEVEL, and log method, path, status and duration\_ms as fields. Add a test for the logger." 这些会话分别运行了 61、65 和 72 秒,三个会话都在第一个启动后 87 秒内完成。重建仓库大约占每次运行的三分之一到一半多一点。以下是结果。 - **不稳定的测试。**Claude 在 `TtlCache.get` 中发现了一个竞态条件。缓存只在加载器完成后才存储值,因此在加载过程中对同一键的第二次 `get` 会再次调用加载器。Claude 修改缓存以存储进行中的 promise,在加载失败时删除该条目,并连续运行 `npm test` 40 次,零失败。 - **文档。**Claude 启动了服务器,对每个端点运行了 curl,并发现了旧文档错误的五种方式。它列出了 API 从不返回的字段,记录了一个代码忽略的 `days` 参数,将高度以英尺为单位给出而实际是米,跳过了 `/next-high` 端点,并遗漏了错误响应。它还发现格式错误的 `from=` 值会返回空列表和 200 状态码,并将其记录为注意事项,而不是修改未被要求触碰的服务器代码。 - **日志记录器。**Claude 编写了 JSON 日志记录器,将请求日志移至结构化字段,并添加了五个测试。它的提交带着一个失败的测试进入,因此 Claude 重新运行缓存测试八次,看到其中五次失败,并将失败追溯到第一个会话正在修复的同一竞态条件。它提出了相同的修复方案,但没有改动缓存,因为这超出了它的任务范围,并在总结中说明测试套件并不干净。 **图 E**同一本地构建的 20 秒录屏:在三个会话之间点击,然后滚动日志记录器会话的记录 日志记录器的结果显示了为什么云会话适合并行工作。每个会话都有自己的仓库副本、自己的进程和自己的分支。文档会话和日志记录器会话各自启动了 API 服务器进行测试,彼此互不影响。在单台笔记本电脑上,两个代理在同一个检出中工作会编辑相同的文件,并且会在端口上冲突,除非各自选择自己的端口。 由于这种隔离,日志记录器会话无法访问第一个会话正在进行的缓存修复。沿着文件边界拆分并行任务,以合理的顺序合并分支,并预期某个会话会报告另一个会话正在修复的问题。 ## CLAUDE CODE 云会话的内部机制 云会话是在 Anthropic 管理的基础设施上运行的 Claude Code 会话,或者在你组织自己的机器上使用 [自托管环境](https://code.claude.com/docs/en/self-hosted-environments) 运行。图中展示了各个部分。其后的四个要点是改变你工作方式的关键。 ![You start a session from a browser, phone, Desktop, terminal, Slack or a routine. It runs in a fresh VM with a clone of your repository on a claude branch, Claude Code in auto mode, and your environment's setup. GitHub traffic passes through a proxy that holds your token outside the VM; other traffic passes through a security proxy that applies the network allowlist. The result is a branch and a pull request.](https://claude.dev/media/7c0f2a65796202281cbc6ededff3f0dbfe216aca98e3831640eec064e2b85165.png) **图 F**云会话的剖析。代理可以触及的一切都位于 VM 内部。你的 GitHub 令牌和网络策略位于其外部。 - **每个任务都有自己的机器。**一个全新的 VM,你的仓库被克隆到一个新分支上,因此会话无法触碰彼此的文件或端口。参见 [已安装的内容](https://code.claude.com/docs/en/cloud-environments#installed-tools)。 - **你的 GitHub 令牌永远不会进入 VM。**代理持有它,会话获得一个短期凭证,只能推送到自己的工作分支。参见 [GitHub 代理](https://code.claude.com/docs/en/cloud-environments#github-proxy)。 - **仓库的 Claude 配置会随之而来。你的个人配置则不会。**`CLAUDE.md`、规则、技能、代理和命令随仓库一起传输,而你的 `~/.claude` 留在你的笔记本电脑上。参见 [云会话中的设置](https://code.claude.com/docs/en/settings#settings-in-cloud-sessions)。 - **空闲的 VM 会被回收。**重新打开会话,你会获得一个全新的 VM,对话已恢复,因此请提交你在意的工作。参见 [环境过期](https://code.claude.com/docs/en/claude-code-on-the-web#environment-expired)。 有关规格、[权限模式](https://code.claude.com/docs/en/permission-modes) 和网络级别,请参阅 [云环境文档](https://code.claude.com/docs/en/cloud-environments)。 ## 本地还是云端? 云端会话不会取代本地会话,大多数人两者都会用。下表展示了它们的差异,表后的段落说明了各自适用的场景。 | | 本地会话 | 云端会话 | | --- | --- | --- | | 运行于 | 你的机器 | 每个任务一台全新 VM | | 笔记本休眠或离线 | 会话停止 | 会话继续运行 | | 同一仓库上的多个任务 | 独立的工作树、端口,需谨慎处理 | 每个任务一个 VM 和一个分支 | | 智能体可访问的范围 | 你的用户账户能访问的一切,包括 SSH 密钥、云 CLI 和 `~/.claude` | 仓库、你设定的网络级别、你启用的连接器,以及会话作用域的 GitHub 凭据 | | 启动或跟进方式 | 那台机器,或通过远程控制用你的手机 | 浏览器、手机、Desktop、终端、Slack、API 调用或定时任务 | | 审批 | 任意模式,包括逐命令审批 | 自动、接受编辑或计划 | | 结束时 | 你的工作树中的变更 | 一个分支,以及你需要时的一个拉取请求 | | 算力 | 你的机器 | 无单独的算力费用;使用你套餐的额度 | 当任务需要只有你的机器才具备的东西时,就留在本地。这包括带有真实本地数据的数据库、通过 VPN 访问的服务、GPU、手机模拟器,或你桌上的硬件。对于紧凑的视觉循环——你希望在自己浏览器中几秒内看到每次变更——也留在本地,以及当你的组织采用 [零数据保留](https://code.claude.com/docs/en/zero-data-retention)(会关闭云端会话)时。 有两个功能介于两种选择之间。**远程控制**让会话留在你的机器上,并让你从手机或浏览器操控它。**[自托管环境](https://code.claude.com/docs/en/self-hosted-environments)**(Team 和 Enterprise 版测试中)在你组织自己的基础设施上运行云端会话,因此它们可以访问私有网络。 如果以上都不适用,那么该任务就是云端的良好候选。下一节介绍最能从中获益的工作流。 ## 适合云端会话的七种工作流 这些工作流充分利用了表中的差异:每个任务一台独立机器、你离开时仍在运行的会话,以及结束时供你审查的分支。 ### 1\. 并行清理积压任务 假设你有五个互不相关的小修复。在本地,你要一个接一个地做,或者设置五个工作树并让它们的端口和安装互不干扰。在云端,你可以启动五个会话并审查五个分支。 CODEShell claude --cloud "Fix the flaky test in auth.spec.ts" claude --cloud "Update the API documentation" claude --cloud "Refactor the logger to use structured output" `claude --cloud` 会在你当前分支克隆你的 GitHub 远程仓库,所以请先推送你的本地提交。在 VM 启动期间,CLI 会显示设置步骤的实时清单,并将你输入的任何内容排队。 把每个任务写成一个自包含的工单,说明哪里有问题、完成是什么样,以及如何证明。那个不稳定测试的提示词说明了它的证明方式:连续运行测试套件至少 30 次。该会话运行了 40 次。 当这些任务属于同一个更大的工作时,一个 **[项目](https://claude.com/blog/projects-redesigned)**(Pro 和 Max 版公开测试中)会运行一个协调者对话,为你启动并跟踪云端会话。然后它按状态将它们分组:进行中、等待你处理,以及可供审查。 ### 2\. 让它证明修复 不稳定测试是最需要反复证明的工作的典型例子:你必须一遍又一遍地运行测试套件,而你不希望这个循环占用你正在使用的机器。在云端,Claude 修补了缓存,并在一条命令中运行了整个测试套件 40 次。 ![The flaky-test session's Bash step: a patch to src/cache.js that caches the in-flight promise, then a loop running the test suite 40 times, with output runs=40 fails=0.](https://claude.dev/media/6ce551ccd1a1cd64a0f9c0fb8b8116e1ca1e260a9f5de861de798e0fe578afe6.png) **FIG G**四十次运行,零失败:flaky-test 会话的真实命令和输出,在本地运行的 claude.ai/code 界面中重放。Claude 修补了 src/cache.js,并在一步中把整个测试套件循环运行了 40 次。路径显示在 /home/user 下。 虚拟机没有计算费用,其 CPU 也不是你的,所以要求提供充分的证明。把测试套件运行 200 次,在 50 个提交中二分定位一个回归,运行缓慢的集成测试层,或者像文档会话那样启动应用并用 curl 访问它。 Claude 的每一轮仍然计入你的套餐,但在一条命令内进行长时间测试运行的成本很低。[前台命令](https://code.claude.com/docs/en/cloud-environments)默认在 2 分钟后超时(最多 10 分钟),然后继续在后台运行最多 30 分钟。你可以在环境变量中用 `BASH_DEFAULT_TIMEOUT_MS` 和 `BASH_MAX_TIMEOUT_MS` 提高默认值。 ### 3\. 在桌面上规划,在云端构建,在终端中收尾 对于较大的改动,先在来回沟通成本低的地方就方案达成一致。以计划模式启动 Claude,一起制定计划,提交计划并推送。 CODEShell claude --permission-mode plan \# ...agree on the plan, save it to docs/migration-plan.md, commit and push... claude --cloud "Execute the migration plan in docs/migration-plan.md" 当云端会话在构建时,你的终端可以腾出来做其他工作。完成后,把会话拉取下来手动收尾。 CODEShell claude --teleport \# pick a cloud session claude --teleport Teleport 会检查你处于同一个仓库中,获取会话的分支,检出它,并将整个对话加载到你的终端。你需要一个干净的工作树(它会提议暂存),并且分支必须已推送。在 Claude Code 内部,`/teleport`(或 `/tp`)会打开同一个选择器,然后 `/tasks` 再 `t` 也可以。桌面应用则相反,其 **Open in** 菜单会把本地会话发送到云端。 ### 4\. 从手机端查看进度 Claude 应用中的 Code 标签页连接到相同的会话。你可以从手机启动任务、跟进任务、引导任务、回答 Claude 提出的问题,或让 Claude 关注某个拉取请求。 手机适合处理那些等你坐到键盘前就会忘记的问题。我给第四个会话提了一个你会在手机上输入的那种问题:tidepool 如何预测潮汐,以及在时间窗口的边缘它可能如何出错?它运行代码来验证答案,并发现了一个真实的 bug。该循环从不检查第一个或最后一个样本,因此当高潮恰好落在窗口起点时,API 会漏掉它。 ### 5\. 把 CI 失败和审查评论交给 Claude 在仓库上安装 Claude GitHub App 后,云端会话可以关注拉取请求并对其发生的情况采取行动。在 claude.ai/code 的会话中的 CI 栏里,打开 **Auto-fix**。你也可以在终端中于 PR 分支上运行 `/autofix-pr`,让移动应用关注该 PR,或将 PR URL 粘贴到会话中。 Claude 会为失败的检查和审查评论推送清晰的修复,并解释它改了什么。对于任何含糊或架构性的问题,它会向你询问。审查线程上的回复会以你的 GitHub 用户名发布,并标注为 Claude Code。Claude 不会收到与基础分支合并冲突的通知,所以请让它 rebase。它的评论还可能触发诸如 Atlantis 之类的评论驱动自动化。 ### 6\. 无需自己动手即可开始工作 一个**例程**(研究预览版)是若干已保存的资源,旨在完成一项任务,例如提示词、代码仓库、连接器和环境。每次运行都是一个云会话,由触发器启动。触发器可以是定时计划(最高频率为每小时一次)、对例程自身端点的 HTTP 调用,或 GitHub 事件(如拉取请求开启或发布)。你可以在 claude.ai/code/routines、桌面应用中创建,或在 CLI 中使用 `/schedule` 创建。例程运行时无需审批提示,默认情况下会推送到以 `claude/` 为前缀的分支。 有两个更小的工具在这里能帮上忙。你可以从任何已登录的机器上,包括 CI 任务中,向正在运行的会话排队追加一条后续消息。 CODEShell claude -p "The integration tier is green now; rebase on main and push" --cloud 你还可以为预填好的会话添加书签。诸如 `claude.ai/code?prompt=Triage+the+newest+issues&repositories=acme-labs/tidepool` 这样的 URL 会打开 claude.ai/code,并已填好提示词和代码仓库。 ### 7\. 运行你并不完全信任的代码 贡献者的拉取请求、新依赖的安装脚本,或你五分钟前克隆的代码仓库,都可能运行你尚未阅读过的代码。在你的笔记本电脑上,这些代码会与你的 SSH 密钥、云 CLI 会话和浏览器配置文件相邻运行。而在云会话中,它运行在一个一次性 VM 里,没有这些东西,只有一个会话范围的 GitHub 凭据,以及一个你可以收窄的网络。 将环境的网络访问设置为 **None** 可获得最严格的运行,或保持 **Trusted**,它允许访问包注册表、GitHub 和主要云 SDK 主机。即使在 None 下,Claude Code 仍会向 Anthropic API 发送请求,因此数据仍可能以这种方式离开 VM,并且会话仍可推送到自己的分支。所有出站流量都经过一个记录主机名的代理。 ## 连接 GitHub 而不陷入困境 如果你的第一个云会话出了问题,GitHub 是最可能的原因。大多数问题源于云会话需要两个独立的 GitHub 权限。 - **使用 GitHub 登录**告诉 Claude 你是谁。 - **在账户或组织上安装 Claude GitHub App**设定 Claude 可以在那里看到哪些私有代码仓库。 公共代码仓库仅凭第一项即可使用。私有代码仓库需要第二项,且需安装在拥有它们的账户或组织上。如果你已连接 GitHub 但某个私有代码仓库缺失,通常是因为 App 未安装在拥有它的账户或组织上。 | 你已连接的内容 | 公共仓库 | 你的私有仓库 | 某组织的私有仓库 | 自动修复、GitHub 触发器、项目 | | --- | --- | --- | --- | --- | | 仅使用 GitHub 登录 | 是 | 否 | 否 | 否 | | \+ 在你的个人账户上安装 App | 是 | 是 | 否 | 你的仓库 | | \+ 在组织上安装 App(所有者批准) | 是 | 仅当也安装在你的账户上时 | 是 | 组织仓库 | | `/web-setup`(你的 `gh` 令牌) | 是 | 是 | 你的令牌能访问的任何内容 | 否,需要 App | ### 路径 A:在浏览器中连接(推荐) 在 [claude.ai/connect-github](https://claude.ai/connect-github) 连接你的 GitHub 账户,然后在拥有你代码仓库的账户或组织上安装 Claude GitHub App。对于组织,通常需要所有者批准安装。[快速入门](https://code.claude.com/docs/en/web-quickstart)会逐步介绍每个步骤。 如果 GitHub 没有把你送回 claude.ai/code,[claude.ai/connect-github](https://claude.ai/connect-github) 上的连接页面可以显示针对常见原因的简短检查清单。其中之一是单点登录步骤,如果你跳过它,组织的代码仓库会被隐藏。 ![The Didn't finish connecting screen with five tips: sign in to the right GitHub account, authorize each organization on the single sign-on step, start again if you saw GitHub connection not completed, connect your own account first and let an owner approve organization access later, or run /web-setup from the terminal.](https://claude.dev/media/0855b55ac62191f9b92cd9f5f1d5ab2d8181b03eb155678dd859cc7c8f8722ed.png) **图 L**如果 GitHub 没有把你送回来:产品自带的检查清单,用于处理中断的 GitHub 连接,来自本地运行的 claude.ai/code 界面中的快速设置引导流程 自动修复、由 GitHub 触发的例程和项目也依赖该 App,所以即使你通过其他方式连接,也要安装它。 ### 路径 B:从终端使用 /web-setup 连接 如果你已经在使用 `gh` CLI,请在 Claude Code 中运行 `/web-setup`,将你的 `gh` token 发送到你的 Claude 账户。之后会话便可访问该 token 能访问的任何仓库,无论是否使用该 App。请参阅 [从终端连接](https://code.claude.com/docs/en/web-quickstart#connect-from-your-terminal) 了解完整步骤。在 Team 和 Enterprise 方案中,需要由所有者先开启 [快速设置](https://code.claude.com/docs/en/claude-code-on-the-web#quick-setup-for-team-and-enterprise)。 ### 路径 C:跳过 GitHub,进行一次性操作 在没有 GitHub 远程仓库、或未安装该 App 的仓库中运行 `claude --cloud`,Claude Code 会改为上传你的仓库打包文件,而不是克隆它。只有当你的 GitHub 连接对该仓库具有推送权限时,会话才能推送回去。文档中列出了 [打包文件包含和不包含的内容](https://code.claude.com/docs/en/claude-code-on-the-web#send-local-repositories-without-github)。 ### 如果你使用 Team 或 Enterprise 所有者有一份简短的清单:在 [claude.ai/admin-settings/connectors](https://claude.ai/admin-settings/connectors) 开启 GitHub 连接器,在 [Claude Code 管理设置](https://claude.ai/admin-settings/claude-code) 中允许云会话,在组织的仓库上安装 Claude GitHub App(或批准成员的请求),并决定是否开启 [快速设置](https://code.claude.com/docs/en/claude-code-on-the-web#quick-setup-for-team-and-enterprise)。使用 IP 允许列表或 GitHub Enterprise Server 的组织还有额外步骤。请参阅关于 [IP 允许列表](https://code.claude.com/docs/en/claude-code-on-the-web#limitations) 和 [GitHub Enterprise Server](https://code.claude.com/docs/en/github-enterprise-server) 的文档。 ### 当它仍然无法工作时 | 你看到的现象 | 原因 | 修复方法 | | --- | --- | --- | | 选择器中缺少某个私有仓库 | 拥有该仓库的账户或组织未安装该 App,或其仓库访问权限未包含该仓库 | 在那里安装该 App,或将该仓库添加到 GitHub 设置中该 App 的仓库访问权限中 | | 出现错误,提示你必须是该组织的所有者才能将其关联 | 该组织阻止了成员资格检查,通常是因为有待处理的 App 权限请求、IP 允许列表或 SAML 单点登录 | 所有者在该组织的 GitHub App 设置中接受待处理的权限请求,为已安装的 GitHub App 开启 IP 允许列表继承,或(在 SAML 下)授予 Claude 访问该组织的权限 | | 连接后,某个组织的仓库立即缺失 | 该组织使用 SAML 单点登录,而其授权步骤被跳过了 | 在 GitHub 的“单点登录到你的组织”步骤中,继续之前点击每个组织旁边的 **Authorize**。如果你已经跳过了,请在 GitHub 设置中为该组织授权 Claude,然后重新连接 | | 每个云会话都因身份验证错误而失败 | 你的 Claude 组织使用了 IP 允许列表 | 请支持人员将 Anthropic 托管的服务加入豁免 | 其他任何情况,请参阅文档中的 [故障排除](https://code.claude.com/docs/en/claude-code-on-the-web#troubleshooting),包括 [连接 GitHub 后没有出现任何仓库](https://code.claude.com/docs/en/web-quickstart#no-repositories-appear-after-connecting-github)。要完全断开 GitHub,请使用 claude.ai/customize/connectors。 ## 为会话提供检查自身工作所需的条件 能够运行你的测试的会话会在交回工作之前检查自己的工作。否则,你审查的是没人运行过的更改。本指南演示中的大部分价值来自 Claude 运行各种东西:测试套件运行了 40 次、服务器及其 curl 请求、窗口边缘的潮汐计算。十分钟的环境设置就能让 Claude 有办法运行这些检查。 ![The Add cloud environment dialog with the name tidepool, Trusted network access, LOG\_LEVEL=debug, and a setup script that installs shellcheck with apt-get.](https://claude.dev/media/aba93ba97b08d40ee9705338d22e861ed592cc8a7e32b8ddd715b6545b3c4fcd.png) **图 M**在 claude.ai/code 界面中添加云环境,使用示例值在本地运行:名称、网络访问级别、.env 格式的变量,以及一个设置脚本 - **从 Default 环境开始。**它使用 Trusted 网络访问、无变量、无设置脚本,这对大多数 JavaScript、Python、Go 和 Rust 仓库来说已经足够。 - **为机器使用设置脚本。**它在 Claude Code 启动前以 root 身份运行,因此 `apt install` 可以正常工作。它必须以 0 退出,否则会话不会启动,并且应在约五分钟内完成,以便环境被缓存。之后,新会话将从磁盘上带有你的工具的快照启动。当你更改脚本或允许的主机时,缓存会重建,大约每七天也会重建一次。 - **为项目使用 SessionStart 钩子。**将 `npm install` 及类似步骤放入仓库 `.claude/settings.json` 中的钩子,这样它们在本地和云端以相同方式运行。如果某个步骤只应在云端运行,请检查 `CLAUDE_CODE_REMOTE`。仓库钩子会在单仓库会话中加载。 - **按会话启动服务。**缓存存储的是文件。之前运行的进程不会在缓存中保留。让 Claude 运行 `service postgresql start`,或在 SessionStart 钩子中执行。 - **选择能正常工作的最窄网络级别。**Trusted 覆盖常见注册表。使用 Custom 添加私有注册表,仅在任务需要开放互联网时使用 Full。更改会在大约一分钟内到达正在运行的会话。 - **让密钥远离共享变量。**环境变量对任何使用该环境的人都可见。在 Pro 和 Max 上,环境的 API 凭据会在 VM 之外为你指定的主机请求附加一个密钥,因此密钥永远不会存在于变量中。 - **将命令放入 CLAUDE.md。**你的个人 `~/.claude` 不会到达云端 VM。如果 Claude 需要知道如何运行集成测试,仓库必须说明。 ## 值得养成的习惯 - **一个任务,一个会话。**小而独立的会话更易于审查,丢弃成本也更低。 - **要求提供证据。**说出能证明任务已完成的命令,并在查看 diff 之前阅读 Claude 的总结。 - **在 `claude --cloud` 之前推送。**VM 从 GitHub 克隆,因此未推送的提交不会到达它。 - **在长任务中随时提交。**空闲的 VM 可能会被回收。 - **在 diff 视图中审查。**行内评论会批量合并到你的下一条消息中,**Create PR** 可以打开完整 PR、草稿或 GitHub 的撰写页面。 - **在 Claude 工作时进行引导。**你在 Claude 工作时发送的消息会排队,你可以撤回一条已排队的消息。 - **共享会话。**在 Team 和 Enterprise 上,将会话的可见性设置为 Team,以便审查者可以阅读更改是如何完成的。来自云会话的提交带有一个 `Claude-Session` 尾注,链接回对话记录。 - **注意你的限制。**并行会话会并行消耗你的计划限制,因此五个会话消耗它们的速度大约是一个会话的五倍。Routines 有自己的每小时上限,而 [projects](https://code.claude.com/docs/en/claude-projects) 每天最多可启动 200 个新线程。 ## 常见问题 **谁可以使用云会话?**Pro、Max 和 Team 计划,以及拥有高级席位或 Chat + Claude Code 席位的 Enterprise 用户,并使用 claude.ai 账户登录。它们不适用于 Console API 密钥或第三方提供商。请参阅 [云会话文档](https://code.claude.com/docs/en/claude-code-on-the-web)。 **我的数据会去哪里?** Anthropic 会存储会话记录,保留时长取决于你的套餐和模型改进设置。虚拟机在闲置后会被回收,删除会话会移除其数据。参见[数据使用](https://code.claude.com/docs/en/data-usage)和[安全性](https://code.claude.com/docs/en/security)。 **Claude 会用我的云会话数据来训练吗?** 云会话遵循与 Claude Code 其余部分相同的政策。在 Team、Enterprise 和 API 上,除非你的组织选择加入,否则 Anthropic 不会用你的代码或提示来训练模型。在 Free、Pro 和 Max 上,这取决于你的[模型改进设置](https://claude.ai/settings/data-privacy-controls)。参见[数据使用](https://code.claude.com/docs/en/data-usage)。 **它能处理我的大型代码仓库吗?** 虚拟机大约有 4 个 vCPU、16 GB 内存和 30 GB 磁盘。把繁重的安装放进[安装脚本](https://code.claude.com/docs/en/cloud-environments#setup-scripts),这样它们只运行一次并进入缓存的快照。 **GitLab 或 Bitbucket 呢?** `claude --cloud` 可以从任何 git 仓库上传 bundle,但会话无法推送回这些托管平台。[GitHub Enterprise Server](https://code.claude.com/docs/en/github-enterprise-server) 在 Team 和 Enterprise 上受支持。参见[平台限制](https://code.claude.com/docs/en/claude-code-on-the-web#limitations)。 **并行分支发生冲突时会怎样?** 这些会话彼此并不知晓。先合并一个分支,然后[向下一个会话发送后续消息](https://code.claude.com/docs/en/claude-code-on-the-web#send-follow-ups-from-the-cli),例如 `claude -p "rebase on main and fix any conflicts" --cloud `。 **我会失去本地工具吗?** 用户级配置不会随之迁移,所以把团队需要的内容放进仓库:将技能和命令提交到 `.claude/` 下,把项目范围的 MCP 服务器添加到 `.mcp.json`,并在 `CLAUDE.md` 中记录测试命令。[云会话中的设置](https://code.claude.com/docs/en/settings#settings-in-cloud-sessions)列出了每个会话会读取的内容。 ## 五分钟内开始 设置大约需要五分钟。之后,你就可以交出一个任务,合上笔记本电脑,回来时看到一个可供审查的分支。 1. 打开 claude.ai/code,或使用你的 claude.ai 账户在 Claude Code 中运行 `/login`。 2. 连接 GitHub,并在你的仓库所在位置安装 Claude GitHub App。 3. 选择仓库和 Default 环境。 4. 从你的待办事项中给 Claude 一个任务,并附上一条能证明任务完成的命令。 5. 关闭标签页。稍后用手机查看,然后审查 diff 并在 claude.ai/code 创建拉取请求。 ## 正文 · 原文 You probably run Claude Code in a terminal on your own laptop. That session depends on the laptop in three ways: - It shares your working tree, so two sessions on one repository can edit the same files and fight over the same port. - It runs with your credentials. - It stops when your computer sleeps or the Wi-Fi drops. [A cloud session](https://code.claude.com/docs/en/claude-code-on-the-web) runs Claude Code on a machine of its own. Each task gets a fresh virtual machine with your repository cloned onto a new branch and your environment's setup already done. You can start one from [claude.ai/code](https://code.claude.com/docs/en/web-quickstart), the [Claude mobile app](https://code.claude.com/docs/en/mobile), the [Desktop app](https://code.claude.com/docs/en/desktop#run-long-running-tasks-in-the-cloud), your [terminal](https://code.claude.com/docs/en/claude-code-on-the-web#from-terminal-to-cloud), and [Slack](https://code.claude.com/docs/en/slack). You can then follow it from the browser, the mobile app, and Desktop. When the work is done, it sits on a branch you can turn into a pull request. Cloud sessions come with your Pro, Max, Team, or Enterprise plan at no additional cost: there's no separate charge for the cloud machine, and sessions draw on the same usage limits as the rest of Claude Code. Depending on your plan, an organization owner may need to [turn on cloud sessions](https://claude.ai/admin-settings/claude-code) first. **Bonus credit for cloud sessions.** Existing individual Pro and Max subscribers can claim a one-time bonus credit for cloud sessions, on top of their plan limits: $100 on Pro and $250 on Max. Claim it by October 7 at claude.ai/code/claim-credit or with `/claim-credit` in Claude Code. The credit expires on November 4. After it's used or expires, your plan's regular usage applies. It isn't eligible for Projects or Routines. See the [Promotional Credit Offer Terms](https://www.anthropic.com/legal/promotion-credit-terms). For this guide I ran four real cloud sessions against a small sample repository. Their transcripts, diffs, and timings appear throughout. The repository and the user in the screenshots are made up. The work, the output, and the numbers come from those sessions. One of the main advantages of cloud sessions is that you can run several tasks at once without them getting in each other's way. Here are three I started within 16 seconds of each other, each on its own machine. On my laptop, I'd have run these one after another, or spent my time keeping them out of each other's way. ![Timeline of three cloud sessions in three VMs, started within 16 seconds of each other. After a hatched setup bar, the flaky-test fix finishes at 65 seconds with the suite run 40 times and 0 failures, the docs rewrite at 62 seconds with 5 doc errors fixed, and the structured-logging change at 87 seconds with JSON logs and 5 new tests.](https://claude.dev/media/58bd02532f8c5914f4dc430c84caddcb4158c4dc7b2905bcf602c9cb439ab5e2.png) **FIG A**The real timeline of three cloud sessions on one repository, in seconds from the first start. Hatched bars are the setup step that recreated the sample repository (a GitHub clone replaces it in normal use), and each dot is one tool call. ## THREE TASKS, ONE REPOSITORY, THREE MACHINES The sample repository is **tidepool**, a small Node API that predicts tides for three fictional harbors. It had three ordinary problems: one test failed about one run in four, the API docs described parameters the code no longer read, and the logger built its lines by concatenating strings. I started three cloud sessions within 16 seconds of each other, one per problem. I started them programmatically, and because tidepool isn't on GitHub, each session first recreated the repository from files in its prompt. With a real repository you'd skip that step, and from a terminal each session is one `claude --cloud` command. Shortened, the three prompts were: CODEShell claude --cloud "npm test fails maybe one run in four. Find the flaky test, fix the root cause in the code (not the test), and prove it by running the suite at least 30 times in a row." claude --cloud "docs/API.md is out of date with src/server.js. Rewrite it so every endpoint, parameter, default and response shape matches the code. Start the server and run each curl example to check it." claude --cloud "Make src/logger.js emit one JSON object per line, keep LOG\_LEVEL, and log method, path, status and duration\_ms as fields. Add a test for the logger." The sessions ran for 61, 65 and 72 seconds, and all three were done 87 seconds after the first one started. Recreating the repository took roughly a third to just over half of each run. Here are the results. - **The flaky test.** Claude found a race in `TtlCache.get`. The cache stored a value only after the loader finished, so a second `get` for the same key during a load called the loader again. Claude changed the cache to store the in-flight promise, dropped the entry when a load fails, and ran `npm test` 40 times in a row with zero failures. - **The docs.** Claude started the server, ran a curl against every endpoint, and found five ways the old doc was wrong. It listed fields the API never returns, documented a `days` parameter the code ignores, gave heights in feet when they are metres, skipped the `/next-high` endpoint, and left out the error responses. It also found that a malformed `from=` value returns an empty list with a 200, and documented that as a caveat instead of changing server code it wasn't asked to touch. - **The logger.** Claude wrote the JSON logger, moved the request log to structured fields, and added five tests. Its commit went in with one failing test, so Claude reran the cache test eight times, saw it fail in five of them, and traced the failure to the same race the first session was fixing. It proposed the same fix, left the cache alone because that was outside its task, and said in its summary that the suite wasn't clean. **FIG E**A 20-second recording of the same local build: clicking between the three sessions, then scrolling the logger session's transcript The logger result shows why cloud sessions suit parallel work. Each session had its own copy of the repository, its own processes and its own branch. The docs session and the logger session each started the API server to test against it, and neither affected the other. On a single laptop, two agents working in one checkout would edit the same files, and would collide on a port unless each picked its own. Because of that isolation, the logger session had no access to the cache fix the first session was making. Split parallel tasks along file boundaries, merge the branches in a sensible order, and expect a session to report problems that another session is already fixing. ## UNDER THE HOOD OF A CLAUDE CODE CLOUD SESSION A cloud session is a Claude Code session running on Anthropic-managed infrastructure, or on your organization's own machines with a [self-hosted environment](https://code.claude.com/docs/en/self-hosted-environments). The figure shows the parts. The four takeaways after it are the ones that change how you work. ![You start a session from a browser, phone, Desktop, terminal, Slack or a routine. It runs in a fresh VM with a clone of your repository on a claude branch, Claude Code in auto mode, and your environment's setup. GitHub traffic passes through a proxy that holds your token outside the VM; other traffic passes through a security proxy that applies the network allowlist. The result is a branch and a pull request.](https://claude.dev/media/7c0f2a65796202281cbc6ededff3f0dbfe216aca98e3831640eec064e2b85165.png) **FIG F**Anatomy of a cloud session. Everything the agent can touch sits inside the VM. Your GitHub token and the network policy sit outside it. - **Every task gets its own machine.** A fresh VM with your repository cloned onto a new branch, so sessions can't touch each other's files or ports. See [what's installed](https://code.claude.com/docs/en/cloud-environments#installed-tools). - **Your GitHub token never enters the VM.** A proxy holds it, and the session gets a short-lived credential that can push only to its own working branch. See the [GitHub proxy](https://code.claude.com/docs/en/cloud-environments#github-proxy). - **The repository's Claude config comes along. Your personal one doesn't.** `CLAUDE.md`, rules, skills, agents, and commands travel with the repo, and your `~/.claude` stays on your laptop. See [settings in cloud sessions](https://code.claude.com/docs/en/settings#settings-in-cloud-sessions). - **Idle VMs get reclaimed.** Reopen the session and you get a fresh VM with the conversation restored, so commit work you care about. See [environment expiry](https://code.claude.com/docs/en/claude-code-on-the-web#environment-expired). For specs, [permission modes](https://code.claude.com/docs/en/permission-modes), and network levels, see the [cloud environments docs](https://code.claude.com/docs/en/cloud-environments). ## LOCAL OR CLOUD? Cloud sessions don't replace local ones, and most people use both. The table shows where they differ, and the paragraphs after it say when each one fits. | | Local session | Cloud session | | --- | --- | --- | | Runs on | Your machine | A fresh VM for each task | | Laptop asleep or offline | The session stops | The session keeps going | | Several tasks on one repo | Separate worktrees, ports and care | One VM and one branch per task | | What the agent can reach | Anything your user account can, including SSH keys, cloud CLIs and `~/.claude` | The repository, the network level you set, the connectors you enable, and a session-scoped GitHub credential | | Start or follow from | That machine, or your phone through remote control | Browser, phone, Desktop, terminal, Slack, an API call or a schedule | | Approvals | Any mode, including per-command | Auto, Accept edits or Plan | | Ends with | Changes in your working tree | A branch, and a pull request when you want one | | Compute | Your machine | No separate compute charge; uses your plan's limits | Stay local when the task needs something only your machine has. That covers a database with real local data, a service you reach over VPN, a GPU, a phone simulator, or hardware on your desk. Stay local too for tight visual loops where you want to see each change in your own browser within seconds, and when your organization runs with [Zero Data Retention](https://code.claude.com/docs/en/zero-data-retention), which turns cloud sessions off. Two features sit between the options. **Remote control** keeps the session on your machine and lets you steer it from your phone or browser. **[Self-hosted environments](https://code.claude.com/docs/en/self-hosted-environments)**, in beta for Team and Enterprise, run cloud sessions on your organization's own infrastructure, so they can reach private networks. If none of that applies, the task is a good candidate for the cloud. The next section covers the workflows where that pays off most. ## SEVEN WORKFLOWS THAT SUIT CLOUD SESSIONS These workflows put the differences in the table to work: a separate machine for each task, sessions that keep running while you're away, and a branch at the end for you to review. ### 1\. Clear a backlog in parallel Let's say you have five small, unrelated fixes. Locally, you'd do them one after another, or set up five worktrees and keep their ports and installs apart. In the cloud, you'd start five sessions and review five branches. CODEShell claude --cloud "Fix the flaky test in auth.spec.ts" claude --cloud "Update the API documentation" claude --cloud "Refactor the logger to use structured output" `claude --cloud` clones your GitHub remote at your current branch, so push your local commits first. While the VM starts, the CLI shows a live checklist of setup steps and queues anything you type. Write each task as a self-contained ticket that states what's wrong, what done looks like, and how to prove it. The flaky-test prompt named its proof: running the suite at least 30 times in a row. The session ran it 40 times. When the tasks belong to one larger effort, a **[project](https://claude.com/blog/projects-redesigned)** (public beta for Pro and Max) runs a coordinator conversation that starts and tracks the cloud sessions for you. It then groups them by state: working, waiting on you, and ready for review. ### 2\. Let it prove the fix A flaky test is the clearest case of work that needs repeated proof: you have to run the suite again and again, and you don't want that loop tying up the machine you're working on. In the cloud, Claude patched the cache and ran the whole suite 40 times in one command. ![The flaky-test session's Bash step: a patch to src/cache.js that caches the in-flight promise, then a loop running the test suite 40 times, with output runs=40 fails=0.](https://claude.dev/media/6ce551ccd1a1cd64a0f9c0fb8b8116e1ca1e260a9f5de861de798e0fe578afe6.png) **FIG G**Forty runs, zero failures: the flaky-test session's real command and output, replayed in the claude.ai/code interface running locally. Claude patched src/cache.js and looped the full suite 40 times in one step. Paths show under /home/user. The VM has no compute charge and its CPU isn't yours, so ask for thorough proof. Run the suite 200 times, bisect a regression across 50 commits, run the slow integration tier, or start the app and hit it with curl the way the docs session did. Each of Claude's turns still counts toward your plan, but a long test run inside one command costs little. [Foreground commands](https://code.claude.com/docs/en/cloud-environments) time out after 2 minutes by default (10 at most) and then keep running in the background for up to 30 more. You can raise the defaults with `BASH_DEFAULT_TIMEOUT_MS` and `BASH_MAX_TIMEOUT_MS` in the environment's variables. ### 3\. Plan at your desk, build in the cloud, finish in your terminal For a larger change, agree on the approach first where back-and-forth is cheap. Start Claude in plan mode, work out the plan together, commit the plan, and push it. CODEShell claude --permission-mode plan \# ...agree on the plan, save it to docs/migration-plan.md, commit and push... claude --cloud "Execute the migration plan in docs/migration-plan.md" While the cloud session builds, your terminal is free for other work. When it's done, pull the session down to finish it by hand. CODEShell claude --teleport \# pick a cloud session claude --teleport Teleport checks that you're in the same repository, fetches the session's branch, checks it out, and loads the whole conversation into your terminal. You need a clean working tree (it offers to stash), and the branch has to be pushed. From inside Claude Code, `/teleport` (or `/tp`) opens the same picker, and `/tasks` then `t` works too. The Desktop app goes the other way, and its **Open in** menu sends a local session to the cloud. ### 4\. Check in from your phone The Code tab in the Claude app connects to the same sessions. From your phone you can start a task, follow it, steer it, answer a question Claude asked, or tell Claude to watch a pull request. A phone suits questions you'd otherwise forget by the time you reach a keyboard. I gave a fourth session the kind of question you'd type on one: how does tidepool predict tides, and how could it go wrong at the edges of a time window? It ran code to check its answer and found a real bug. The loop never examines the first or last sample, so the API misses a high tide that falls exactly at the start of the window. ### 5\. Hand CI failures and review comments to Claude With the Claude GitHub App installed on a repository, a cloud session can watch a pull request and act on what happens to it. From the CI bar in a session at claude.ai/code, turn on **Auto-fix**. You can also run `/autofix-pr` on the PR branch in your terminal, ask the mobile app to watch the PR, or paste the PR URL into a session. Claude pushes clear fixes for failing checks and review comments, and explains what it changed. It asks you about anything ambiguous or architectural. Replies on review threads post under your GitHub username, labeled as Claude Code. Claude doesn't get notified about merge conflicts with the base branch, so ask it to rebase. Its comments can also trigger comment-driven automation such as Atlantis. ### 6\. Start work without starting it yourself A **routine** (research preview) is several saved resources designed to accomplish a task, such as a prompt, repositories, connectors, and an environment. Each run is a cloud session, started by a trigger. Triggers can be a schedule (hourly at most often), an HTTP call to the routine's own endpoint, or a GitHub event such as a pull request opening or a release. Create one at claude.ai/code/routines, in the Desktop app, or with `/schedule` in the CLI. Routines run without approval prompts, and by default they push to `claude/`\-prefixed branches. Two smaller tools help here. You can queue a follow-up into a running session from any machine where you're logged in, including a CI job. CODEShell claude -p "The integration tier is green now; rebase on main and push" --cloud You can also bookmark a prefilled session. A URL such as `claude.ai/code?prompt=Triage+the+newest+issues&repositories=acme-labs/tidepool` opens claude.ai/code with the prompt and repository already filled in. ### 7\. Run code you don't fully trust A contributor's pull request, a new dependency's install script, or a repository you cloned five minutes ago can all run code you haven't read. On your laptop, that code runs next to your SSH keys, your cloud CLI sessions and your browser profile. In a cloud session it runs in a disposable VM with none of those, a session-scoped GitHub credential, and a network you can narrow. Set the environment's network access to **None** for the strictest run, or keep **Trusted**, which allows package registries, GitHub and the major cloud SDK hosts. Even at None, Claude Code still sends requests to the Anthropic API, so data can leave the VM that way, and the session can still push to its own branch. All outbound traffic passes through a proxy that logs hostnames. ## CONNECTING GITHUB WITHOUT GETTING STUCK If your first cloud session goes wrong, GitHub is the most likely reason. Most problems come from cloud sessions needing two separate GitHub permissions. - **Signing in with GitHub** tells Claude who you are. - **Installing the Claude GitHub App** on an account or organization sets which private repositories Claude can see there. Public repositories work with the first alone. Private repositories need the second, on whichever account or organization owns them. If you connected GitHub and a private repository is missing, the App usually isn't installed on the account or organization that owns it. | What you've connected | Public repos | Your private repos | An org's private repos | Auto-fix, GitHub triggers, projects | | --- | --- | --- | --- | --- | | Signed in with GitHub only | Yes | No | No | No | | \+ App on your personal account | Yes | Yes | No | Your repos | | \+ App on the organization (owner approves) | Yes | Only if also on your account | Yes | Org repos | | `/web-setup` (your `gh` token) | Yes | Yes | Whatever your token can reach | No, needs the App | ### Path A: connect in the browser (recommended) Connect your GitHub account at [claude.ai/connect-github](https://claude.ai/connect-github), then install the Claude GitHub App on the account or organization that owns your repository. For an organization, an owner usually has to approve the install. The [quickstart](https://code.claude.com/docs/en/web-quickstart) walks through each step. If GitHub doesn't send you back to claude.ai/code, the connect page at [claude.ai/connect-github](https://claude.ai/connect-github) can show a short checklist for the usual causes. One of them is the single sign-on step, which hides an organization's repositories if you skip it. ![The Didn't finish connecting screen with five tips: sign in to the right GitHub account, authorize each organization on the single sign-on step, start again if you saw GitHub connection not completed, connect your own account first and let an owner approve organization access later, or run /web-setup from the terminal.](https://claude.dev/media/0855b55ac62191f9b92cd9f5f1d5ab2d8181b03eb155678dd859cc7c8f8722ed.png) **FIG L**If GitHub doesn't send you back: the product's own checklist for an interrupted GitHub connection, from the quick-setup onboarding flow in the claude.ai/code interface running locally Auto-fix, GitHub-triggered routines and projects also depend on the App, so install it even if you connect another way. ### Path B: connect from your terminal with /web-setup If you already use the `gh` CLI, run `/web-setup` inside Claude Code to send your `gh` token to your Claude account. Sessions can then reach any repository that token can, with or without the App. See [Connect from your terminal](https://code.claude.com/docs/en/web-quickstart#connect-from-your-terminal) for the walkthrough. On Team and Enterprise plans, an owner has to turn on [Quick setup](https://code.claude.com/docs/en/claude-code-on-the-web#quick-setup-for-team-and-enterprise) first. ### Path C: skip GitHub for a one-off Run `claude --cloud` in a repository that has no GitHub remote, or one where the App isn't installed, and Claude Code uploads a bundle of your repository instead of cloning it. The session can push back only if your GitHub connection has push access to that repository. The docs list [what the bundle includes and leaves out](https://code.claude.com/docs/en/claude-code-on-the-web#send-local-repositories-without-github). ### If you run Team or Enterprise An owner has a short checklist: turn on the GitHub connector at [claude.ai/admin-settings/connectors](https://claude.ai/admin-settings/connectors), allow cloud sessions in the [Claude Code admin settings](https://claude.ai/admin-settings/claude-code), install the Claude GitHub App on the organization's repositories (or approve members' requests), and decide whether to turn on [Quick setup](https://code.claude.com/docs/en/claude-code-on-the-web#quick-setup-for-team-and-enterprise). Organizations with IP allowlists or GitHub Enterprise Server have an extra step. See the docs on [IP allowlists](https://code.claude.com/docs/en/claude-code-on-the-web#limitations) and [GitHub Enterprise Server](https://code.claude.com/docs/en/github-enterprise-server). ### When it still doesn't work | What you see | Why | Fix | | --- | --- | --- | | A private repository is missing from the picker | The App isn't installed on the account or organization that owns it, or its repository access excludes it | Install the App there, or add the repository to the App's Repository access in your GitHub settings | | An error saying you must be an owner of the organization to link it | The organization blocked a membership check, usually because of a pending App permission request, an IP allow list, or SAML single sign-on | An owner accepts the pending permission request in the organization's GitHub App settings, turns on IP allow list inheritance for installed GitHub Apps, or (under SAML) grants Claude access to the organization | | An organization's repositories are missing right after you connect | The organization uses SAML single sign-on, and its authorization step was skipped | On GitHub's "Single sign-on to your organizations" step, click **Authorize** next to each organization before you continue. If you already skipped it, authorize Claude for that organization in your GitHub settings, then reconnect | | Every cloud session fails with an authentication error | Your Claude organization uses IP allowlisting | Ask support to exempt Anthropic-hosted services | For anything else, see [troubleshooting](https://code.claude.com/docs/en/claude-code-on-the-web#troubleshooting) in the docs, including [no repositories appearing after you connect GitHub](https://code.claude.com/docs/en/web-quickstart#no-repositories-appear-after-connecting-github). To disconnect GitHub entirely, use claude.ai/customize/connectors. ## GIVE SESSIONS WHAT THEY NEED TO CHECK THEIR OWN WORK A session that can run your tests checks its own work before it hands the work back. Without that, you review changes nobody has run. Most of the value in this guide's demos came from Claude running things: the suite 40 times, the server and its curls, the tide calculation at the window's edge. Ten minutes of environment setup gives Claude a way to run those checks. ![The Add cloud environment dialog with the name tidepool, Trusted network access, LOG\_LEVEL=debug, and a setup script that installs shellcheck with apt-get.](https://claude.dev/media/aba93ba97b08d40ee9705338d22e861ed592cc8a7e32b8ddd715b6545b3c4fcd.png) **FIG M**Adding a cloud environment in the claude.ai/code interface, running locally with sample values: a name, a network access level, variables in .env format, and a setup script - **Start with the Default environment.** It uses Trusted network access, no variables and no setup script, which is enough for most JavaScript, Python, Go and Rust repositories. - **Use a setup script for the machine.** It runs as root before Claude Code starts, so `apt install` works. It must exit 0 or the session won't start, and it should finish within about five minutes so the environment gets cached. After that, new sessions start from a snapshot with your tools on disk. The cache rebuilds when you change the script or the allowed hosts, and about every seven days. - **Use a SessionStart hook for the project.** Put `npm install` and similar steps in a hook in the repository's `.claude/settings.json`, so they run the same way locally and in the cloud. Check `CLAUDE_CODE_REMOTE` if a step should run only in the cloud. Repository hooks load in single-repository sessions. - **Start services per session.** The cache stores files. Processes that were running don't survive it. Ask Claude to run `service postgresql start`, or do it in a SessionStart hook. - **Pick the narrowest network level that works.** Trusted covers the common registries. Use Custom to add a private registry, and Full only when the task needs the open internet. Changes reach running sessions within about a minute. - **Keep secrets out of shared variables.** Environment variables are visible to anyone who uses the environment. On Pro and Max, an environment's API credentials attach a key to requests for the hosts you name, outside the VM, so the key never sits in a variable. - **Put the commands in CLAUDE.md.** Your personal `~/.claude` doesn't reach the cloud VM. If Claude needs to know how to run the integration tests, the repository has to say so. ## HABITS THAT PAY OFF - **One task, one session.** Small, separate sessions are easier to review and cheaper to throw away. - **Ask for evidence.** Name the command that proves the task is done, and read Claude's summary before the diff. - **Push before `claude --cloud`.** The VM clones from GitHub, so unpushed commits don't reach it. - **Commit as you go on long tasks.** Idle VMs can be reclaimed. - **Review in the diff view.** Inline comments are batched into your next message, and **Create PR** can open a full PR, a draft, or GitHub's compose page. - **Steer while Claude works.** Messages you send while Claude works queue up, and you can take a queued one back. - **Share the session.** On Team and Enterprise, set a session's visibility to Team so a reviewer can read how the change was made. Commits from cloud sessions carry a `Claude-Session` trailer that links back to the transcript. - **Watch your limits.** Parallel sessions draw on your plan limits in parallel, so five sessions use them about five times as fast as one. Routines have their own hourly caps, and [projects](https://code.claude.com/docs/en/claude-projects) can start up to 200 new threads a day. ## COMMON QUESTIONS **Who can use cloud sessions?** Pro, Max, and Team plans, and Enterprise users with a premium seat or a Chat + Claude Code seat, signed in with a claude.ai account. They aren't available with a Console API key or a third-party provider. See the [cloud sessions docs](https://code.claude.com/docs/en/claude-code-on-the-web). **Where does my data go?** Anthropic stores the session transcript, and how long it's kept depends on your plan and model-improvement setting. VMs are reclaimed after inactivity, and deleting a session removes its data. See [data usage](https://code.claude.com/docs/en/data-usage) and [security](https://code.claude.com/docs/en/security). **Will Claude train on my cloud sessions data?** Cloud sessions follow the same policy as the rest of Claude Code. On Team, Enterprise, and the API, Anthropic doesn't train models on your code or prompts unless your organization opts in. On Free, Pro, and Max, it depends on your [model-improvement setting](https://claude.ai/settings/data-privacy-controls). See [data usage](https://code.claude.com/docs/en/data-usage). **Will it handle my large repository?** The VM has about 4 vCPUs, 16 GB of RAM, and 30 GB of disk. Put heavy installs in a [setup script](https://code.claude.com/docs/en/cloud-environments#setup-scripts) so they run once and land in the cached snapshot. **What about GitLab or Bitbucket?** `claude --cloud` can upload a bundle from any git repository, but the session can't push back to those hosts. [GitHub Enterprise Server](https://code.claude.com/docs/en/github-enterprise-server) is supported on Team and Enterprise. See the [platform restrictions](https://code.claude.com/docs/en/claude-code-on-the-web#limitations). **What happens when parallel branches conflict?** The sessions don't know about each other. Merge one branch, then [send the next session a follow-up](https://code.claude.com/docs/en/claude-code-on-the-web#send-follow-ups-from-the-cli) such as `claude -p "rebase on main and fix any conflicts" --cloud `. **Will I lose my local tools?** User-level config doesn't travel, so move what the team needs into the repository: commit skills and commands under `.claude/`, add project-scoped MCP servers to `.mcp.json`, and document test commands in `CLAUDE.md`. [Settings in cloud sessions](https://code.claude.com/docs/en/settings#settings-in-cloud-sessions) lists what each session reads. ## START IN FIVE MINUTES Setup takes about five minutes. After that, you can hand off a task, close your laptop, and come back to a branch that's ready for review. 1. Open claude.ai/code, or run `/login` in Claude Code with your claude.ai account. 2. Connect GitHub and install the Claude GitHub App where your repository lives. 3. Pick the repository and the Default environment. 4. Give Claude one task from your backlog, with a command that proves it's done. 5. Close the tab. Check in from your phone later, then review the diff and create the pull request at claude.ai/code.