What Claude Code cloud sessions actually change about how you work — stated as decision rules you can apply on Monday, with the places the source is a toy demo, self-reported or quietly generous to the product called out.
Spine text (claude.dev Playbooks, Addy Osmani, 6 Oct 2026): Claude Code in the cloud: a field guide to cloud sessions · checked against Use Claude Code in the cloud and Configure cloud environments
The field guide is a Playbooks post by Anthropic about Anthropic’s own product, and its evidence is three runs on a fictional repo called Tidepool plus one phone question. That is a good illustration and a poor measurement: no success rates, no failure counts, no cost per task. So each module separates what the source says, where it is thin or self-serving, and arithmetic or doc facts I checked against the official cloud-session docs.
Modules 2, 3, 4 and 7 make you commit to an answer before the reveal. Do them before reading the explanation.
A cloud session is Claude Code running on an Anthropic-managed VM instead of your laptop. Each task gets its own machine (Ubuntu 24.04, x86_64, 4 vCPUs, 16 GB RAM, 30 GB disk per the environments doc), the repo is cloned onto a fresh claude/ branch, and the session ends in a branch and a pull request rather than edits in your working tree. You can start one from the browser, the phone’s Code tab, the Desktop app, a terminal (claude --cloud), a schedule, or an API call, and it keeps running with your laptop closed.
| Fact | What it buys you | What it costs you |
|---|---|---|
| Every task gets its own machine | No port, file or install collisions between parallel tasks | Sessions cannot see each other; conflicts are deferred to merge time |
| The GitHub token never enters the VM | A compromised session cannot walk off with your credential; push is scoped to its branch | You depend on the proxy and on correct App/branch scoping |
Repo Claude config travels; ~/.claude does not | Team rules in CLAUDE.md, .claude/ skills, .mcp.json work for everyone | Your personal skills, memory and shortcuts silently vanish |
| Idle VMs are reclaimed | No resource leak on your side | Uncommitted work and background processes are lost; only the conversation is restored |
Foreground commands wait 2 minutes by default (10 maximum), then move to the background for up to 30 more minutes; BASH_DEFAULT_TIMEOUT_MS and BASH_MAX_TIMEOUT_MS raise them. SessionStart hooks are cancelled after 600 seconds. A setup script is snapshot-cached only if it finishes in about five minutes. There is no separate compute charge — but cloud sessions share rate limits with all your other Claude use.
The demo is three tasks on a toy Node repo with a deliberately planted flaky test, outdated docs and a string-concatenating logger. All three finished in about a minute. That tells you the plumbing works, not how often a cloud session succeeds on your 400-file monorepo with a 20-minute integration tier. The post publishes zero success rates, zero retry counts and no cost per task. “Setup was a third to a half of each run” is a statement about a tiny repo with a cached environment, not a latency budget.
~/.claude) for isolation and endurance.CLAUDE.md, hooks in .claude/settings.json, services started per session.Go cloud when tasks are independent, the proof is long-running, you will not keep a laptop awake, or you need many branches of one repo. Stay local when the task needs local data, a VPN-only service, a GPU, a simulator or desk hardware, a tight visual loop measured in seconds, or when your organization runs Zero Data Retention (which disables cloud sessions entirely). Between the two sit Remote Control (laptop session, phone steering) and self-hosted environments (beta, Team/Enterprise: cloud sessions on your own infrastructure, reaching private networks).
The post frames cost as “no separate compute charge.” True, but the real currency is your plan limits, which parallel sessions drain in parallel: five sessions is roughly five times the draw for roughly five times the throughput. Cloud does not make work cheaper; it makes your attention and wall-clock cheaper. Decide on which of those you are short of.
The field guide’s strongest claim is not parallelism; it is that a VM you are not paying CPU for can go prove the fix: run the suite 40 times, start the server and curl every documented endpoint, run the tide calculation at the window edge. “Most demo value came from running.” I agree, and would go further: the prompt should name the proof command and the pass criterion, because an agent that decides its own bar will pick a cheap one.
Forty passes sounds decisive. It rules out the original flake decisively (a 25% failure rate passes 40 times in a row with probability 0.7540, about 0.001%). It rules out far less about a partial fix. Two numbers to commit to before you read on.
The agent’s change was incomplete: the flake is reduced from 25% to a residual 5% failure rate per run, but the agent does not know that. It runs the suite 40 times in a row. What is the probability (in percent) that all 40 runs pass — so the agent reports success on a still-broken test?
You want to be 95% confident that the remaining flake rate is below 1%, assuming every run passes. Roughly how many consecutive clean runs do you need?
In session 3 the logger agent reran the cache test 8 times and saw it fail 5 times. If the true failure rate were the stated “about 1 in 4,” five or more failures in eight runs has probability about 2.7%. Either the flake is much more likely under that session’s changed code and load, or “1 in 4” was a loose description. Both readings carry the same lesson: a flake rate is a property of the environment, not the test. A fix proven on one VM under one load has been proven there.
“Read Claude’s summary before the diff” is a habit the post recommends. The summary is the agent’s self-report. Session 3 shows an honest one (it said the suite was not clean), but nothing guarantees that. Prefer: read the command and its raw output in the transcript, check the pass criterion is the one you named, then read the diff. Also note the guide never says the fix in session 1 was reviewed for correctness by anyone other than the agent that wrote it.
Cheap risk: run once, show output. Flaky or concurrency bug: at least 300 runs, report the fail count, vary load (parallel jobs). Behavioural change: a test that fails before the change and passes after. Docs: execute every example. Regression hunt: bisect with a scripted pass/fail command. Raise BASH_DEFAULT_TIMEOUT_MS so long loops are not shunted to the background mid-run.
Three sessions started within 16 seconds and all finished in 87 seconds because the tasks touched different files: cache, docs/API.md, logger. The most instructive moment is the one the post mentions almost in passing: the logger session ran into the very race condition the first session was fixing, proposed the same fix, declined to apply it as out of scope, and reported an unclean suite. That is the correct behaviour and also the cost model of parallelism: every session is a branch that cannot see the others’ fixes. You pay the integration cost at the end, and sometimes you pay it as a red CI run on a branch that is “done.”
| Do | Avoid |
|---|---|
| Split along file or module boundaries | Two sessions on the same file or the same shared fixture |
Push local commits before claude --cloud; the VM clones from GitHub, not your disk | Assuming unpushed work is visible to the session |
| Ticket = what is wrong, what done looks like, how to prove it | “Fix the flaky test” |
Merge one branch, then claude -p "rebase on main and fix conflicts" --cloud <session-id> | Letting five branches rot until merge day |
“5 sessions ≈ 5× speed” ignores the human cost: five diffs to review. For most teams the bottleneck is review attention, not agent throughput, and the post offers Projects (a coordinator that groups sessions by working / waiting / ready for review) without any data on whether review quality holds up. Start with two or three sessions and measure how many of the PRs you merge without edits before widening.
The post presents seven workflows as peers. They are not. They differ sharply in how much autonomy you hand over and how reversible the result is.
| Workflow | Value | Risk | My position |
|---|---|---|---|
| 1. Clear a backlog in parallel | High | Low | The default use. Self-contained tickets, file-disjoint, push first. |
| 2. Let it prove the fix | Highest | Low | The real differentiator (module 3). Name the proof command. |
| 3. Plan at desk, build in cloud, finish in terminal | High | Low | Sound. Commit and push the plan; --teleport needs a clean tree and a pushed branch, and the local copy then diverges from the cloud session. |
| 4. Check in from your phone | Medium | Low | Best for read-only questions. The post’s example (found a real edge bug by running code, changed no files) is one anecdote, not a rate. |
| 5. Hand CI failures and review comments to Claude (auto-fix) | Medium | High | It replies on review threads under your username (labelled Claude Code) and can trigger comment-driven automation. Do not enable it on repos where a PR comment can deploy infrastructure. |
| 6. Routines (schedule, HTTP, GitHub event) | High | High | Research preview; runs without approval prompts and pushes to claude/ branches by default. Scope the environment narrowly and keep the prompt idempotent. |
| 7. Run code you do not fully trust | Situational | Misunderstood | Oversold. See module 6. |
Auto-fix and green CI. An agent rewarded for turning a red check green has an incentive to loosen the test. The docs say it pushes “clear fixes” and asks about ambiguous or architectural ones; “clear” is the agent’s judgement. Pair it with branch protection that requires human review and a CLAUDE.md rule that tests may not be weakened to pass. GitHub emits no webhook when the base branch advances into a conflict, so auto-fix will not notice; ask for a rebase.
Routines and quiet failure. A routine fires with nobody watching. The post gives the hourly minimum cadence and the branch prefix but no failure-notification story; assume a routine that errors does so silently unless you build the alert (a failing exit that opens an issue, or a notification step) into the prompt.
Workflows 1–4 are framed as natural fits; 5–7 as extensions. Its habit list — one task per session, ask for evidence, push before --cloud, commit as you go, steer while it works, share the session — is accurate and worth adopting wholesale. Cloud commits carry a Claude-Session trailer linking to the transcript, which is genuinely useful provenance for reviewers.
A cloud VM has no access to your SSH keys, your cloud CLI sessions or your browser profile, and it never holds your GitHub token: a proxy attaches the credential server-side and the session gets scoped access to its own branch. Running a stranger’s PR or an untrusted dependency install there rather than on your laptop is a real improvement. The post is right about this.
| Channel | Why it stays open |
|---|---|
| Anthropic API | Even with network access disabled, Claude Code still talks to the API, so data can leave that way (the docs say so explicitly). |
| Branch push | The session can push to its own branch; anything it can read in the repo can be written to a branch you may not inspect immediately. |
| Allowlisted hosts | My inference: the Trusted level includes package registries, GitHub and cloud SDK hosts. Any host the code can write to is a potential exfiltration path, and an untrusted install script needs a registry to run at all. |
| Environment variables | Visible to anyone who can use the environment. Never put secrets there. |
| Prompt injection | The agent reads PR bodies, issues and files, and acts on them. Isolation limits the damage; it does not stop the agent being talked into something within its permissions. |
Network levels: None (installs fail), Trusted (default; registries, GitHub, cloud SDKs, Docker Hub), Custom (your domain list, optionally plus defaults), Full. Pro and Max can attach API credentials that stay outside the sandbox and are added to matching requests after they leave the VM; Team and Enterprise do not have this yet, so on those plans a secret is either absent or in a shared variable. Cloud sessions are unavailable under Zero Data Retention or the HIPAA configuration.
“Run untrusted code in the cloud” should read: protects your laptop, not your repo or your data in the repo. If the repo itself holds sensitive code or customer data, the VM is where that data now lives, under a plan whose retention and training policy you should read (Team, Enterprise and API: not trained on unless the organization opts in; Free, Pro and Max: depends on the model-improvement setting). Use the narrowest network level the task allows, put nothing sensitive in shared variables, and require review before anything an agent pushed reaches main.
/web-setup| Layer | Use for | Rules |
|---|---|---|
| Setup script (environment) | System packages (apt install), heavy toolchains | Runs as root before Claude starts; must exit 0 or the session fails; finish in about five minutes so the filesystem snapshot is cached; cache rebuilds when script or allowed hosts change |
SessionStart hook (.claude/settings.json) | Project-level installs such as npm install | Runs the same locally and in the cloud; gate with CLAUDE_CODE_REMOTE; cancelled at 600 seconds unless you set a timeout |
| Per-session services | Databases, docker compose stacks | The cache stores files, not processes; start them in a hook or ask Claude |
| CLAUDE.md | Test commands, conventions, how to prove a change | Your personal ~/.claude does not reach the VM |
/web-setup?Sign-in tells Claude who you are; the Claude GitHub App decides which private repos it can reach. /web-setup instead sends your local gh token to your account, so sessions reach whatever that token can, with or without the App — but Auto-fix, Projects and triggers still need the App. Position: for individuals who already live in gh, /web-setup is fastest; for anything team-owned, prefer the App with explicitly selected repositories, because a gh token is usually broader than the repos you intend to delegate.
The troubleshooting tables are accurate and useful, but the post is silent on the tradeoffs a security reviewer will raise first: what a stolen claude.ai session could start in your repos, whether the session-scoped credential can be limited to read-only, and how to audit what a routine did. Ask those questions of your own org before turning on Routines or Quick setup.
/web-setup is token-scoped and does not.claude --cloud on it. Read the proof command’s raw output before the summary and the diff.CLAUDE.md; install dependencies in a SessionStart hook gated on CLAUDE_CODE_REMOTE; keep heavy installs in the setup script under five minutes.