Table of contents

Remote Control lets you connect to a Claude Code session running on your own machine from a phone or a browser and carry on exactly where you left off. The official description puts it like this: "Start a task at your desk, then pick it up from your phone on the couch or a browser on another computer" (Continue local sessions from any device with Remote Control).

There is only one thing you really need to hold onto here. Claude runs on your machine from start to finish. Code execution and filesystem access never leave your desk. Your phone and claude.ai are a window into that local session, not the place it executes.

📌 What this article is based on: the behaviour, eligible plans and default values below were checked against Anthropic's official documentation (Remote Control / Platforms and integrations / Data usage / Advanced setup). Version-dependent behaviour is labelled with the version it requires. Trusted Devices is in beta.

1. What Remote Control is: the machine that runs is yours, not the cloud

When people hear "have an AI do development from my phone", most of them picture a container spinning up somewhere in the cloud. Remote Control is designed the other way around. Neither the computation nor the files move; only the place you drive it from does.

That difference is what decides everything you can do with it. The official documentation lists four things.

Your full local environment, remotely

Your filesystem, MCP servers, tools and project configuration all stay available. Type @ on your phone and it autocompletes file paths from your local project.

Both surfaces at once

The conversation and the progress of subagents and workflows stay in sync across every connected device. Terminal, browser or phone, it is all one conversation.

Send photos and files

Claude sees attached photos directly as part of your message. Other files are downloaded to your machine by Claude Code and passed along as @ file references.

It survives interruptions

If your laptop sleeps or your network drops, it reconnects automatically once the machine is back. Subagent and workflow updates from the gap are queued and delivered once the connection recovers.

That last point matters more than it sounds. "Kick off a build before you get on the train and collect the result when you get off" does not break just because you went through a tunnel on the way.

What you need in order to use it

Requirement Details
Plan Pro / Max / Team / Enterprise. API keys are not supported. On Team and Enterprise it is off until an Owner turns on the toggle in the admin console
Authentication Sign in to claude.ai with /login. Long-lived tokens from claude setup-token or CLAUDE_CODE_OAUTH_TOKEN cannot open a connection, because those grant permission to make model requests and nothing else
API endpoint A direct connection to api.anthropic.com is required. Amazon Bedrock, Google Cloud's Agent Platform and Microsoft Foundry are not supported. Neither is pointing ANTHROPIC_BASE_URL at another host (v2.1.196 and later)
Environment variables DISABLE_TELEMETRY / DO_NOT_TRACK / CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC / DISABLE_GROWTHBOOK all stop feature-flag evaluation, so if any of them is set the feature is unavailable
Workspace trust Run claude once in the project directory and clear the trust dialog. Trust is not saved when you do this in your home directory, so always start from the project side

⚠️ The fourth requirement, the environment variables, is easy to miss. Plenty of people set DO_NOT_TRACK for privacy reasons, and that is exactly why they get told the feature is not enabled on their account. It is a textbook case of a cause that is hard to trace back to your own configuration; running claude doctor will tell you which check failed.

2. Four ways to work from a distance, and which ones use your own PC

Claude Code offers several ways to keep working when you are not sitting at the terminal, and the first fork in the road is which ones run on your machine and which run in the cloud. Reread the official platform comparison along that axis and it looks like this.

Approach Trigger Where Claude runs Best suited to
Remote Control Connecting to a running session Your own PC (CLI / VS Code) Steering work in progress, approvals
Dispatch Sending a task from your phone Your own PC (desktop app) Handing off work while you are out
Channels Events from Telegram, Discord and the like Your own PC (CLI) Reacting to external events such as a CI failure
Claude Code on the web Submitting a task at claude.ai/code Anthropic's cloud Work with no local environment, parallel runs

The top three all run on your own PC. That is why they can reach assets that exist only locally: a repository you never cloned elsewhere, a database behind the corporate network, an installed toolchain, a deployment key. This is where the things a cloud session fundamentally cannot do live.

Sometimes the cloud is not an option

It is easy to overlook, but where your repository is hosted narrows the field. The official limitations say so: cloning repositories and opening pull requests require GitHub, and non-GitHub repositories such as GitLab or Bitbucket can be sent as a local bundle, but the results cannot be pushed back to the remote.

If you run your own Git server or an internal GitLab, the practical choices for "working from a distance" come down to Remote Control and Dispatch. That is not a matter of taste; your setup decides it for you.

3. Getting started: three entry points and how to choose

The CLI has three ways to start, and you pick between them based on whether you want to take one session with you or accept several.

1. Take the conversation you are having right now

If you are already inside a Claude Code session, this is all it takes.

/remote-control

The official wording is "starts a Remote Control session that carries over your current conversation history". It abbreviates to /rc, and an argument becomes the session title (/remote-control Article proofreading). This is the shortest answer to "something came up and I have to leave mid-task". The same command works in the VS Code extension.

2. Start with remote enabled from the outset

claude --remote-control "Project name"

This launches an ordinary interactive session with a remote connection attached. It abbreviates to --rc. You can type it at the terminal, and you can send it from your phone.

3. Server mode: accept several sessions

claude remote-control

The process stays resident as a server and waits for remote connections. Press the space bar and it displays a QR code, so pointing your phone's camera at it connects you straight away.

Flag Effect
--name "..." Sets the name shown in the session list on claude.ai
--spawn worktree Cuts a dedicated git worktree for each session (requires a git repository). The default same-dir has every session share one working directory, so editing the same file causes conflicts. Switchable at runtime with the w key
--spawn session Accepts a single session only and refuses further connections
--capacity N Cap on concurrent sessions (default 32)
--continue / --session-id Brings back sessions from a server you stopped (v2.1.200 and later)

Opening it on your phone

There are three ways to connect: open the session URL in a browser, scan the QR code, or pick it from the list in the Claude app. In the mobile app, "Code" in the navigation is the session list, and Remote Control sessions appear with a computer icon and a green dot.

If the app is not installed yet, running /mobile inside Claude Code brings up a QR code for the download (iOS / Android).

💡 The QR code is a shortcut, not authentication. Skip it and you still get to the same place by picking the session by name from the app's list. Access is decided by "whose account is this", not by "who knows the URL" — section 7 covers this.

If connecting every time gets tedious

Auto-connect is off by default and only applies when you start it explicitly. To stay connected all the time, use Enable Remote Control for all sessions in /config, or set remoteControlAtStartup to true in a settings file.

There is a nicely judged asymmetry here. A false written into project settings (.claude/settings.json) is honoured, but a true is ignored. The design makes sure a checked-in file cannot silently turn on Remote Control for everyone who opens the repository.

4. What you can and cannot do from the phone

A connected device receives everything happening in the terminal as it happens. Slash commands, however, have a line drawn through them.

✅ Available from phone and web

/compact /clear /context /usage /recap /exit
In argument form: /model sonnet /effort high /rename /fast /color
/mcp (v2.1.166+), /config key=value (v2.1.181+), /autocompact 500k (v2.1.221+)

❌ Local only

/plugin, /resume and anything else that only makes sense in the terminal UI. Adding arguments does not help.
That /resume, which switches conversations, is local-only has real consequences: wanting to move to a different conversation means going back to the PC.

Commands that open a picker or a slider in the terminal are replaced by an argument form on the phone. That is to say: write /model sonnet rather than typing /model on its own.

You can answer permission prompts, and that is the real prize

The single most useful thing in practice is that permission prompts and questions are forwarded to your phone. The documentation states that Claude Code keeps them open until you answer them. The hours a long task spends stalled on an approval while it waits for you to get home simply disappear.

Other kinds of dialog, however, have a deadline. Anything other than permission prompts and questions — the model-choice prompt shown after a safety refusal, for instance — waits five minutes by default, then closes and continues with the dialog's no-action default. dialogExpiry adjusts or disables it (v2.1.224 and later).

How long a model or effort change sticks

Action Scope of the effect
Choosing from the device's model picker That session only
Sending /model <name> Also changes the default for new sessions (same as typing it in the terminal)
Choosing an effort level That session only. If CLAUDE_CODE_EFFORT_LEVEL pins it, the change is refused (v2.1.234 and later)

The same act of "changing the model" persists differently depending on whether you pick it in the UI or send a command. This is where you get the accident of dropping to a lighter model on the move and finding the default changed with it.

5. How it calls you back: push notifications

While Remote Control is active, Claude sends push notifications. The documentation says it typically sends one when a long-running task finishes or when it needs a decision from you to continue. You can also request one explicitly in your prompt, for example notify me when the tests finish.

Configuration is two toggles in /config and nothing more; there is no per-event configuration.

Push when Claude decides

Proactive notifications at Claude's discretion. Completion of a long-running task is this one.

Push when actions required

Permission prompts and questions. The notification that tells you something has stopped and is waiting.

One thoughtful touch: no push is sent while you are actively using the terminal. Beyond that, pointing CLAUDE_CLIENT_PRESENCE_FILE at a marker file (v2.1.181 and later) means notifications are skipped for as long as that file exists — create it on screen unlock and delete it on lock, and you can also silence the stretches where you are working in another window but still sitting at the PC.

📱 The usual culprit when nothing arrives: if /config shows No mobile registered, opening the Claude app on your phone refreshes the push token. On iOS, Focus modes and notification summaries delay delivery; on Android, battery optimisation does. Check those too.

6. How it works: why no port has to be opened

The first thing to be wary of in any "drive my home PC from outside" story is opening an inbound port. Expose SSH to the internet and you become a brute-force target; VNC is no different. Remote Control avoids that structurally.

The documentation is unambiguous: "Your local Claude Code session makes outbound HTTPS requests only and never opens inbound ports on your machine."

1. Register

The local claude registers itself with the Anthropic API

2. Poll

It goes and fetches whatever work has arrived

3. Relay

When the phone connects, the server routes messages between the two

All traffic goes through the Anthropic API and is protected by the same TLS as an ordinary Claude Code session. The connection uses several short-lived credentials, each scoped to a single purpose and revocable independently.

Compared with the traditional approaches

Method Inbound port Router setup Runs locally
Exposing SSH directly Required Port forwarding ✅
VNC / remote desktop Required Required ✅
Remote Control Not required Not required ✅
Cloud session Not required Not required ❌

As a by-product of traversing NAT, you need no router configuration, no static IP and no DDNS. A PC at your parents' house or a machine on a corporate LAN will connect as long as outbound traffic gets through.

7. Security: there is one gate, and it is your account

With no inbound port, the network-side attack surface all but vanishes. So where did the risk go? It moved to the account.

The QR code is not authentication

You will find explanations that get this wrong, but the QR code is not a step in authentication. There are three ways to connect — open the URL, scan the QR, pick it from the app's list — and the moment you can pick it from a list, the QR is only a shortcut.

So what guards the gate? The documentation says this in the auto-connect section: "Auto-connect signs in with your own claude.ai account, so a session it starts appears only in your own account's Claude apps and grants no one else access." Sessions are tied to the account, not to whoever happens to know the URL.

And you can read the single-gate design out of the official wording itself. The Trusted Devices description says it "ties Remote Control access to a known device and a recent authentication, not just a signed-in account". Turn that around and the default gate is precisely one thing: a signed-in account.

Why one gate is not weak, and what that depends on

The entrance is not permanent

It exists only while the session runs. Stop the process and it is gone. This is not a door that can be probed around the clock

Long-lived tokens cannot open it

Leaking a CI CLAUDE_CODE_OAUTH_TOKEN does not translate into remote control. The permissions are kept separate

One gate means one gate's strength

If a password alone gets you in, your defence is worth exactly one password. Weakness here nullifies everything else

Which means the to-do list collapses into a single item: set up a passkey on claude.ai. The key is bound to the device, it resists phishing, and the biometric data itself never reaches Anthropic (what is stored is only the device's public key and basic metadata such as display name, platform and enrollment time). On Team and Enterprise, Trusted Devices can enforce an enrolled device plus a sign-in no more than 18 hours old across the whole organisation.

Conversation logs are stored on the server

One point deserves to be stated plainly. While you are connected, the session transcript — your messages, Claude's responses, tool execution — is stored on Anthropic's servers. That is what makes cross-device sync and recovery from a dropped connection possible. It is not end-to-end encrypted.

Account Retention
Free / Pro / Max (model improvement ON) 5 years
Free / Pro / Max (OFF) 30 days
Team / Enterprise / API 30 days

You can change the setting at any time in claude.ai's privacy settings. Organisations under zero data retention cannot enable Remote Control at all.

In fairness, it is worth adding that ordinary Claude Code already sends every prompt and output to the API, and conversation logs already sit in plain text in ~/.claude/projects/ on your machine (30 days by default, changeable with cleanupPeriodDays). What Remote Control newly adds is that a copy also persists server-side for the sake of sync.

If you lose your phone

The fastest and most certain move is to kill the claude process on the PC. The entrance itself disappears. After that, change your password and sign out. If you use Trusted Devices, removing that device from Trusted devices in account settings revokes its credential immediately.

Your phone is not holding a resident "key to the PC". The app's signed-in state is the whole of it, so the screen lock and a passkey are your defence as they stand.

The risks that actually bite in practice

⚠️ Two risks remain, and neither of them is technical — they are operational.

1. On a small screen you cannot read the whole command you are approving. Answering permission prompts from your phone is the biggest single benefit, and it is also how you end up skim-reading on the move and tapping "allow". Especially in a session holding production credentials.

2. Combine it with a mode that skips permissions and the gatekeeper is gone. Layer remote operation on top of a workflow that bypasses permission prompts and you are reaching in from outside at something with no approval gate at all. Picking one or the other is the safe side.

Isolation via --sandbox is an option, though the sandbox is not supported on native Windows (WSL 2 is). Depending on your setup, you may have to plan on doing without that particular safety net.

If you want to forbid it outright, the disableRemoteControl setting disables it. An administrator can also forbid it per device from managed settings.

8. Diagnosing failures to connect and dropped sessions

The error messages name the cause fairly specifically. Here are the common ones.

Symptom Cause and fix
It says a claude.ai subscription is required You are authenticated with an API key. Unset ANTHROPIC_API_KEY, then run claude auth login
It says a full-scope token is required You are authenticated with a long-lived setup-token style token. Those are for model requests only, so redo it with claude auth login
It says the feature is not enabled on your account Usually a stale cache after a plan change. Run claude auth logout then login. claude doctor tells you which check failed
It says feature-flag evaluation is required One of the four DISABLE_TELEMETRY-family variables is set. The message names the variable, so check both your shell environment and the env block in settings.json
It says you are not going through the Anthropic API Either a provider setting such as Bedrock or Foundry, or ANTHROPIC_BASE_URL pointing at a different host

When it drops, should you reconnect?

This is a spot where the documentation explicitly says to read the reason before deciding. A failed connection shows you why, and in the following three cases the usual "run /remote-control" advice is deliberately omitted.

Another device took it over

Rerun it only if you want it back

It was ended or archived elsewhere

Rerunning it reopens the session even if archived

The server cannot find the session

It may have been deleted from another device

When the network goes down, the mode changes the behaviour

This one is genuinely confusing if you do not know it. If the machine is awake but cannot reach the network for a sustained period:

  • Server mode: gives up after about ten minutes and the process exits. Rerun claude remote-control to start a new session
  • Interactive session: you can keep working locally as normal. Claude Code retries for as long as the fault persists and reconnects on its own once the network returns

And if you stop the server with Ctrl+C, the sessions can be brought back for about four hours (claude remote-control / --continue / --session-id). Past that, you start fresh.

💡 On a remote machine, start it inside tmux or screen. The documentation says so explicitly: dropping the SSH connection kills the process and takes the session offline. For a "Claude Code on a server, driven from a phone" setup, this is mandatory practice.

9. Remote Control or Dispatch

Both run on your own PC, which is exactly why they get confused. The dividing line is whether you have to prepare before you leave.

Aspect Remote Control Dispatch
Preparation Required (start it on the PC first) Not required (once paired, whenever it occurs to you)
Where it starts On the PC; the phone joins later On the phone
Entry point on the PC CLI / VS Code extension Desktop app
Conversation structure One conversation, synced to every device You ask a resident conversation and a separate session spawns
Plans Pro / Max / Team / Enterprise Pro / Max only
Where it fits Steering and approving work in progress Handing off work while you are out

This is not a choice of one over the other. Dispatch when you are throwing work in from outside, Remote Control when you connect before leaving your desk — using both is the natural arrangement. The details of Dispatch and where to draw its safety line are collected in a dedicated article.

Summary

  • Remote Control moves where you drive from, not where things run. Local files, MCP servers and tools all remain available
  • Outbound HTTPS only, with no inbound port opened. No router configuration, no static IP, and a smaller attack surface than exposing SSH
  • The QR code is a shortcut, not authentication. Access is decided by "whose account is this", not by who knows the URL
  • There is one gate and it is your claude.ai account, which makes a passkey the top priority. On Team and Enterprise, Trusted Devices binds it to a device and a biometric check
  • While connected, the transcript is stored on the server. Retention splits into 5 years and 30 days depending on the model-improvement setting
  • It only works while the local process is alive. On a remote machine, start it inside tmux or screen
  • The remaining practical risk is operational, not technical — tapping approve on a small screen. Be especially deliberate in sessions holding production credentials

FAQ

Q1. Can I use it from the desktop app?

The startup methods the documentation lists are the CLI and the VS Code extension; no procedure for starting from the desktop app is described. On the other hand, there is a statement that a "Settings > Claude Code > Enable remote control by default" toggle exists in the desktop app too, and another that resuming a conversation in Claude Desktop that had Remote Control active reconnects to the existing session. Check the settings screen first, and fall back to the CLI if it is not there.

Q2. Can I pick up a conversation from the desktop app in the CLI?

Very likely, yes. The documentation states explicitly that the VS Code extension, the JetBrains plugin and the desktop app all write to ~/.claude/, and conversations are stored in ~/.claude/projects/. The flow is to run claude --resume in the same directory, select the conversation, and then run /remote-control.

Q3. My Node.js is old. Can I still install the CLI?

Yes. The native installer does not use Node.js — on Windows, that is irm https://claude.ai/install.ps1 | iex in PowerShell. The npm package asks for Node.js 22 or later, but it too ships a native binary, so an old Node produces an EBADENGINE warning and the install still completes.

Q4. What happens if my PC goes to sleep?

The session goes offline, but Claude Code reconnects automatically when the machine comes back online. Status updates from subagents and workflows during the gap are queued and delivered once it recovers. If you end the process itself, though (closing the terminal, quitting VS Code), it shows as offline within seconds and has to be brought back deliberately.

Q5. How many sessions can I connect at once?

An interactive session is one remote session per process. To handle several from one process, use server mode (claude remote-control). The default cap is 32 sessions, changeable with --capacity.

Q6. Will multiple sessions trash the same files?

Under the default --spawn same-dir, every session shares one working directory, so editing the same file causes a conflict. Specifying --spawn worktree assigns a dedicated git worktree to each on-demand session (a git repository is required). You can also switch at runtime with the w key.

Q7. Can I use /resume from my phone to move to another conversation?

No. /resume is a local-only command and does not work even with arguments. Note that if you switch conversations with /resume on the terminal side, the connected device does not receive the new conversation's history or title, but new messages flow both ways to whichever conversation is open in the terminal.

Q8. How is this different from Claude Code on the web?

The execution location differs. Both use the claude.ai/code interface, but Remote Control runs on your machine, so local MCP servers, tools and project configuration all remain available. Claude Code on the web runs in the cloud, so it works without any local environment but cannot touch local assets.

Q9. Does it work through a corporate proxy or LLM gateway?

No. Pointing ANTHROPIC_BASE_URL at any host other than api.anthropic.com makes it unavailable (v2.1.196 and later). Signing in through an enterprise Claude apps gateway is out of scope too. Organisations with compliance settings such as zero data retention cannot enable it either.

Related articles