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

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. FIG AThe 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: CODEShellclaude --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 EA 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 FAnatomy 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 sessionCloud sessionRuns onYour machineA fresh VM for each taskLaptop asleep or offlineThe session stopsThe session keeps goingSeveral tasks on one repoSeparate worktrees, ports and careOne VM and one branch per taskWhat the agent can reachAnything your user account can, including SSH keys, cloud CLIs and ~/.claudeThe repository, the network level you set, the connectors you enable, and a session-scoped GitHub credentialStart or follow fromThat machine, or your phone through remote controlBrowser, phone, Desktop, terminal, Slack, an API call or a scheduleApprovalsAny mode, including per-commandAuto, Accept edits or PlanEnds withChanges in your working treeA branch, and a pull request when you want oneComputeYour machineNo 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. CODEShellclaude --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 GForty 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. CODEShellclaude --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. CODEShellclaude --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.

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. CODEShellclaude -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 connectedPublic reposYour private reposAn org's private reposAuto-fix, GitHub triggers, projectsSigned in with GitHub onlyYesNoNoNo+ App on your personal accountYesYesNoYour repos+ App on the organization (owner approves)YesOnly if also on your accountYesOrg repos/web-setup (your gh token)YesYesWhatever your token can reachNo, 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.

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 LIf 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 seeWhyFixA private repository is missing from the pickerThe App isn't installed on the account or organization that owns it, or its repository access excludes itInstall the App there, or add the repository to the App's Repository access in your GitHub settingsAn error saying you must be an owner of the organization to link itThe organization blocked a membership check, usually because of a pending App permission request, an IP allow list, or SAML single sign-onAn 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 organizationAn organization's repositories are missing right after you connectThe organization uses SAML single sign-on, and its authorization step was skippedOn 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 reconnectEvery cloud session fails with an authentication errorYour Claude organization uses IP allowlistingAsk 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 MAdding 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 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.

Open claude.ai/code, or run /login in Claude Code with your claude.ai account. Connect GitHub and install the Claude GitHub App where your repository lives. Pick the repository and the Default environment. Give Claude one task from your backlog, with a command that proves it's done. Close the tab. Check in from your phone later, then review the diff and create the pull request at claude.ai/code.