How to use Claude Code cloud sessions: setup, environments, and credits
Published October 7, 2026
Summary
A Claude Code cloud session runs Claude Code in a VM that Anthropic manages, so the task keeps going after you close your laptop. This guide shows how to start one from the browser, your phone, the desktop app, or the terminal, set up its cloud environment, use the cloud session credit, and pull the work back into your terminal with teleport.
Basics
What is a Claude Code cloud session?
A cloud session is a Claude Code session that runs on cloud infrastructure instead of your machine. By default that is an isolated VM Anthropic manages. It clones your GitHub repository, works on its own branch, and keeps running after you close the tab or your laptop, and you can check on it or steer it from claude.ai, the Claude mobile app, or the desktop app.
Anthropic launched the feature as Claude Code on the web and made it generally available as cloud sessions on September 23, 2026. Checked October 7, 2026 against Anthropic's documentation. Replicas publishes this guide and is another way to run Claude Code in the cloud, covered at the end.
| Requirement | Details |
|---|---|
| Plan | Pro, Max, or Team, or Enterprise with premium or Chat + Claude Code seats |
| Sign-in | A claude.ai account. Not available with an API key, Amazon Bedrock, Google Cloud's Agent Platform, or another third-party provider |
| Code host | GitHub, through the Claude GitHub App or /web-setup. Other hosts only as an uploaded bundle that cannot push back |
| Organization | Owners can turn cloud sessions off; organizations with Zero Data Retention or the HIPAA configuration cannot use them |
| Cost | No separate compute charge; usage counts toward your plan's limits |
Setup
How to start a Claude Code cloud session
The first session takes three steps in the browser: connect GitHub, accept the Default environment, and submit a task. After that, you can start sessions from any surface and they all show up in the same list.
Your first session at claude.ai/code
Go to claude.ai/code, sign in, and follow the prompt to connect GitHub. That lets sessions clone any public repository. For private repositories, install the Claude GitHub App on the account or organization that owns them; an organization owner may need to approve it.
On Pro and Max, onboarding then creates an environment called Default. On Team and Enterprise, keep the defaults on the Create your first cloud environment form and click Create & finish. Default uses Trusted network access and has no environment variables or setup script.
Pick the repository and branch below the message box, choose a permission mode (Auto, Accept edits, or Plan; Manual and Bypass are not offered), describe the task, and press Enter. Name files and paste error output: "Fix the failing auth test in tests/test_auth.py" works better than "fix tests".
From the terminal with claude --cloud
Sign in to the Claude Code CLI with your claude.ai account (run /status to check the login method), then run claude --cloud "Fix the authentication bug in src/auth/login.ts" from your repository. The VM clones your GitHub remote at the current branch, not your local checkout, so push local commits first.
If you already use the GitHub CLI, run /web-setup inside Claude Code to connect GitHub with your gh token instead of the browser flow. It also creates the Default environment if you have none. On Team and Enterprise, /web-setup appears only after an owner turns on Quick setup. Each --cloud command starts its own session, so you can run several tasks in parallel.
- claude --cloud is not claude --remote-control. --cloud runs the work on a cloud VM; Remote Control keeps it on your computer and lets your phone or browser steer it.
- From a repository with no GitHub remote, or one the Claude GitHub App is not installed on, claude --cloud uploads a bundle of your local repository instead. It must be under 100 MB and only includes tracked files. On macOS, Linux, and WSL, uncommitted changes to files like .env and *.pem stay on your machine.
From your phone or the desktop app
Open the Code tab in the Claude mobile app, or select Cloud instead of Local when you start a session in the desktop app. Sessions started anywhere show up everywhere, so you can start a task on your laptop and review it from your phone.
Configuration
Set up the cloud environment: setup script, variables, and network access
Every cloud session runs in a cloud environment, the saved configuration for network access, environment variables, and a setup script. Edit Default or add another from the cloud icon above the message box at claude.ai/code. Run /remote-env in Claude Code to choose which environment claude --cloud uses.
| Setting | What to know |
|---|---|
| Setup script | Bash that runs as root on Ubuntu 24.04 before Claude Code starts. It must exit zero. If it finishes in about five minutes, Anthropic caches the filesystem and later sessions skip it; the cache rebuilds when you change the script or allowed hosts, and about every seven days. |
| Environment variables | .env format, one KEY=value per line. Anyone who uses the environment can read them, and a running session picks up edits only once its VM is restored or rebuilt. |
| API credentials | Pro and Max only. A proxy adds the key to requests for the hosts you list, so Claude and its commands never see it. |
| Network access | None, Trusted (the default: package registries, GitHub, cloud SDKs), Full, or Custom with your own domain list. GitHub, MCP connectors, and the Anthropic API stay reachable at every level. |
Write a setup script that caches
Use the setup script for what is not in the image, for example apt update && apt install -y shellcheck, and for slow container pulls such as docker compose pull. Packages, files, and pulled images carry over in the cache; running processes do not, so ask Claude to start PostgreSQL, Redis, or your compose stack in each session.
For project setup that should also run locally, such as npm install, use a SessionStart hook in the repository's .claude/settings.json and exit early unless CLAUDE_CODE_REMOTE is true. Hooks in your user-level ~/.claude/settings.json do not reach cloud sessions.
- Preinstalled: Python 3 with pip, uv, and poetry; Node 20, 21, and 22; Ruby; PHP 8.3; Java 21; Go; Rust; C and C++ toolchains; Docker; PostgreSQL 16 and Redis 7 (not started by default); git, gh, jq, and ripgrep.
- Each VM has roughly 4 vCPUs, 16 GB of RAM, and 30 GB of disk. Foreground commands wait 2 minutes by default; set BASH_DEFAULT_TIMEOUT_MS in the environment variables for long builds.
- Bun is installed but has known problems fetching packages through the session's security proxy.
Cost
How cloud session usage and the cloud session credit work
Cloud sessions share rate limits with the rest of your Claude and Claude Code usage, and there is no separate charge for the VM. Several sessions running in parallel use your limits proportionately faster.
At general availability, Anthropic offered existing individual Pro and Max subscribers a one-time cloud session credit: $100 on Pro and $250 on Max. The subscription had to be active on September 23, 2026 at 2:00 PM PDT, and the credit had to be claimed by October 7 at 11:59 PM PT from the banner in the desktop app or IDE, or with /claim-credit in Claude Code.
- What the credit pays for
- Cloud sessions only. Projects, routines, Remote Control, chat, and local Claude Code usage are not covered.
- Order of use
- While credit remains, cloud session usage is paid from it and does not count toward your plan's limits. Once it runs out, sessions count toward your plan again.
- Expiry
- Unused credit expires on November 4, 2026 at 11:59 PM PT. Team and Enterprise plans, free trials, and accounts with a past-due payment were not eligible.
Cloud to terminal
Move a cloud session to your terminal with teleport
Run claude --teleport in a checkout of the same repository to pick a session, or claude --teleport SESSION_ID to open one directly. Inside Claude Code, /teleport (or /tp) opens the same picker, and in /tasks you can press t. Teleport checks out the session's branch and loads the full conversation.
From the CLI, handoff only goes one way: you cannot push an existing terminal session to the cloud, so start a new one with claude --cloud. The desktop app can send a local session to the cloud from its Open in menu. After you teleport, new work stays local; run /remote-control in that session to keep steering it from your phone.
To steer a cloud session without opening it, run claude -p "also update the changelog" --cloud SESSION_ID. The message is queued and the command exits.
| Teleport requirement | If it fails |
|---|---|
| No uncommitted changes | Teleport offers to stash them |
| Same repository, not a fork | Run it from a checkout of the session's repository |
| Session branch pushed to the remote | Teleport fetches it without prompting, so load SSH keys into ssh-agent first |
| Same claude.ai account | Run /login; API key sign-in is not enough |
Results
Review the diff, open a pull request, and turn on auto-fix
When Claude reaches a stopping point, it pushes its branch. Select the lines-changed indicator, such as +42 -18, to open the diff, comment on specific lines (comments go out with your next message), and choose Create PR for a full or draft pull request. The session stays open after the PR, so you can paste CI output or review comments back in.
With the Claude GitHub App installed, turn on Auto-fix from the CI status bar, or run /autofix-pr on the branch in your terminal. Claude then responds to failed checks and review comments, pushing clear fixes and asking about ambiguous ones. It cannot react to merge conflicts, and its replies post under your GitHub username, so review comment-triggered automation such as deploy bots before enabling it.
Common problems
When a cloud session will not start or stops
Most failures come from GitHub access, the setup script, or signing in with something other than a claude.ai account.
- No private repositories appear
- Install the Claude GitHub App on the account or organization that owns the repository, or connect with /web-setup so sessions use your gh token.
- Setup hangs or times out
- The setup script is probably over the roughly five-minute cache budget. Run installs in parallel, remove retry sleeps, and move the largest downloads into a background SessionStart hook.
- Setup script failed
- The script exited non-zero. Add set -x to find the failing command, append || true to non-critical steps, and check that the network level allows the registry.
- Unable to get organization UUID
- claude --cloud and claude --teleport need a claude.ai sign-in. Run /login instead of using an API key; Bedrock and other third-party provider setups cannot use cloud sessions.
- Environment expired
- Idle sessions pause and their VM is eventually reclaimed. Reopen the session at claude.ai/code for a fresh VM with your conversation; commands and subagents that were still running are not restored.
Team workflow
When a team outgrows Anthropic cloud sessions
Cloud sessions are a good default for one developer with a Claude plan and code on GitHub. Replicas runs the same Claude Code CLI in a VM per task for teams that need what cloud sessions do not cover: GitLab repositories, Anthropic API keys, Bedrock, or Foundry, tasks started from Slack, Linear, or GitHub, a desktop the agent can drive, and Codex or OpenCode in the same environment.
Compare both, along with Remote Control, a VPS, and GitHub Actions, in the Claude Code in the cloud guide before choosing.
FAQ