Claude Code in the cloud: a field guide to cloud sessions

來源原標題

Claude Code in the cloud: a field guide to cloud sessions

機構

Anthropic

原始標籤

Best practices

原始連結

https://claude.dev/blog/claude-code-in-the-cloud/

摘要原文

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 Pause 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: CODE Shell Copy 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 session FIG 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 ~/.