What changes when Claude Code runs on its own machine, the workflows where that pays off, and how to connect GitHub on the first try.
You probably run Claude Code in a terminal on your own laptop. That session depends on the laptop in three ways:
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.
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:
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.
TtlCache.get. The cache stored a value only after the finished, so a second get for the same key during a load called the 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.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 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.
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.
CLAUDE.md, rules, skills, agents, and commands travel with the repo, and your ~/.claude stays on your laptop. See For specs, permission modes, and network levels, see the cloud environments docs.
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.
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.
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.
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.
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.
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.
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.
claude --permission-mode plan
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.
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.
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.
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.
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.
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.
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.
If your first cloud session goes wrong, GitHub is the most likely reason. Most problems come from cloud sessions needing two separate GitHub permissions.
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 (yourgh token) |
Yes | Yes | Whatever your token can reach | No, needs the App |
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.
Auto-fix, GitHub-triggered routines and projects also depend on the App, so install it even if you connect another way.
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.
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.
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.
| 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.
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.
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.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.service postgresql start, or do it in a SessionStart hook. claude --cloud. Claude-Session trailer that links back to the transcript.
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.
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.
/login in Claude Code with your claude.ai account.