aq.dev / guides / claude-code-cloud-sessions-explained

Claude Cloud Sessions: What They Are and How to Use Them

A Claude cloud session is a Claude Code conversation and execution environment that runs on cloud infrastructure instead of your computer. It usually clones a GitHub repository into a fresh environment, works on a branch, and keeps running after your laptop closes. You can monitor and steer it from the web, mobile, desktop, or another terminal, then review its diff and create a pull request.

AQ is where teams put AI agents to work on reviewed pull requests, using the agents and subscriptions they already have, with shared workspaces on private cloud machines of their own.

As verified on November 7, 2026, Anthropic documents cloud sessions for Pro, Max, Ultra, and Team plans, and for Enterprise users with premium seats or Chat + Claude Code seats. Enterprise custom roles need the cloud sessions permission, and an organization can disable cloud sessions through policy. Scheduled tasks have their own organization toggle and, where custom roles apply, their own permission.

What is a Claude cloud session?

An interactive cloud session pairs one Claude Code conversation with an environment for a task. In the default Anthropic-hosted configuration, Claude gets an isolated Ubuntu VM, clones the selected repository, runs the environment's setup script, works on a branch, and pushes changes for review. The conversation remains available after a push, so you can inspect the diff, add inline comments, create a pull request, or ask for another change.

A cloud environment is the saved configuration behind that work. It controls setup commands, environment variables, network access, and network secrets. Team and Enterprise organizations can also route sessions to self-hosted cloud environments, currently in public beta, where their own runners execute the session. The cloud environment documentation covers configuration and environment selection.

Several features use the word session, but they have different execution and persistence rules:

WorkflowWhere it runs and how it startsDoes your machine need to stay on?What persists?
Interactive cloud sessionOne task starts from the browser, an app, or claude --cloudNoThe conversation and cloud environment; pushed branches are durable, while a reclaimed VM loses running work
Cloud scheduled task, formerly a routineA saved prompt runs on a schedule, API call, or GitHub event. Each trigger starts a new session outside a project's threads; a project run can continue a threadNoThe saved task configuration and run history
Session-scoped /loopA prompt repeats inside an existing session, on that session's machineNo while a cloud session's environment is active; yes for a local sessionOnly while the session process and environment remain available. A recurring loop expires after seven days
Pull request auto-fixA cloud session watches GitHub CI failures and review comments on one PRNoThe session and its auto-fix setting remain available until you stop monitoring or the session ends
Remote ControlA local terminal, IDE, or desktop session becomes reachable from the web or mobileYes, with the local process running and the machine awakeYour local session and files, under your machine's normal persistence rules

Use the product documents for the detailed configuration steps: cloud scheduled tasks, session-scoped scheduling, auto-fix, and Remote Control. The sections below call out the behavior that changes which one you should choose.

How to start and use a Claude cloud session

  1. Connect GitHub. Authorize the Claude GitHub App during browser onboarding, or run /web-setup to connect the token from the GitHub CLI. Auto-fix and GitHub triggers require the app. Team and Enterprise owners control whether members see /web-setup through Quick setup.
  2. Choose a starting surface. Open claude.ai/code, use the Code tab in the mobile app, select a Cloud environment in the desktop app, or run claude --cloud from a repository.
  3. Select the environment and permission mode. The default environment uses Limited network access, with Allow package managers checked so the default package-manager allowlist applies. Cloud sessions offer Accept edits, Plan, and Auto when the organization and model support Auto. Bypass permissions is unavailable.
  4. Write a bounded assignment. Name the outcome, relevant files, constraints, and checks. Push the branch and commits the task needs before starting from a terminal, because the normal path clones the GitHub remote rather than your checkout.
  5. Monitor or step away. The active task continues without your laptop. Reopen it from another device to answer a question, add a follow-up, or retract a queued message Claude has not read.
  6. Review and checkpoint. Inspect the diff, comment on lines, ask Claude to commit and push work in progress, and create a pull request when the branch is ready. Run your normal review and required checks before merging.

I re-ran the installed CLI on November 7, 2026. It reports 2.1.319 (Claude Code), and its local claude --help output shows --cloud [description|session_id|url] and --environment <environment_id>. This is interface evidence from the installed CLI, not a live cloud integration test.

# Start a new interactive cloud session
claude --cloud "Fix the flaky test in auth.spec.ts"

# Start independent tasks in parallel
claude --cloud "Update the API documentation"
claude --cloud "Refactor the logger to use structured output"

# Queue one follow-up into an existing session
claude -p "Also update the changelog" --cloud <session-id>

# Route a new session to a self-hosted environment
claude --cloud "Run the integration tests" --environment <ccpool_environment_id>

# Continue a cloud session in a clean local checkout
claude --teleport <session-id>

Each claude --cloud "task" invocation creates a separate session and branch. Anthropic-hosted sessions get separate VMs; a self-hosted runner starts a separate Claude Code process for each session. The older --remote spelling is a deprecated alias. The --environment flag accepts a self-hosted ccpool_... ID, not an Anthropic-hosted env_... ID. Use /remote-env to select an Anthropic-hosted environment from the CLI.

The CLI hands work from cloud to terminal with --teleport; it does not upload an existing local conversation into a cloud session. The desktop app can send a local Code session to the cloud from its Open in menu. After teleporting, later local messages and edits stay in the terminal's own copy.

Cloud scheduled tasks run saved work without your machine

A cloud scheduled task, formerly called a routine, is a durable configuration containing a prompt, one or more repositories, an environment, triggers, and connectors. It is in research preview, so its behavior, limits, and API can change. Create and manage tasks at claude.ai/code/routines or with /schedule outside a cloud session.

A task can run on a recurring or one-time schedule, from an authenticated HTTP POST to its API trigger, or from a GitHub event. You can combine triggers or use only one. A task with no schedule has no next run time, but it can still fire through its API or GitHub trigger. Outside a project's threads, every run starts a fresh cloud session with the saved prompt. The scheduled task documentation covers cron syntax, API headers, event filters, and hourly caps.

  • Bound the reach. Select only the repositories the task needs, choose an environment with the minimum required network access, and review the connectors. All connected connectors are included by default, including their write tools, so remove every unneeded connector before saving.
  • Know the identity. A scheduled task belongs to an individual claude.ai account and is not shared with teammates. Its GitHub commits, pull requests, Slack messages, Linear tickets, and other connector actions use that person's connected identity.
  • Budget the runs. Runs consume the owner's Claude plan allowance just like interactive sessions. Trigger-specific hourly caps also apply, and they have no overage. A subscription usage limit rejects later runs unless usage credits are enabled.
  • Handle permission waits. Auto mode can still stop for an ask rule or after repeated blocks. Open the run to answer. A session waiting for approval or connector sign-in can expire while it waits.
  • Read the transcript. A Succeeded history row means the session ended without a Claude Code failure. It does not prove the requested work completed; blocked requests and unfinished work can appear only in the transcript.

The saved task is durable independently of any one session. That is different from session-scoped work: when an interactive cloud VM is reclaimed, pending commands, subagents, session-scheduled tasks, and a /loop waiting for its next iteration do not resume. Use a cloud scheduled task for recurring work that must survive environment reclamation, and use /loop for polling inside an active session.

Auto-fix watches CI failures and review comments

Auto-fix requires the Claude GitHub App on the repository. Enable it from the PR menu in a cloud session's Changes card, run /autofix-pr on the PR branch, paste an existing PR URL into a session, or ask the mobile app to watch the PR. Claude then receives CI check failures and new review comments.

For a clear fix that does not conflict with earlier instructions, Claude can edit and push the branch, then explain the change in the session. For an ambiguous or architecturally significant request, it asks before acting. Duplicate events and comments that need no change only add a note.

Two limits need explicit handling:

  • GitHub emits no webhook when an advancing base branch creates a merge conflict, so auto-fix cannot respond to that conflict by itself. Open the session and ask Claude to rebase.
  • Claude's review-thread replies use your GitHub identity with a Claude Code label. Comment-triggered automation such as Atlantis, Terraform Cloud, or a custom issue_comment workflow can treat that reply as your instruction. Review those workflows before enabling auto-fix, and disable it where a PR comment can deploy infrastructure or run privileged operations.

What persists, what expires, and what to push

An active cloud session keeps working after your laptop or tab closes. After a few idle minutes, an Anthropic-hosted VM pauses with its files saved. Anthropic does not publish a fixed reclamation deadline. If the paused VM is reclaimed, reopening provisions a fresh VM and restores the conversation history, but it does not restore running or pending work.

StateWhat survivesWhat to do
Laptop or tab closesThe active cloud session keeps runningReopen from another device to monitor or steer
VM pauses while idleConversation and VM files are saved for resumeSend the next message when you return
Paused VM is reclaimedConversation history returns in a fresh VMRerun commands and subagents; recreate session tasks and /loop
Cloud scheduled task is savedIts prompt, repositories, environment, triggers, and connectors persist independentlyReview run history and the saved scope after any configuration change
Changes are committed and pushedThe branch is durable on GitHubCommit and push checkpoints during long tasks
Session is archivedThe record remains under ArchivedUnarchive before sending CLI messages
Session is deletedNothingDeletion permanently removes the session and its data

Treat the conversation, the saved cloud environment, durable cloud tasks, and pushed branches as persistent state. Treat uncommitted VM files, processes, subagents, and session-scoped schedules as temporary. The laptop-close guide compares this with local persistence and Remote Control.

Check a local bundle before starting from the CLI

Claude Code can upload a local repository when there is no remote, when a github.com repository lacks the Claude GitHub App, or when you set CCR_FORCE_BUNDLE=1. This path has a platform-specific credential safeguard:

  • macOS, Linux, and WSL: the bundle omits uncommitted changes to credential-like files, including .env, Terraform *.tfvars, id_rsa, and *.pem. It also omits uncommitted changes managed by a git filter such as Git LFS. A Left on this machine: notice names each omission. The session receives the committed version, or no file when none is committed.
  • Native Windows: uncommitted changes to tracked files upload as they are, regardless of filename. Stash or revert sensitive edits before starting. This Windows behavior comes from Anthropic's documentation; I did not test it on Windows.

Untracked files are excluded on every platform, so run git add on a new file the task needs after reviewing it. A full bundle must be under 100 MB; larger repositories fall back to the current branch and then a single squashed working-tree snapshot, and fail if that snapshot is still too large. A bundled GitLab, Bitbucket, or other non-GitHub repository cannot push results back to that remote. Results can push to a GitHub remote only when your GitHub connection has push access there.

Run these local checks before claude --cloud:

git status --short
git diff --name-only
git diff --cached --name-only
git ls-files --others --exclude-standard

Review every listed path, then stash or revert any sensitive tracked edit. Do not rely on the filename filter as a secrets scanner. A GitHub clone from a pushed branch avoids the local bundle path and its working-tree rules.

Security: threat model, boundaries, and checks

The threat model is an agent that follows useful instructions with access to code, credentials, and external services. Repository files, pull request text, CI output, API fire payloads, and connector content are untrusted input. They can contain instructions that try to redirect the agent, disclose data through an allowed host, or invoke a write through your identity. An isolated VM limits host access; it does not make every model action safe. The API fire wrapper labels payload text as untrusted, but you still need a saved prompt that restricts how the task uses it.

Assign responsibility for each boundary

  • Anthropic-hosted VM. Anthropic provides a fresh isolated VM and the session proxies. You choose the repository, prompt, permission mode, environment, connectors, and network policy. Review those inputs and the resulting branch. Approximate documented resource ceilings are 4 vCPUs, 16 GB RAM, and 30 GB disk, and they can change.
  • Self-hosted runners. Your organization owns runner isolation, images, host updates, network egress, and the credentials its deployment supplies. Repository checkouts and build artifacts stay on operator machines, but prompts, responses, tool results, and the session transcript still go to Anthropic. That remains true when model requests use Bedrock or Google Cloud's Agent Platform. Self-hosting alone supports no compliance or total-locality claim.
  • Transcript and model flow. Anthropic stores the cloud transcript so you can resume on another surface. A third-party model route changes inference hosting, not the session event stream to api.anthropic.com. Interactive --cloud sessions themselves require a claude.ai sign-in and do not run through third-party provider authentication.
  • GitHub credentials. In Anthropic-hosted environments, real git credentials and signing keys stay outside the VM. The GitHub proxy substitutes scoped credentials for attached repositories. It rejects branch deletion, non-branch pushes, and GraphQL requests. A token you place in environment variables is visible to session commands instead.
  • Network secrets and egress exceptions. A network secret stays outside the VM and is attached to matching requests after they leave it. Secret hosts, GitHub, enabled connectors, and the Anthropic API use paths outside the ordinary allowlist. Even None network access still permits the Anthropic API. Environment variables are readable by anyone who uses the environment, so do not put secrets there.
  • Connector authority. Include only connectors required for the task and prefer read-only scopes. Connector traffic travels through Anthropic's servers rather than the session's network allowlist. A prompt or fetched document can ask Claude to write through an included connector, so least privilege and ask rules matter.
  • Review and release. Use GitHub branch protection or rulesets to constrain pushes, and keep human diff review and required checks before merge or deployment. Check whether the connected identity can bypass those rules; a rule that identity may bypass will not stop its pushes.

Plan for failure modes

Environment reclamation stops commands, subagents, and session loops. A permission or connector sign-in wait can end in expiry. Missing GitHub authentication makes scheduled tasks skip runs for up to 72 hours and then turn off. A base-branch conflict produces no auto-fix webhook. A successful run status can hide unfinished work. Native Windows can include a sensitive tracked edit in an upload. Each case needs a checkpoint, a narrower permission, a manual review, or a rerun rather than an assumption that automation recovered it.

Reproduce the important checks with synthetic data

  1. Scope. Use a disposable repository with synthetic files and no production credentials. Confirm the selected environment, network level, attached repositories, and connector list before the first run. Expect no unneeded write-capable connectors.
  2. Untrusted input. Add a harmless instruction in a test issue, PR comment, and API fire payload that asks the agent to change a marker file or call an unneeded connector. Verify that the saved prompt and permission rules do not authorize that action. Remove the test content afterward.
  3. Network. Ask the session to request a domain outside the Limited allowlist. Expect a 403 with x-deny-reason: host_not_allowed. Then test the one synthetic API host the task needs and inspect its logs. Repeat after environment changes because GitHub, connectors, network secrets, and the Anthropic API do not prove the ordinary allowlist is open.
  4. GitHub proxy. Ask the session to print GH_TOKEN. With proxy authentication it should read proxy-injected, not a usable token. Test a REST request with gh api repos/{owner}/{repo} for an attached repository and expect success; expect an unattached repository or GraphQL request to fail with 403.
  5. Branch protection. On a disposable repository, attempt a push that violates the expected rule and confirm GitHub rejects it. Open the resulting PR through the normal path and verify that required checks and a human reviewer are still necessary.
  6. Persistence. Commit and push a non-sensitive checkpoint, close the browser, and reopen from another device. Verify the conversation and branch. After any actual reclamation, expect to rerun background commands and recreate session-scoped schedules; do not wait for reclamation with the only copy of your work.
  7. Auto-fix. On a synthetic PR, introduce a clear CI failure and verify the fix commit and session explanation. Add an ambiguous review request and verify Claude asks first. Advance the base branch into a conflict and confirm you must request the rebase yourself. Keep comment-triggered deployment workflows disabled during the test.

Choose Anthropic cloud, a DIY VM, or AQ

ChoiceChoose it whenBoundary you accept
Anthropic-hosted cloud sessionYou want a bounded GitHub task, parallel branches, durable cloud tasks, or PR auto-fix without operating infrastructureAnthropic-managed execution and transcript storage, temporary VM state, plan usage limits, and GitHub-centered review
Anthropic self-hosted environmentYour Team or Enterprise organization needs session execution and internal network access on its own runnersYou operate the runners and egress, while orchestration and transcripts still use Anthropic
Claude Code on your own VMYou need a persistent terminal, a non-GitHub remote, custom tools, internal services, or direct control of one machineYou provision and maintain the machine, access, updates, backups, and terminal persistence
AQA team needs to enter the same live CLI session, work in isolated worktrees on a dedicated machine, and review terminal, editor, preview, and changes togetherAQ hosts the team workspace layer, while your chosen agent CLI and model provider process the session

The DIY Claude Code VM guide covers provisioning and terminal persistence. Use Claude Code Projects when one person wants Claude to coordinate several related sessions. The choice criteria above separate those workflows from a shared team workspace.

Where AQ fits

AQ is where teams put AI agents to work on reviewed pull requests, using the agents and subscriptions they already have, with shared workspaces on private cloud machines of their own. Each work item has its own branch and worktree. Teammates with access can open the same running terminal, editor, and app preview, and request control of the live session. On the AQ Pro plan, that machine can be a customer-connected cloud VM or a dedicated always-on AQ-managed machine; Free runs agents on your own Mac with the AQ Mac app.

Use Anthropic cloud when you want to delegate a GitHub task into Anthropic's session and PR workflow. Use a DIY VM when you want to operate the terminal host yourself. Use AQ when several people need persistent access to the work and the same live session. AQ does not reproduce Anthropic-managed cloud sessions, scheduled tasks, or auto-fix. AQ Build covers work items, AQ Bots covers scheduled and event-driven team jobs, and AQ vs Claude Code on the web holds the feature-by-feature matrix.

Original AQ application proof

On November 7, 2026, I captured the production build of the real AQ React application using the fictional Ascent demo workspace and a mocked API and WebSocket stream. No production account, customer content, real credential, model call, GitHub call, or Anthropic cloud integration participated. The terminal lines and repository content are synthetic.

AQ desktop work item with a live Claude terminal showing a synthetic Claude Code version, isolated worktree path, branch, edited file, and passing test result
This application walkthrough proves that AQ renders a real CLI terminal tab with branch and worktree context, a message input, and Changes access. The displayed CLI output is synthetic. It is not a production Anthropic integration test or proof of a live model session.
AQ desktop Changes panel for a synthetic countdown branch showing five changed files, a TypeScript diff, an inline review comment, and a pull request card
The same application walkthrough proves the review surface: branch scope, file and line counts, a unified diff, an inline comment, and PR state with checks. It does not test a production Anthropic, GitHub, or deployment integration.

To verify the workflow in your own AQ workspace, create a work item, open its real CLI tab, confirm the branch and worktree in the item details, and inspect the same branch under Changes. Ask a teammate with access to open the workspace and verify the live terminal and preview before granting terminal control. Keep your normal model, credential, and branch-protection review.

Sharing and usage limits

  • Sharing. Team and Enterprise sessions can be Private or Team. Pro, Max, and Ultra sessions can be Private or Public, where Public still requires a claude.ai login. Recipients see the latest state when they open the link, not a live-updating view. Inspect code, output, and credentials before changing visibility.
  • Plan usage. There is no separate charge for the Anthropic-hosted VM. Interactive sessions, scheduled runs, and parallel work draw from the same plan allowance and consume it faster when they overlap. Eligible accounts can enable usage credits for metered overage. See the Claude Code usage limits guide for windows and overflow options.
  • Organization restrictions. Cloud sessions require the relevant plan, seat, role, and organization policy. An organization IP allowlist can block Anthropic-hosted sessions because their API calls originate from Anthropic-managed infrastructure. Self-hosted environments are unavailable with Zero Data Retention or the HIPAA configuration.

Frequently asked questions

What is a Claude cloud session?

A Claude cloud session is a Claude Code conversation and execution environment that runs on cloud infrastructure instead of your computer. It usually starts from a GitHub repository, works on its own branch, keeps running after your laptop closes, and can be monitored or steered from the web, mobile, desktop, or another terminal.

How do I use Claude cloud sessions?

Connect GitHub, choose an environment, and start from claude.ai/code, the mobile or desktop app, or claude --cloud "your task". Push local commits the task needs first. Give Claude a bounded assignment, review its diff and tests, ask for checkpoints, and create a pull request when the branch is ready.

Are Claude cloud sessions available on Ultra?

Yes. As verified on November 7, 2026, Anthropic lists Pro, Max, Ultra, and Team, plus Enterprise users with premium seats or Chat + Claude Code seats. Enterprise custom roles need the cloud sessions permission, and organization policy can still disable access.

What is the difference between a cloud scheduled task and an interactive cloud session?

An interactive session is one conversation you start and steer for a task. A cloud scheduled task is a durable saved prompt with repositories, an environment, triggers, and connectors. It runs on a schedule, API call, or GitHub event, and each trigger normally starts a new session outside a project's threads. Scheduled tasks belong to an individual account and use that person's plan allowance.

How does pull request auto-fix work?

With the Claude GitHub App installed and auto-fix enabled, Claude watches the PR for CI failures and review comments. It can push a clear fix, asks before ambiguous or architecturally significant work, and replies with your GitHub identity plus a Claude Code label. It receives no webhook for a base-branch conflict, so you must ask it to rebase. Review comment-triggered automation first because a reply can start privileged workflows.

Are local credential edits safe when native Windows starts a cloud session?

Native Windows uploads uncommitted changes to tracked files as they are, regardless of filename. Stash or revert sensitive edits first. macOS, Linux, and WSL omit uncommitted changes to credential-like and git-filter-managed files and print a Left on this machine notice. Every platform excludes untracked files, and bundles have a 100 MB fallback limit. This Windows note is documented behavior, not a Windows test performed for this guide.

Does a Claude cloud session keep running after I close my laptop?

Yes, while its cloud environment remains active. An idle Anthropic-hosted VM later pauses with files saved and can eventually be reclaimed. Reopening restores the conversation in a fresh VM, but running commands, subagents, session-scoped tasks, and a waiting /loop do not resume. Commit and push checkpoints, and use a durable cloud scheduled task for recurring work.

How do I run Claude Code on a cloud VM?

For Anthropic-managed execution, connect GitHub and run claude --cloud "your task" from a pushed repository, or start in the Claude apps. Team and Enterprise organizations can instead route to a self-hosted environment with --environment <ccpool_environment_id>. For a VM you provision yourself, install Claude Code on that machine and use tmux or Remote Control; the DIY VM guide on this page covers that route.