Set up Claude Code cloud sessions

Before you start

You need four things. Check them now and the later steps won't stall.

• A Claude Pro, Max or Team plan, or an Enterprise premium or Chat + Claude Code seat. Organizations with Zero Data Retention can't use cloud sessions. The credit was offered to Pro and Max subscribers only.
• Claude Code signed in with your claude.ai account, not an API key. Run /status inside claude to see which one you're using. If it shows an API key, run /login.
• A GitHub account, with the code you want to work on in a GitHub repository. A folder that only exists on your disk can't be cloned into a cloud session.
• For the terminal route, the GitHub CLI (gh) installed and logged in. On a Mac that's brew install gh and then gh auth login. You can skip gh entirely and connect GitHub in the browser instead, as step 2 shows.

Update Claude Code first with claude update. The --cloud flag and /claim-credit are in 2.1.281, and older versions may not have them.

Step 1

Claim the credit

Open Claude Code and type /claim-credit. You can also open claude.ai/code, where a claim prompt appears on accounts that still have one. The deadline to claim is the end of 7 October 2026, US Pacific time.

If you've claimed it already, the command tells you so and links to your offer page. Here's the exact output from my account.

> /claim-credit
  ⎿  You've already claimed this offer. See the offer at https://claude.ai/code/claim-credit/6

The number at the end can differ from the public link, so open the one your own terminal prints. Your balance shows on claude.ai as a card titled Cloud session credits, which reads "Applies automatically to cloud sessions. After it's used or expires, your plan's regular usage applies." Mine said "$250 of $250 left" with an expiry of November 5 at 2:59 PM GMT+7. That's 11:59 PM Pacific on November 4, because US daylight saving time ends on November 1 and the Pacific offset becomes UTC−8.

The CLI's /usage screen doesn't show this credit. Its "Usage credits" line is paid extra usage, which is a separate setting.

Step 2

Connect GitHub

There are two ways in. Pick the terminal one if gh already works on your machine, since it takes ten seconds.

From the terminal with /web-setup

Start claude in any folder and run /web-setup. It reads the token that gh auth token prints and asks you to confirm. Then it sends the token to Anthropic, which stores it encrypted against your claude.ai account. Cloud sessions then use it to clone and push. You'll see this prompt.

Connect cloud sessions to GitHub?
Cloud sessions require connecting to your GitHub account to clone and push code on your behalf.
Your local credentials are used to authenticate with GitHub
❯ 1. Continue
  2. Cancel

Choose Continue. On my machine it printed one line and opened claude.ai/code in the browser.

⎿  Connected as theluckystrike. Opened https://claude.ai/code

Two details matter here. The command only works in an interactive session, so claude -p "/web-setup" fails with "/web-setup isn't available in this environment." And the cloud can reach exactly what your gh token can reach. If you plan to let Claude edit GitHub Actions files, add the workflow scope first with gh auth refresh -s workflow and then run /web-setup again. To remove the token later, disconnect GitHub at claude.ai/customize/connectors.

From the browser with the Claude GitHub App

Open claude.ai/code and follow the GitHub prompt. It asks you to authorize Claude on GitHub, then offers to install the Claude GitHub App. You can skip the install and add it later. Public repos work straight away. A private repo only shows up once the app is installed on that repo or on the organization that owns it.

Organization repos are where most people get stuck. Go to github.com/settings/applications, open the Claude entry, and click Grant next to the organization under Organization access. If the button says Request instead, an admin of that GitHub organization has to approve it. If the organization uses single sign-on, each member has to authorize the app for it separately. On Team and Enterprise plans, an Owner may also need to switch on the GitHub connector in the admin settings before anyone sees a sign-in button.

Step 3

Check the environment

Every cloud session runs inside an environment, which sets its network access, environment variables and optional setup script. Pro and Max accounts get one called Default during onboarding. It starts with no variables or script and uses Trusted network access. Trusted allows package registries and a list of approved domains, nothing else.

Trusted is fine for most JavaScript and Python work. Change it when an install fails with a 403, or when the task needs an API that isn't on the list. You edit environments in the claude.ai/code interface. The four levels are below.

Environment variables use .env format, one KEY=value per line. Anyone who can use the environment can read them, so keep real secrets out of there. On Pro and Max, add those as API credentials on the environment instead. A proxy attaches them to matching requests, and Claude never sees the key. A setup script is a bash script that runs before Claude Code starts. It gets about five minutes and must exit with code 0. Later sessions reuse the cached filesystem it leaves behind for around seven days. Put machine-level installs there. Project steps such as npm ci belong in a SessionStart hook in the repo, which runs at the start of every session, local or cloud.

// .claude/settings.json in your repo
{
  "hooks": {
    "SessionStart": [
      { "matcher": "startup|resume",
        "hooks": [ { "type": "command",
        "command": "if [ \"$CLAUDE_CODE_REMOTE\" = \"true\" ]; then npm ci; fi" } ] }
    ]
  }
}

CLAUDE_CODE_REMOTE is set to true inside cloud sessions, so the hook above installs dependencies in the cloud and leaves your laptop alone.

The machine itself has 4 vCPUs, 16 GB of RAM and 30 GB of disk. It comes with Python 3 (pip, uv, poetry, pytest, ruff), Node 20 to 22 (npm, pnpm, yarn, bun), Ruby, PHP 8.3, Java 21, Go, Rust, and C and C++. Docker, PostgreSQL 16 and Redis 7 are installed too, along with the usual command-line tools including git, gh, jq and ripgrep.

What carries over from your machine

Less than you'd expect. Your personal ~/.claude/settings.json, your user-level hooks and your user-scope MCP servers stay on your laptop. A cloud session reads the .claude/settings.json committed in the repo, plus any settings your organization manages on the server. Anything the session needs has to live in the repo or in the environment.

The CLI sends sessions to your default environment. Run /remote-env inside claude to pick a different one.

Step 4

Start your first session

From the terminal, cd into a local clone of a GitHub repo and pass the task to --cloud. What the session starts from depends on the Claude GitHub App. If the app is installed on the repo, the session clones the GitHub copy of your current branch, so push first. If it isn't, even after /web-setup, the CLI uploads your local repo as a bundle instead, uncommitted changes to tracked files included. Install the app on the repo if you want the GitHub route every time.

cd ~/code/your-repo
git push
claude --cloud "Read README.md and reply with its first heading. Do not change any files."

That's the smoke test I ran. The terminal came back with this.

Created cloud session: README smoke test
View: https://claude.ai/code/session_013RJsJUzfWs11NhuKnFaKr2?from=cli&m=0
Resume with: claude --teleport session_013RJsJUzfWs11NhuKnFaKr2

The session read the file on Anthropic's machine and answered "Codebase licensing checklist", which is the right heading. My local clone stayed untouched. A read-only task is the cheapest way to prove the whole chain works before you hand it something real.

You don't need a terminal at all. The same session starts from claude.ai/code in a browser, from the Code tab in the Claude app on iPhone or Android, or from the desktop app by picking Cloud instead of Local. You choose the repo and type the task.

Step 5

Follow and steer it

The View link is the main window onto a running session. It shows every tool call, and you can type follow-ups there, from any device. In the terminal you have two more options.

# send a follow-up message to a running session
claude -p "Also update the changelog." --cloud session_013RJsJUzfWs11NhuKnFaKr2

# pull the whole session down to your machine and keep working locally
claude --teleport session_013RJsJUzfWs11NhuKnFaKr2

What doesn't work, at least on my account, is attaching to a session interactively. claude --cloud session_... without -p returned "Error: Attaching to an existing cloud session is not enabled for your account." Use the web link or one of the two commands above.

Cloud sessions offer three permission modes, which are Auto, Accept edits and Plan. There's no manual approval mode and no bypass. In Accept edits, Claude pushes its branch without stopping to ask, so use Plan when you want to read the approach first.

Be careful with sharing. On Pro and Max, setting a session's visibility to Public lets any logged-in claude.ai user open it, and a session can contain private code and credentials.

Teleport has conditions of its own. It needs the same claude.ai account that started the session and a checkout of the same repo, not a fork. The session's branch must already be pushed, and if your working tree has changes it offers to stash them. After you teleport, new turns run locally in their own copy of the session. Treat them as local usage.

Step 6

Review and merge the work

A session started in the browser begins from the repo's default branch unless you name another one. From the CLI it begins from the branch you're on. Either way it commits to a branch prefixed claude/. The session page shows a counter such as +42 −18. Click it to open the diff and comment on individual lines. Your comments go back with your next message. When you're happy, click Create PR and choose a full PR, a draft, or GitHub's compose page with a generated title and description.

Commits made in a cloud session carry a Claude-Session: trailer with the session URL, and PR bodies include the link too. To leave it out, commit "attribution": {"sessionUrl": false} to the repo's .claude/settings.json. Your personal ~/.claude/settings.json doesn't reach the cloud.

Plan the credit so none of it expires

Whatever is left on November 4 is gone. The planner divides your remaining balance by the days left, so you can see what a day's worth of cloud work should cost. The first figures below assume 24 September. The page recomputes them from your own clock when it loads.

Anthropic's own clarification is that the credit is "an optional one-time credit that your cloud sessions spend first, before falling back onto your normal plan usage." Cloud sessions themselves don't cost extra. Anthropic's docs say they share your plan's rate limits and carry no separate charge for the virtual machine.

What the credit is good for

Long jobs that shouldn't depend on your laptop staying awake are the obvious fit. A dependency upgrade across a repo qualifies, and so does a migration or a loop of running the tests, fixing and running them again. Parallel work fits too. Each session is its own VM with its own copy of the repo, so five sessions on five repos don't fight over one working tree. And you can start or check a session from your phone.

Some things don't move to the cloud. A session can't see files that exist only on your disk or drive a browser that's logged in on your machine. Interactive logins such as AWS SSO won't finish either. If a job depends on any of those, keep it local.

What's official and what's only reported

When something goes wrong

The errors below come up most often. I collected them from my own run, the official docs and open issues on the Claude Code GitHub repo.

Sources

• Use Claude Code in the cloud, Anthropic docs
• Get started with Claude Code in the cloud, Anthropic docs
• Configure cloud environments, Anthropic docs
• Use the GitHub integration, Claude help center
• anthropics/claude-code issues, for the 403 and setup-script reports