Claude Code Remote Control: Setup, Limits and Fixes

The short answer

Remote Control connects claude.ai/code or the Claude mobile app to a Claude Code session that keeps running on your own machine. Nothing moves to the cloud: your filesystem, MCP servers, tools and project configuration stay where they are, and the phone or browser is a window into that local process. Anthropic’s documentation lists it for Pro, Max, Team and Enterprise plans, says API keys are not supported, and says Team and Enterprise Owners must switch it on first. The computer has to stay awake and the claude process has to keep running.

Most “not working” reports in the documentation reduce to a short list of causes: a login that is not a full claude.ai session, a provider or base URL that is not api.anthropic.com, an environment variable that disables feature flags, an organization policy, or an old version. The fix section below maps each exact message to its documented cause. The guide is built from Anthropic’s Remote Control page, its Claude Code on the web page, the permission modes page and the Academy tutorial, with first-party posts from Anthropic staff on X and one independent early write-up. Everything was checked on October 28, 2026. Nothing here comes from our own testing, and where the documentation is silent we say so.

What Remote Control is

Per the docs, a Remote Control session registers with the Anthropic API from your computer and then waits for work. When you open the session from claude.ai/code or the Claude app for iOS and Android, the server relays messages between that client and the local process. The model is not running in the browser and your repository is not uploaded to run elsewhere. If you quit the process, the session goes offline.

The docs list four practical benefits. First, the full local environment is available remotely, including @ autocomplete of file paths from your local project. Second, the terminal, browser and phone stay in sync, including the progress of subagents and dynamic workflows, so you can send messages from any of them interchangeably. Third, you can attach photos and files from the phone or browser; Claude sees photos directly, and other files are downloaded to your machine and passed in as @ references. Fourth, it survives interruptions: if the laptop sleeps or the network drops, an interactive session reconnects when the machine comes back.

Remote Control is available from three starting points: the CLI, the Claude Desktop app and the VS Code extension. The CLI has three modes, covered in the setup section. Whichever you use, the Remote Control sessions you create show up in the session list at claude.ai/code and in the Code tab of the mobile app, with a computer icon and a green dot while online.

Requirements

The documentation states the requirements as a list. The table restates them with the failure each one produces, because the error text is what most people search for.

One point from the research that this page can now settle: the question of whether Remote Control works with API keys has a plain documented answer, and it is no. The permission-modes page repeats it: for Remote Control the local machine must be signed in with your claude.ai account. If your shell exports ANTHROPIC_API_KEY, the docs say the session will report that API-key auth is in use and refuse; you remove the variable rather than work around it.

Setup steps

The steps below follow the order the documentation implies. Commands and flags are quoted from the Remote Control page; the order and the sanity checks are our arrangement of them.

1. Update and sign in the right way

Run claude update, then sign in with a claude.ai account: claude auth login and choose the claude.ai option, or /login inside a session. If a previous login was an API key or a setup-token, log out first. /status shows which plan and organization your sign-in uses, and claude doctor reports which eligibility check failed.

claude update
claude auth login      # choose the claude.ai option
claude doctor          # shows which eligibility check failed, if any

2. Install the phone app

Install the Claude app for iOS or Android and sign in with the same account and organization. If you do not have the app yet, run /mobile inside Claude Code to display a QR code for claude.ai/mobile, which opens the right app store.

3. Pick a start mode

In your project directory, choose one of these. The first confirmation prompt (“Enable Remote Control? (y/n)”) appears once.

4. Connect from the other device

Open the session URL in any browser, scan the QR code to open it in the Claude app, or find the session by name in the session list at claude.ai/code. In the mobile app, tap Code in the navigation. When a device connects, it shows the subagents and workflows already running in the background, and stopping one from the device stops it on your machine. The session title comes from, in order, the name you passed, your /rename title, the last meaningful message, or an auto-generated name such as myhost-graceful-unicorn.

5. Keep the host alive

The docs say that if you run claude from a terminal on a remote machine, start it inside tmux or screen so the session survives an SSH disconnect. Our related guides cover the surrounding plumbing: Antigravity Remote Control compares a similar browser-based approach, and running an agent against a remote VPS covers SSH-based setups.

# on the always-on machine
tmux new -s claude
cd ~/projects/my-app
claude remote-control --name "my-app" --spawn worktree

6. Optional: auto-connect and push notifications

Run /config and set Enable Remote Control for all sessions to true, or set remoteControlAtStartup to true in your user ~/.claude/settings.json. A true value in project or local settings is ignored, so a checked-in file cannot turn it on for everyone; a false there does turn it off. For push notifications, enable them in /config after installing the app and allowing notifications.

Flags, spawn modes and defaults

These are the server-mode flags that matter most, from the docs. Run claude remote-control --help for the list your installed version supports.

Two details catch people out. First, global flags placed before remote-control are not carried over to the sessions the server creates; Claude Code allows only those it knows are harmless to drop, such as --verbose or --model, and refuses to start for others, such as --settings, naming the flag to remove. Second, the saved spawn mode comes from your own earlier answer or from pressing w, so a server that starts in a mode you did not expect is following a saved choice, which it prints at startup.

Remote Control vs cloud sessions vs teleport

The three names are easy to confuse because they all end up in the same claude.ai/code interface. The deciding question is where Claude runs. Remote Control runs on your machine. A cloud session runs on cloud infrastructure, Anthropic-managed by default, and keeps going after you close the laptop. Teleport is not a third place to run; it is a way to pull a cloud session into your terminal.

The cloud docs add a few facts that matter for the choice. --cloud creates a new cloud session from your current repository and is unrelated to --remote-control; the older --remote spelling still works as a deprecated alias for --cloud. Because the VM clones your GitHub remote rather than your working tree, you should push first. A teleported session gets its own copy: new work in the terminal stays local and does not appear in the cloud session. To keep steering from your phone after teleporting, start /remote-control in the local session. The Desktop app can send a local session to the cloud from its Open in menu.

Boris Cherny’s post, from the Claude Code team, states the same split in two sentences: teleport brings a cloud session to your machine, and /remote-control lets your phone or the web drive a session that is already running locally. The Remote Control page also lists neighbors for when you are away from the terminal: Dispatch (message a task from the mobile app, Claude runs on Desktop), Channels (push events from chat apps into a CLI session), Slack (mention @Claude, runs in the cloud), self-hosted environments, and scheduled tasks. Remote Control is the one built for steering work that is already in progress.

Which one should you use?

Permissions and push notifications

A session you control from a phone still asks for permission the way it would at the keyboard. The permission-modes page says Remote Control sessions on your local machine offer Manual, Accept edits, Plan and Auto for a session you started yourself, and that you cannot select Bypass permissions from the app. On claude.ai/code the mode dropdown sits under the prompt box; in the mobile app, tap the + button in the prompt box and then Permission. The dropdown shows the mode the local session is in, including one set from the terminal, and updates when it changes in either place. You can also set the starting mode at launch.

claude remote-control --permission-mode acceptEdits

Cloud sessions offer a different list (Accept edits, Plan, Auto) and ignore dontAsk and bypass modes from settings files. Per the same page, with Claude Code v2.1.283 or later auto mode is the built-in starting mode for interactive terminal and VS Code sessions, where a second classifier model reviews actions instead of you; the page also states that auto mode reduces prompts but does not guarantee safety. Some things are never auto-approved in any mode, including tools matched by an explicit ask rule and the built-in AskUserQuestion tool. Claude Code keeps permission prompts and AskUserQuestion questions open until you answer them, so a phone that is out of reach leaves the session waiting. Other forwarded dialogs, such as a model-choice prompt after a safety refusal, expire after five minutes by default and then take their no-action default; the dialogExpiry setting adjusts or disables that.

Push notifications are the piece that makes unattended use practical. When Remote Control is active, Claude can push to your phone, typically when a long task finishes or when it needs a decision. You can also ask for one in the prompt, for example “notify me when the tests finish”. Setup is the app, the same account, the operating system permission, and then enabling push in /config for proactive notifications, permission prompts and questions, or both. Per-event configuration beyond those toggles does not exist. If notifications do not arrive, the docs point to No mobile registered in /config (open the app so it refreshes its push token), iOS Focus modes and notification summaries, and aggressive Android battery optimization. Claude Code skips pushes while you are typing in or focused on the connected terminal.

Connection and security

The docs describe the network model plainly. Your local session makes outbound HTTPS requests only and never opens an inbound port. It registers with the Anthropic API and polls for work; when you connect from another device, the server routes messages between the client and the local session over a streaming connection, all through the Anthropic API over TLS, using several short-lived credentials each scoped to a single purpose. Execution and filesystem access stay on your machine.

The trade-off is stated just as clearly: while Remote Control is connected, the session transcript, including your messages, Claude’s responses and tool activity, is stored on Anthropic’s servers so that devices stay in sync and the session can reconnect after a drop. Stored transcripts are retained under the data usage policy. If that is not acceptable for a repository, the disableRemoteControl setting turns the feature off entirely, and Zero Data Retention or HIPAA-configured organizations cannot enable it at all.

Trusted Devices is a beta control for stricter setups. When on, viewing or steering a Remote Control session requires an enrolled device and a sign-in no more than 18 hours old, refreshed with Face ID, Touch ID, Windows Hello or a passkey. It is off by default, Owners enable it on Team and Enterprise, and Pro and Max users can turn on Require trusted devices themselves. The docs note that sessions already running when an Owner enables it are not retroactively protected. Auto-connect signs in with your own account, so a session it starts appears only in your own Claude apps.

Limits

These are the documented limitations, grouped by what they affect. None of them are rate limits in the usual sense; the page lists no request quota specific to Remote Control.

Troubleshooting checklist

Start with the order below, then use the message table. The sequence is our arrangement; every cause and fix in the table is from the Remote Control page.

1. Is Claude Code running on the host and awake? An offline process shows as “Remote Control disconnected” or “Can’t reach” on the client. Neither message tells you whether Claude is still working.
2. Run /status. Does the plan and organization match what you expect? A leftover Team or Enterprise login on a Pro or Max plan triggers the policy error.
3. Run claude doctor. It shows which eligibility check failed and, for policy problems, the Organization policy line.
4. Is an API key or token overriding the login? Check ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, apiKeyHelper and CLAUDE_CODE_OAUTH_TOKEN in your shell and in the env block of settings files.
5. Is the session routed away from api.anthropic.com? Check ANTHROPIC_BASE_URL, CLAUDE_CODE_USE_BEDROCK and similar provider variables.
6. Are DISABLE_GROWTHBOOK or CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC set anywhere? Unset them. For DISABLE_TELEMETRY or DO_NOT_TRACK, update Claude Code and check Trusted Devices.
7. Can the machine reach the Anthropic API on port 443? Re-run with claude remote-control --verbose for the full error.
8. On Team or Enterprise, has an Owner enabled the toggle, and do your custom roles include both permissions?
9. Update with claude update and reconnect with /remote-control.

Two situations are not errors. If an interactive session’s indicator shows another connection took over the session, another device or Claude Code session has it now; reconnect only if you want it back. And if an interactive session shows “Remote Control not started here” after you resumed the conversation in a second terminal, the first terminal still has Remote Control on and the second left it off on purpose; run /remote-control in the second to move it.

How the feature evolved

Remote Control is recent, and early write-ups describe a narrower feature than today’s documentation. Simon Willison wrote on February 25, 2026 that the feature “dropped yesterday”, that it was “a little bit janky”, that he first hit a not-enabled error until he logged out and back in, and that he could run only one session at a time. Those notes are dated and are best read as a snapshot of launch week, not a description of current behavior. His re-login fix matches the current docs’ advice for stale entitlements, and today’s server mode lists a default capacity of 32 sessions. You can read the original in his link post.

Anthropic staff posts on X trace the rollout. Noah Zweben posted on March 6, 2026 that Remote Control was available to Team and Enterprise users on version 2.1.69, default off, with admins enabling it in settings. A week later he described session spawning from the mobile app on version 2.1.74 and later, for Max, Team and Enterprise at that time, with GitHub set up on mobile. The current documentation lists Pro as well and adds spawn modes, worktrees, resume and Trusted Devices, so treat those posts as the history, not as the requirements.

Anthropic also publishes a short video, Using Claude Code Remote Control, on its Claude channel, linked from the Academy tutorial page. We confirmed that the video exists and its title through YouTube’s oEmbed endpoint; we have not summarized its contents here.

Claim and evidence table

What we could not verify

• We did not test Remote Control. Every behavior above is as documented by Anthropic on October 28, 2026; the docs change often and cite many version numbers, so check claude --version against the version notes.
• We did not compare Remote Control against self-managed SSH, Tailscale and tmux setups; the docs only mention tmux or screen as a way to keep a host session alive.
• The docs list plans but no per-plan usage numbers for Remote Control, and no latency, throughput or concurrency guarantees beyond the 32-session default capacity.
• Whether a custom slash command or skill can be invoked by typing it on mobile is not stated in the pages we read; they list which built-in commands work remotely.
• The Zweben posts describe requirements as of March 2026 (Max, Team and Enterprise for spawning, GitHub set up on mobile). The current docs differ, and we do not know the exact dates of each change.
• The mobile screenshot from Boris Cherny’s thread shows the Code tab, and the spawn screenshot is a video frame. Neither is documentation of a specific Remote Control screen.
• We did not watch the YouTube tutorial in full, so we make no claims about its content.

Verdict

Remote Control is the right tool when the work is already running on a machine you own and you want to nudge, approve or review it from elsewhere without moving code or tools. It is the wrong tool if your account uses API keys, a cloud provider such as Bedrock, or a gateway, if your organization has Zero Data Retention or HIPAA configured, or if the machine will not stay on. In those cases cloud sessions (where available) are the alternative, and they trade local tools for independence from your laptop.

If it will not connect, resist guessing. The docs give each message a specific cause, and the causes cluster around login type, provider, environment variables and organization policy. Check those four before reinstalling anything. For people who plan to leave sessions running, the practical setup the docs support is a host inside tmux, server mode with worktree spawning, a deliberate permission mode, and push notifications on, with the knowledge that a pending approval waits until you answer it. For longer-term habits around Claude Code, see our Claude Code best-practice guide and the comparison in Antigravity vs Claude Code.

FAQ

Sources

Sources checked October 28, 2026.

• Continue local sessions from any device with Remote Control — Claude Code docs (requirements, modes, flags, limits, security, troubleshooting)
• Use Claude Code in the cloud — Claude Code docs (cloud sessions, --cloud, --teleport, requirements)
• Choose a permission mode and Configure permissions — Claude Code docs (modes available in Remote Control sessions, auto mode)
• Using Claude Code Remote Control — Claude Academy tutorial page and its YouTube video
• Noah Zweben on X, March 6, 2026 and March 13, 2026 (rollout posts)
• Boris Cherny on X, post 1 and post 2, March 30, 2026 (mobile app, teleport and /remote-control)
• Claude Code Remote Control — Simon Willison, February 25, 2026 (independent launch-week notes)

Related reading: Antigravity Remote Control, Antigravity on a remote VPS, Claude Code best-practice guide, and Antigravity vs Claude Code.