Source: ai-research/claude-dev-blog-claude-code-in-the-cloud-2026-10-28.md · Added 2026-10-30: raw/Coding_on_the_go_with_Claude_Code.md (official Claude YouTube video, see § The official phone walkthrough)

Author: Addy Osmani (Anthropic) · URL: https://claude.dev/blog/claude-code-in-the-cloud/ · Published: October 6, 2026

Anthropic’s practical guide to cloud sessions: Claude Code running on a fresh VM per task, with your repository cloned onto its own branch. Osmani ran four real sessions against a small sample repository and reports the timings and results. The guide covers when to use the cloud instead of your laptop, seven workflows that suit it, how to connect GitHub without getting stuck, and how to set up an environment so Claude can check its own work.


What a cloud session is

  • One VM per task, with your repo cloned onto a new branch and your environment’s setup already done. Sessions can’t touch each other’s files or ports.
  • Start from claude.ai/code, the mobile app, the Desktop app, the terminal (claude --cloud "<task>"), Slack, an API call or a schedule. Follow from browser, phone or Desktop.
  • Your GitHub token never enters the VM. A proxy holds it; the session gets a short-lived credential that can push only to its own branch.
  • Repo config travels, personal config doesn’t. CLAUDE.md, rules, skills, agents and commands come with the repo; ~/.claude stays on your laptop.
  • Idle VMs are reclaimed. Reopening gives a fresh VM with the conversation restored, so commit as you go.
  • Cost: included in Pro, Max, Team and Enterprise with no separate compute charge; sessions draw on the same usage limits as the rest of Claude Code. An org owner may need to turn them on.
  • VM size: about 4 vCPUs, 16 GB RAM, 30 GB disk.

The test run

Three sessions started within 16 seconds of each other on a sample Node API (“tidepool”), all done 87 seconds after the first started:

  • Flaky test: found a race in a cache’s get, cached the in-flight promise, then ran the suite 40 times with 0 failures.
  • Docs: started the server, curled every endpoint, and found five ways the API doc was wrong.
  • Logger: wrote a JSON logger with five tests, hit the same flaky test, traced it to the race the first session was fixing, left it alone as out of scope, and said the suite wasn’t clean.

The lesson Osmani draws: isolation means sessions don’t see each other’s fixes. Split parallel tasks along file boundaries, merge branches in a sensible order, and expect one session to report a problem another is already fixing.

Local or cloud?

LocalCloud
Laptop asleep or offlineSession stopsKeeps going
Several tasks on one repoSeparate worktrees, ports, careOne VM and branch per task
Agent can reachAnything your account can (SSH keys, cloud CLIs, ~/.claude)The repo, the network level you set, enabled connectors, a session-scoped GitHub credential
ApprovalsAny mode, including per-commandAuto, Accept edits or Plan
Ends withChanges in your working treeA branch, and a PR when you want one

Stay local for local databases with real data, VPN-only services, GPUs, phone simulators, hardware, tight visual loops, or orgs on Zero Data Retention (which turns cloud sessions off). In between: Remote Control keeps the session on your machine but steerable from your phone; self-hosted environments (beta, Team and Enterprise) run cloud sessions on your own infrastructure.

Seven workflows

  1. Clear a backlog in parallel. One claude --cloud per fix. Push first: it clones your GitHub remote at your current branch. Write each task as a ticket that says what’s wrong, what done looks like, and how to prove it. For one larger effort, a redesigned project (public beta, Pro and Max) runs a coordinator that starts and tracks the sessions.
  2. Let it prove the fix. The VM’s CPU isn’t yours, so ask for heavy proof: run the suite 200 times, bisect 50 commits, run the slow integration tier. Foreground commands time out after 2 minutes by default (10 max), then keep running in the background for up to 30 more; raise with BASH_DEFAULT_TIMEOUT_MS and BASH_MAX_TIMEOUT_MS.
  3. Plan locally, build in the cloud, finish in your terminal. claude --permission-mode plan, commit and push the plan, claude --cloud "Execute the plan in docs/migration-plan.md", then claude --teleport (or /teleport, /tp) to pull the branch and conversation back. Teleport needs a clean working tree and a pushed branch.
  4. Check in from your phone. Start, steer, answer questions, or tell Claude to watch a PR from the Code tab in the Claude app.
  5. Hand CI failures and review comments to Claude. With the Claude GitHub App installed, turn on Auto-fix in the session’s CI bar, or run /autofix-pr. Claude pushes clear fixes and asks about anything ambiguous. It is not told about merge conflicts, so ask it to rebase.
  6. Start work without starting it. Routines (research preview) run a cloud session from a schedule (hourly at most), an HTTP call, or a GitHub event. Queue a follow-up into a running session from anywhere, including CI: claude -p "rebase on main and push" --cloud <session-id>. A prefilled URL such as claude.ai/code?prompt=...&repositories=org/repo bookmarks a session start.
  7. Run code you don’t fully trust (a contributor’s PR, a new dependency) in a disposable VM away from your keys. Network None is strictest; even then Claude Code still talks to the Anthropic API and can push to its own branch.

Connecting GitHub

Cloud sessions need two separate GitHub permissions: signing in with GitHub (who you are) and installing the Claude GitHub App (which private repos Claude can see). Public repos work with sign-in alone.

ConnectedYour private reposAn org’s private reposAuto-fix, GitHub triggers, projects
Sign-in onlyNoNoNo
+ App on your accountYesNoYour repos
+ App on the org (owner approves)Only if also on your accountYesOrg repos
/web-setup (your gh token)YesWhatever the token reachesNo, needs the App
  • Path A (recommended): claude.ai/connect-github, then install the App where the repo lives.
  • Path B: /web-setup sends your gh token to your Claude account (Team and Enterprise owners must enable Quick setup first).
  • Path C: claude --cloud in a repo without a GitHub remote uploads a bundle instead; it can push back only if your GitHub connection has access. GitLab and Bitbucket work this way but can’t receive pushes.
  • Common failures: a missing private repo means the App isn’t installed on the owning account or org; missing org repos right after connecting usually means the SAML single-sign-on Authorize step was skipped; every session failing with an auth error usually means org IP allowlisting (ask support to exempt Anthropic-hosted services).

Give sessions a way to check their work

  • Start with the Default environment (Trusted network, no variables, no setup script); enough for most JavaScript, Python, Go and Rust repos.
  • Setup script for the machine: runs as root before Claude Code, must exit 0, should finish in about five minutes so the environment gets cached. The cache rebuilds when the script or allowed hosts change, and about every seven days.
  • SessionStart hook for the project (npm install and similar) in .claude/settings.json, so it runs the same locally and in the cloud. Check CLAUDE_CODE_REMOTE for cloud-only steps.
  • Start services per session: the cache keeps files, not running processes.
  • Narrowest network level that works: Trusted covers common registries; Custom adds a private registry; Full only when needed.
  • Keep secrets out of shared variables; on Pro and Max, an environment’s API credentials attach keys outside the VM for named hosts.
  • Put test commands in CLAUDE.md, since ~/.claude doesn’t reach the VM.

Habits

  • One task per session; ask for evidence and read the summary before the diff.
  • Push before claude --cloud; commit as you go on long tasks.
  • Parallel sessions use plan limits in parallel: five sessions burn them about five times as fast. Routines have hourly caps; projects can start up to 200 threads a day.
  • On Team and Enterprise, set session visibility to Team for reviewers. Cloud commits carry a Claude-Session trailer linking to the transcript.

The official phone walkthrough (Anthropic video, 2026-10)

Creator: official Claude YouTube channel (@claude), Coding on the go with Claude Code · URL: https://www.youtube.com/watch?v=-OH1y7CjIew · auto-caption transcript fetched 2026-10-30, about 715 words. It agrees with the guide above on every overlapping point (fresh clone per session, own branch, same plan limits with no VM charge, the two GitHub steps, personal settings, skills and plugins not travelling, self-hosting on Team and Enterprise). What it adds is the click path:

  1. Connect GitHub, then install the Claude GitHub App and pick its repos. “A private repo only shows up after the app can see it.”
  2. Start from the desktop app: select Cloud instead of Local, then choose the repo, the environment and the branch to start from. The demo task: a newsletter form on a marketing site accepts an invalid email and the request fails on the server.
  3. Close the laptop. On the phone, open the Claude app → Code tab. Start a new task or continue the one from the laptop; answer Claude’s question or steer it somewhere else.
  4. Review on the phone. Comments you leave on the diff go back to Claude with your next message. Tap Create PR to open the pull request on GitHub, then have Claude watch the PR and respond to failing checks and review comments.
  5. Or finish in the terminal with claude --teleport, which brings the cloud session onto your computer.
  • Custom environments let you set network access, add environment variables and write a setup script, on top of the default image with common runtimes, build tools and databases.
  • When to use it, per the video: tasks that outlast your time at the laptop (a large refactor, a migration), work started before leaving for the day and reviewed in the morning, ideas that come to you away from the computer, and several tasks at once without managing worktrees.
  • Cloud session vs Remote Control: a cloud session doesn’t need your computer on; Remote Control connects the Claude app to a session running on your own computer.

Key Takeaways

  • A cloud session is a disposable VM per task with your repo on its own branch; your GitHub token and personal config stay out of it.
  • Use it for parallel backlog work, long proof runs, overnight or phone-started tasks, CI auto-fix, and untrusted code; stay local for anything that needs your machine’s data, network or hardware.
  • Most first-run failures are GitHub permissions: sign-in and the GitHub App are separate, and private repos need the App on the owning account or org.
  • Ten minutes of environment setup (setup script, SessionStart hook, test commands in CLAUDE.md) is what lets Claude verify its own work.

Try It

  • Pick three small, unrelated fixes and start one claude --cloud per fix, each prompt naming the command that proves it’s done.
  • Move your test and lint commands into the repo’s CLAUDE.md and a SessionStart hook, then check a cloud session can run them.
  • If an org repo is missing from the picker, check the GitHub App install and the SAML Authorize step before anything else.