Claude Code 走向云端：云端会话（Cloud Sessions）实战指南

你可能习惯在自己笔记本电脑的终端里运行 Claude Code。这种本地会话在三个方面依赖你的电脑：

• 它共享你的工作树（Working Tree），因此在同一个代码仓库上启动两个会话可能会修改相同的文件，甚至争抢同一个端口。
• 它使用你的个人凭据运行。
• 一旦电脑休眠或 Wi-Fi 断开，会话就会停止。

云端会话（Cloud session） 则让 Claude Code 运行在专属于它自己的机器上。每个任务都会获得一个全新的虚拟机，你的代码仓库会被克隆到一个新分支上，并且环境配置已自动就绪。

你可以从 claude.ai/code、Claude 移动应用、桌面应用、你的终端以及 Slack 启动云端会话。随后你可以通过浏览器、移动端和桌面端跟进进度。当工作完成后，改动会保存在一个分支上，你可以随时将其转换为拉取请求（Pull Request）。

云端会话包含在你的 Pro、Max、Team 或 Enterprise 计划中，无需额外付费：云端机器不收取单独费用，会话消耗的额度与 Claude Code 其余功能相同。根据你订阅的计划，组织所有者可能需要先开启云端会话。

云端会话奖励额度： 现有的 Pro 和 Max 个人订阅用户可以在其套餐限制之外领取一次性云端会话奖励额度：Pro 用户可领 100 美元，Max 用户可领 250 美元。请在 10 月 7 日前在 claude.ai/code/claim-credit 领取，或在 Claude Code 中输入 /claim-credit 领取。该额度将于 11 月 4 日到期。使用完毕或过期后，将恢复按套餐常规用量计费。该额度不适用于 Projects 或 Routines。详见促销额度条款。

为了编写本指南，我针对一个小型的示例代码仓库运行了四次真实的云端会话。它们的执行过程记录、代码 Diff 和耗时数据贯穿全文。截图中的仓库和用户名是虚拟的，但任务内容、输出和数据均来自这些实际会话。

云端会话的核心优势之一，在于你可以同时运行多个任务，而它们彼此不会互相干扰。以下是我在 16 秒内相继启动的三个任务，每个任务都在独立的机器上运行。如果放在笔记本电脑上，我必须串行执行它们，或者耗费大量精力防止它们互相冲突。

图 A 在同一个代码仓库上运行三个云端会话的真实时间线，以第一次启动后的秒数为单位。阴影条带是重建示例代码仓库的配置步骤（在常规使用中会被 GitHub 克隆取代），每个圆点代表一次工具调用（Tool Call）。

三个任务，一个仓库，三台机器

示例代码仓库名为 tidepool，是一个用于预测三个虚构港口潮汐的小型 Node API。它存在三个常见的典型问题：某个测试每运行四次大约会失败一次；API 文档中描述的参数代码中早已不再读取；日志记录器通过拼接字符串来生成日志行。

我在 16 秒内启动了三个云端会话，每个问题对应一个。我是通过程序化方式启动它们的，而且由于 tidepool 并没有托管在 GitHub 上，每个会话首先需要根据 Prompt 中的文件重建仓库。在真实代码仓库中你可以跳过这一步，而在终端中，每个会话只需要执行一条 claude --cloud 命令。精简后的三个提示词如下：

bash 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 秒内全部完成。重建代码仓库的大约占用了每次运行三分之一到一半出头的时间。以下是任务执行结果：

• 不稳定测试（Flaky test）： Claude 在 TtlCache.get 中发现了一处竞态条件（Race Condition）。缓存只有在加载器执行完成后才会存储值，因此在加载过程中对同一个 Key 发起第二次 get 会再次调用加载器。Claude 修改了缓存逻辑以存储进行中的 Promise，并在加载失败时丢弃该条目，随后连续运行了 40 次 npm test，全部通过且零失败。
• 文档更新： Claude 启动了服务器，对每个端点执行了 curl 请求，并发现了旧文档存在的 5 处错误：列出了 API 从未返回的字段；记录了一个代码完全忽略的 days 参数；潮汐高度原本是米却写成了英尺；遗漏了 /next-high 端点；缺少错误响应说明。它还发现传入畸形的 from= 参数会返回状态码 200 及空列表，Claude 将其作为注意事项写入文档，而不是擅自修改未被要求改动的服务端代码。
• 日志记录器： Claude 编写了 JSON 日志记录器，将请求日志改为结构化字段，并添加了 5 个测试用例。它的提交中包含一个失败测试，因此 Claude 重复运行了 8 次缓存测试，发现其中 5 次失败，并顺藤摸瓜定位到了与第一个会话正在修复的完全相同的竞态条件。它提出了相同的修复方案，但由于这超出了本次任务的范畴而保留了缓存代码原样，并在任务摘要中明确指出测试套件尚未完全通过。

图 B claude.ai/code 界面中的三个会话，本地运行并回放其真实记录。配置步骤已精简，路径显示在 /home/user 下，底部三个侧边栏标题为占位内容，模式指示器显示为默认。

图 C 修复不稳定测试会话

图 D 更新 tidepool API 文档会话

[视频/嵌入内容：同一本地构建的 20 秒录屏：在三个会话之间点击切换，并滚动浏览日志会话的过程记录](FIG E)

日志记录任务的结果印证了为什么云端会话极其适合并行工作。每个会话都有自己独立的代码仓库副本、独立的进程和独立的分支。文档会话和日志会话都各自启动了 API 服务器来进行验证测试，两者互不干扰。如果是在同一台笔记本电脑上，两个 Agent 在同一个检出目录下工作会修改同一批文件，而且除非各自指定端口，否则必然会发生端口冲突。

正是由于这种隔离性，日志会话无法直接访问第一个会话正在进行的缓存修复。因此，请尽量沿文件边界拆分并行任务，按合理的顺序合并分支，并预期某个会话可能会报告另一个会话已经在修复的问题。

Claude Code 云端会话的技术内幕

云端会话是指运行在 Anthropic 托管的基础设施上，或通过自托管环境（Self-hosted environments）运行在企业自身机器上的 Claude Code 会话。下图展示了其组成架构。图表后的四条核心要点将改变你的工作方式。

图 F 云端会话架构剖析。Agent 能够操作的所有内容均位于虚拟机内部。你的 GitHub Token 和网络策略则位于虚拟机外部。

• 每个任务独享一台机器。 独立的全新虚拟机，代码仓库克隆到专属新分支上，因此会话之间绝不会产生文件或端口冲突。参见预装工具列表。
• 你的 GitHub Token 绝不会进入虚拟机。 由外部代理持有 Token，会话仅获得短期的临时凭据，并且该凭据仅具备推送到自身工作分支的权限。参见 GitHub 代理。
• 继承代码仓库的 Claude 配置，但不包含个人配置。 CLAUDE.md、规则、Skills、Agents 和命令都会随仓库同步生效，而你本地的 ~/.claude 配置仍留在笔记本电脑上。参见云端会话中的设置项。
• 闲置虚拟机自动回收。 重新打开会话时，你会获得一台恢复了上下文对话的全新虚拟机，因此对于重要的改动务必及时提交（Commit）。参见环境过期机制。

关于规格配置、权限模式（Permission modes）以及网络级别，请参阅云环境官方文档。

本地会话还是云端会话？

云端会话并不是为了取代本地会话，绝大多数开发者会混合使用两者。下表对比了两者的差异，后续段落将阐述它们各自的最佳适用场景。

对比项	本地会话	云端会话
运行环境	你的本地机器	每个任务独享全新虚拟机
电脑休眠或离线	会话中断停止	会话在云端持续运行
单仓库多任务处理	需要手动维护独立的工作树（Worktrees）、端口，避免冲突	每个任务独享一台虚拟机和一个分支
Agent 可触达资源	你本地用户账户具备的全部权限，包括 SSH 密钥、云服务 CLI 和 ~/.claude	代码仓库、设定的网络访问级别、启用的连接器以及会话级 GitHub 凭据
启动与跟进途径	当前机器，或通过远程控制由手机跟进	浏览器、手机、桌面端、终端、Slack、API 调用或定时任务
审批模式	支持所有模式，包括逐条命令审批	自动模式（Auto）、接受编辑模式（Accept edits）或规划模式（Plan）
交付成果	本地工作树中的文件修改	一个远程分支，可随时发起 Pull Request
算力消耗	本地机器硬件资源	无额外算力收费；直接计入套餐现有额度

当任务依赖只有你本地机器才具备的环境时，请继续留在本地。例如：包含真实本地数据的数据库、必须通过 VPN 访问的服务、本地 GPU、移动端模拟器或桌面连接的物理硬件设备。同样，如果你需要极其紧凑的视觉调试闭环（希望每次改动在数秒内立刻反映在本地浏览器中），或者你的企业启用了零数据保留（Zero Data Retention）（该模式会关闭云端会话功能），请使用本地模式。

有两项功能介于这两者之间：**远程控制（Remote control）**可以让会话保持在你的本地机器上运行，但允许你通过手机或浏览器进行引导交互；面向 Team 和 Enterprise 订阅公测的 自托管环境（Self-hosted environments） 则将云端会话运行在你企业自己的基础设施中，从而能够直接访问内部私有网络。

如果上述限制都不存在，那么该任务就是运行在云端的绝佳候选者。下一节将介绍最能发挥云端优势的工作流。

适合云端会话的七大工作流

这些工作流充分利用了上表中列出的特性差异：每个任务独立机器、离开电脑也能后台持续执行，以及最终交付供你审查的分支。

1. 并行清理任务积压（Backlog）

假设你有五个微小且互不相关的 Bug 需要修复。在本地模式下，你必须排队串行处理，或者手动拉出五个 worktree 并分别配置端口和依赖安装。而在云端，你可以同时启动五个会话，最后直接审查五个分支即可。

bash 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 远程仓库，因此请确保先推送本地 commit。在虚拟机启动期间，CLI 会展示实时的初始化进度清单，并为你排队缓冲在此期间输入的任何内容。

建议将每个任务写成一份自包含的工单（Ticket），说明问题所在、完成的验收标准，以及如何进行验证。前面的不稳定测试提示词就明确指定了验证方式：连续运行测试套件至少 30 次。最终会话执行了 40 次。

当任务属于某个更庞大的项目工程时，项目（Project）（目前面向 Pro 和 Max 用户公测）可以运行一个协调者会话（Coordinator conversation），为你自动启动和追踪各个云端会话。随后它会按状态对会话进行分组整理：处理中、等待你确认、以及已就绪待审查。

2. 让 Agent 自行验证修复成果

不稳定测试（Flaky test）是最需要反复验证的典型工作：你必须一遍又一遍地运行测试套件，绝不希望这种循环占用你正在工作的本地机器。在云端，Claude 自行对缓存代码打了补丁，并在单条命令中完整运行了整个测试套件 40 次。

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 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, the Claude mobile app, the Desktop app, your terminal, and 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 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.

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.

Play video

FIG A PauseThe 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:

CODEShellCopy

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 B The three sessions in the claude.ai/code interface, running locally and replaying their real transcripts. Setup steps are trimmed, paths show under /home/user, the bottom three sidebar titles are filler, and the mode chip shows the default.FIG C The Fix the flaky test sessionFIG D The Update the tidepool API docs session

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. The figure shows the parts. The four takeaways after it are the ones that change how you work.

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.
• 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.
• 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.
• 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.

For specs, permission modes, and network levels, see the cloud environments docs.

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, 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 , 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.

CODEShellCopy

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 (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.

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 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.

CODEShellCopy

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.

CODEShellCopy

claude --teleport            # pick a cloud session
claude --teleport <session-id>

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.

FIG H A question asked from a phone: claude.ai/code at phone width in a browser (not the native app), running locally and replaying the fourth session's real answerFIG I Claude checked each claim by running code against the sample data and changed no files

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.

CODEShellCopy

claude -p "The integration tier is green now; rebase on main and push" --cloud <session-id>

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, 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 walks through each step.

FIG J Step 1, sign in with GitHub. The claude.ai/code onboarding screens, running locally with sample data; the repository names in the illustrations and the Research preview chip are part of the product's own artwork.FIG K Step 2, install the Claude GitHub App

If GitHub doesn't send you back to claude.ai/code, the connect page at 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.

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 for the walkthrough. On Team and Enterprise plans, an owner has to turn on Quick setup 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.

If you run Team or Enterprise

An owner has a short checklist: turn on the GitHub connector at claude.ai/admin-settings/connectors, allow cloud sessions in the Claude Code admin settings, install the Claude GitHub App on the organization's repositories (or approve members' requests), and decide whether to turn on Quick setup. Organizations with IP allowlists or GitHub Enterprise Server have an extra step. See the docs on IP allowlists and 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 in the docs, including no repositories appearing after you connect 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.

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 beforeclaude --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 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.

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 and 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. See 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 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 is supported on Team and Enterprise. See the platform restrictions.

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 such as claude -p "rebase on main and fix any conflicts" --cloud <session-id>.

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 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.