Two Claude Code flags sound almost identical and do unrelated things. --cloud starts a session on Anthropic’s infrastructure. --remote-control exposes a session running on your own machine. Both end up visible at claude.ai/code, which is why the two get mixed up constantly.
The docs say it plainly: --cloud creates cloud sessions, --remote-control is unrelated. If you have been treating them as variations on the same idea, that is the thing to unlearn.
Where the code actually runs
| Claude Code on the web | Remote Control | |
|---|---|---|
| Executes on | An Anthropic-managed VM | Your machine |
| Your files | Cloned from GitHub, or uploaded as a bundle | Already there, untouched |
| Your MCP servers | Not available | Available |
| Machine must stay on | No | Yes |
| Starts with | claude --cloud "task" | claude remote-control |
Everything else follows from the first row. A cloud session cannot read a file you have not pushed, and it cannot reach a local database through an MCP server on your laptop. In exchange, it keeps running when you close the lid.
Starting a cloud session from the terminal
claude --cloud "Fix the authentication bug in src/auth/login.ts"The catch that trips people up on their first run: the VM clones your current branch from GitHub, not from your working directory. Local commits that are not pushed do not exist as far as the cloud session is concerned. Push first.
From v2.1.195 the CLI shows a live checklist while the container starts, covering the clone and any setup script. Anything you type while it provisions is queued and delivered once the session is ready. Use /tasks to check progress, or open the session on claude.ai or your phone.
The older --remote spelling still works as a deprecated alias for --cloud. Worth knowing if you find it in an old script, and worth renaming while you are there, because --remote reads like --remote-control and is not.
Repositories that are not on GitHub
If the repository has no GitHub remote, Claude Code bundles it and uploads it directly. That fallback triggers on its own, or you can force it with CCR_FORCE_BUNDLE=1:
CCR_FORCE_BUNDLE=1 claude --cloud "Run the test suite and fix any failures"Bundling has real limits. The directory needs at least one commit. The bundle must be under 100 MB, and larger repositories degrade first to the current branch only, then to a squashed snapshot of the working tree. Untracked files are excluded, so git add anything you want the session to see. A session created from a bundle cannot push back to a remote unless you also have GitHub authentication configured.
Pulling a cloud session back to your terminal
This is the direction that matters if you started something in the browser and want to finish it locally. Four routes, all the same underlying operation:
claude --teleportfor an interactive picker, orclaude --teleport <session-id>for a specific one/teleportor/tpinside a session you already have open/tasks, then presst- Open in CLI in the web interface, which copies a command to paste
Teleport checks four things before it will resume:
| Requirement | Detail |
|---|---|
| Clean git state | No uncommitted changes. You are prompted to stash |
| Correct repository | A checkout of the same repository, not a fork. From v2.1.199 an unparseable remote such as an SSH host alias is accepted after a confirmation prompt, but only when owner and repository name match |
| Branch pushed | The cloud session’s branch must exist on the remote. Teleport fetches and checks it out |
| Same account | Authenticated to the same claude.ai account that owns the session |
--teleport is not --resume. --resume reopens a conversation from this machine’s local history and never lists cloud sessions.
The overlap nobody mentions
Here is the part worth knowing if you land on this site from an error message. --teleport connects through the same Remote Control session infrastructure that cloud sessions use. So when teleport fails, it fails using Remote Control wording, even though you never ran /remote-control.
You may see any of these while teleporting:
Remote Control session expiredAccess deniedRemote Control may not be available for this organization
The connection token is short-lived and scoped to your account. Run /login locally to refresh credentials and reconnect, and confirm you are on the account that owns the session. The third message means an Owner has not enabled cloud sessions for your organization, which is a different toggle from the Remote Control toggle.
If you searched one of those strings and expected a Remote Control problem, this is your answer. Nothing is wrong with Remote Control. Teleport borrowed its plumbing and inherited its error text. See troubleshooting for the errors that really are Remote Control.
Keeping your phone useful after teleporting
When you teleport, the terminal gets its own copy of the session. New work stays local and stops appearing in the cloud session on claude.ai or in the mobile app. If you want to keep steering from your phone after pulling the session down, start Remote Control in the local session:
/remote-controlThat is the clean way to use both features together: cloud for the unattended run, Remote Control for the part where you want to watch and interject.
Two patterns worth stealing
Plan locally, execute remotely
Start in plan mode so Claude explores and proposes an approach without editing anything, then hand the agreed plan to the cloud.
claude --permission-mode plan
# agree the plan, commit and push it, then:
claude --cloud "Execute the migration plan in docs/migration-plan.md"You keep control of strategy and the cloud does the long autonomous part. Note the commit and push step: the VM clones from GitHub, so a plan sitting uncommitted on your disk is invisible to it.
Parallel tasks
Each --cloud command is its own session and they run simultaneously.
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"Monitor all of them with /tasks. Bear in mind that parallel sessions consume your rate limits proportionately, since there is no separate compute charge but the usage is shared.
Isolation
- Each session runs in its own isolated Anthropic-managed VM.
- Network access is limited by default and can be disabled entirely. Even with network access off, Claude Code still reaches the Anthropic API, which means data can leave the VM by that route.
- Git credentials and signing keys are never inside the sandbox. Authentication goes through a proxy using scoped credentials.
Limits to plan around
- Rate limits are shared with all your other Claude and Claude Code usage. Parallel tasks eat them faster.
- Pushing results needs GitHub. GitLab, Bitbucket and others can be sent up as a bundle, but the session cannot push back.
- IP allowlisting breaks it entirely. Cloud sessions call the Anthropic API from Anthropic infrastructure, not your network, so every session fails with an authentication error until Anthropic-hosted services are exempted.
- Zero Data Retention organizations cannot use it, nor
/web-setup. The same constraint rules out Remote Control. - Sessions expire on inactivity and the VM is reclaimed. Reopening from claude.ai provisions a fresh VM with your conversation history restored.
Which one you want
Use Remote Control when the work has already started on your machine and you want to keep an eye on it from somewhere else. Use Claude Code on the web when the work has not started, you want it to run unattended, or the repository is not even cloned locally. They compose well: cloud for the long run, teleport to bring it home, Remote Control to keep watching from your phone.
Side-by-side breakdown on Remote Control vs Claude Code on the web, and the wider set of options in articles.