Claude Code Remote Control not working: what to check

Start with what you are looking at

Three failures read as one in a search result and have almost nothing in common once you are in front of them. Pick the one that matches your screen, because the fix for each sits in a different section of this page.

• It will not start at all, and the terminal printed a message
• It started, but the session never shows up on your other device
• It connected once, then dropped, or keeps dropping

If the message on your screen is not on this page, the Claude Code error messages guide covers the wider API and HTTP family, and the login errors guide covers sign-in failures that are not specific to Remote Control.

The checks worth doing before you debug anything

Remote Control is not a separate app and it is not a tunnel. It connects claude.ai/code or the Claude app to a Claude Code session running on your machine, and the code keeps executing locally the whole time. The web and mobile views are a window into that session, which is why the computer has to stay awake and the claude process has to keep running.

An eligible login

It is available on Pro, Max, Team and Enterprise plans. API keys are not supported, and on Team and Enterprise an Owner has to enable the Remote Control toggle first. Without an eligible login, claude remote-control exits with an error, while claude --remote-control still opens an interactive session and reports the failure in a notification shortly after launch. That difference matters: the second form looks like it worked.

The endpoint your session talks to

Remote Control needs a session talking to api.anthropic.com directly. It is unavailable on Amazon Bedrock, Google Cloud's Agent Platform and Microsoft Foundry, unavailable when ANTHROPIC_BASE_URL points anywhere else, such as an LLM gateway or a proxy, and unavailable through an enterprise Claude apps gateway sign-in.

Feature-flag evaluation

If a variable turns off feature-flag evaluation, availability depends on which one. CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC or DISABLE_GROWTHBOOK makes Remote Control unavailable, and the variable has to be unset wherever it is set, including the env block of a settings file. DISABLE_TELEMETRY or DO_NOT_TRACK on its own leaves it available unless your organization requires Trusted Devices, on Claude Code v2.1.283 or later, or v2.1.304 or later in the Claude Desktop app.

Two prompts can also stop a start. In a directory you have not trusted, the server asks Trust <directory>? [y/N] before it starts, the answer is never saved in your home directory, and with no terminal to answer on it exits with a Workspace not trusted error. Server mode also asks Enable Remote Control? (y/n) until you accept, and answering no exits without starting anything.

It will not start: the message, and the fix

The first thing to check is which credential the session is using, because the same failure prints three ways. Signed out, /remote-control or --remote-control says Remote Control requires a claude.ai subscription., while claude remote-control says You must be logged in to use Remote Control. Remote Control is only available with claude.ai subscriptions. Signed in, with a credential that outranks your login, the line is Remote Control requires claude.ai subscription auth. followed by the credential in use, and an apiKeyHelper setting and ANTHROPIC_AUTH_TOKEN are named the same way. The fix in every case is claude auth login with the claude.ai option, plus removing whichever variable or setting the message named.

Remote Control requires a claude.ai subscription.

A related line, Remote Control requires a full-scope login token, means the session was authenticated with a long-lived token from claude setup-token or from CLAUDE_CODE_OAUTH_TOKEN. Those tokens can make model requests and nothing else, so they cannot establish a Remote Control session, and claude auth login is the fix.

When the account itself is the problem

Two messages point at the account rather than the credential. Unable to determine your organization for Remote Control eligibility means cached account information is stale, and claude auth login refreshes it. Remote Control isn't enabled for this account means the account-level check came back off, usually with cached entitlements after a plan change, so log out and back in; claude doctor shows which individual check failed, and before v2.1.239 the same line read Remote Control is not yet enabled for your account.

Two more are about the feature-flag check. Couldn't verify Remote Control eligibility means Claude Code could not reach the feature-flag service, which usually means you are offline or behind a proxy that blocks it, so retry once there is network or run claude doctor. Remote Control requires feature-flag evaluation names the variable that switched evaluation off, and on v2.1.154 through v2.1.282 you get this message from DISABLE_TELEMETRY or DO_NOT_TRACK as well, so the fix there is to update Claude Code.

When something routed the session away from the Anthropic API

Remote Control is only available when using Claude via api.anthropic.com.

The message does not stop there. It names what routed the session away, such as CLAUDE_CODE_USE_BEDROCK or a custom ANTHROPIC_BASE_URL, and that name is the whole answer: unset it, check the env key of your settings files if it is not in your shell, and restart the session.

When the organization is the problem

Remote Control is disabled by your organization's policy

This one has five causes and they are worth checking in the order Anthropic lists them. A disableRemoteControl in managed settings turns it off on your device regardless of anything else. Being signed in under a Team or Enterprise organization while your own plan is Pro or Max checks that organization's policy, which /status shows. The HIPAA configuration turns Remote Control off, and /status shows HIPAA on the Organization configuration line. Custom roles on an Enterprise plan need both the cloud sessions permission and the Claude Code remote control permission. Failing all four, an Owner has not enabled the toggle, because Remote Control is off by default on Team and Enterprise plans.

Two neighbouring messages are different states of the same policy. Remote Control was turned off by your organization's policy means the policy changed while a session was connected: the session keeps running without Remote Control and is archived, server mode stops and archives what it was serving then exits, and nothing reconnects on its own. Couldn't verify your organization's policy for remote control means Claude Code could not fetch the policy and has no saved copy, usually because it started offline or before a VPN connected. Each attempt checks again, so no restart is needed, and claude doctor prints an Organization policy line saying why it did not load. Before v2.1.281 that state showed the disabled message instead, which is one reason older write-ups about this failure read wrong.

When the connection itself cannot be established

Two messages cover the last layer. Remote credentials fetch failed means Claude Code could not obtain a short-lived credential, and --verbose prints the full error behind it. The common causes are not being signed in, a firewall or proxy blocking outbound HTTPS on port 443, and a session creation failure. Remote Control got an unexpected server response means the server replied in a form this version cannot read, and retrying on the same version fails the same way, so run claude update and then /remote-control.

If your organization requires Trusted Devices, two more lines appear here. Your organization requires Trusted Devices for Remote Control, but this device is not enrolled is fixed by /login, because enrollment happens as part of signing in and there is no separate command. session expired for trusted-device check means the sign-in is more than 18 hours old, and either signing in again or confirming with Face ID, Touch ID, Windows Hello or a passkey clears it.

It starts, but the session never appears on your other device

Remote Control does not turn itself on. It activates only when you run claude remote-control, claude --remote-control or /remote-control, unless auto-connect is enabled, and auto-connect lives in /config under Enable Remote Control for all sessions. That toggle takes three values: true, false, and default, which clears your choice and follows your organization's admin default. A settings file can carry the same setting as remoteControlAtStartup, and there is one asymmetry worth knowing: a project or local settings file can turn auto-connect off, but its true is ignored, so a checked-in file cannot turn Remote Control on for everyone who opens the repository.

Then there is the count. With auto-connect on, each interactive claude process registers one remote session, so several instances each get their own, and outside server mode one instance supports one remote session at a time. If you started a second terminal and expected it to join the first session, it did not: server mode is the way to drive many sessions from one process.

Where to look also matters. Sessions are listed at claude.ai/code, and in the Claude app under Code, where a Remote Control session shows a computer icon with a green status dot when it is online. Server mode is worth a second look for a different reason: it accepts up to 32 concurrent sessions by default, and --spawn decides whether on-demand sessions share the directory, get a git worktree of their own, or are limited to a single session.

Two things that look like a broken session are commands that live only in the terminal. /plugin and /resume work only from the local CLI, whether or not you pass an argument. Permission modes are also narrower than the terminal's: from the app you can pick Manual, Accept edits, Plan or Auto on a Remote Control session, and Bypass permissions cannot be selected there at all. If a run stops to ask for approvals you thought were off, that is why.

It connected, then dropped, or keeps dropping

The first thing to understand is what the message does not tell you. A Remote Control disconnected or Can't reach message means your browser or app lost contact with Claude Code on your computer. It says nothing about whether Claude or a subagent is still working there, so the useful move is to look at that machine and branch on what it shows.

Three reasons mean the session moved rather than broke. Another connection took over this session means another device or Claude Code session has it now. This session was ended or archived from another device or app means exactly that, and Claude Code reopens an archived session if you ask. The server no longer reports this session means it may have been deleted elsewhere. In the first two, running /remote-control takes it back rather than repairing it. For the third, start a new one with /remote-control.

When the machine is awake but the network is not

Two documented behaviours cover most drops. Once an interactive session is connected, Claude Code keeps retrying for up to three minutes when something between your machine and Anthropic answers with HTTP 403, as can happen after a VPN or a network change; if the refusals last longer it disconnects and the reason names what refused, whether a network edge or a proxy, VPN or firewall on your own network. In a longer outage the two modes part company: server mode gives up after roughly ten minutes and the process exits, so you start it again, while an interactive session keeps retrying for as long as the outage lasts and reconnects on its own.

A disconnect that names a long silence is its own case: an interactive session that reports it could not reach the Remote Control server for about 30 minutes reconnects with /remote-control, and nothing else needs restarting.

When the login behind the connection expires

Remote Control disconnected — Claude.ai login expired — run /login to restore Remote Control

This family is larger than it looks, and each line names its own cause: the saved login expired, it was rejected, the token was unavailable, or you signed out on this machine. The fix is /login, and the messages that end run /login to restore Remote Control do not need anything further, because Claude Code reconnects once you are signed in. The ones that end run /login, then /remote-control want the second command as well.

Server mode has its own version, printed in the terminal rather than on your phone: a warning that it could not renew this computer's connection, with a sentence saying how long the current credential still works. The documented example gives about 26 hours. If it still cannot sign in when that runs out, it prints an error containing Poll: Authentication failed (401) and stops, and the fix is claude /login in another terminal on that machine, then claude remote-control again in the terminal where the server stopped.

Two account-level cases end a session that was working. Signing in to a different claude.ai account or organization on the machine stops the session with a line naming the change, and /remote-control starts a new one under the current account; before v2.1.234 that change went unnoticed until a later request failed with HTTP 404, which could be hours later. When Claude Desktop or an IDE hosts the session, a sign-out or account switch there ends it with a line saying which, and the fix is to sign in to that app and turn Remote Control back on, or start a new session under the new account.

Two open reports in Anthropic's own tracker describe close relatives of this in the desktop app. Issue 102534 reports that Remote Control drops on every idle session there and cannot be re-enabled until a message is sent from the Mac. Issue 100114 reports that it is not restored after a relaunch on the Windows desktop app and that connected sessions show as archived on the phone. Both are what their reporters describe, not Anthropic's account of the behaviour, and both are still open.

Getting a session back after the process stopped

If a resume could not reattach, Couldn't reconnect to your Remote Control session means the failure may be temporary: /remote-control retries, or claude --remote-control starts a fresh session, and the local session keeps running either way. Previous session is unavailable means Claude Code stopped instead of starting a new session on its own, and there is a trap in the fix: running /remote-control without restarting Claude Code first leaves the conversation's earlier messages out of the new session.

After a server stops, its sessions can be brought back in the same directory for about four hours. claude remote-control brings back every session the server was serving, --continue brings back only the one it started with, and --session-id <id> brings back one by the id in its claude.ai/code URL. After roughly four hours, start a new session instead.

If the session runs on a remote machine over SSH, this is the failure that catches people: the session dies with the connection. Start it inside tmux or screen so the process outlives the SSH link. The tmux guide covers keeping a terminal session alive.

What changes while a device is connected

Both of these surprise people after the connection works. Your local session makes outbound HTTPS requests only and never opens an inbound port on your machine, so a firewall rule for inbound traffic is not the fix for anything here. And while Remote Control is connected, the session transcript, including your messages, Claude's responses and tool activity, is stored on Anthropic servers, which is what keeps the conversation in sync across devices and lets it reconnect after a drop. Execution and filesystem access still stay on your machine.

If you would rather not have that at all, the disableRemoteControl setting turns Remote Control off entirely, and organizations with Zero Data Retention enabled, or with the HIPAA configuration applied, cannot enable it in the first place.

Things that are not the cause

• A session that crashes under server mode is not broken permanently. Send it a message from a connected device and Claude Code serves it again, with no server restart, on v2.1.238 or later.
• A file that did not arrive is not a dropped message. Claude still gets the message and the files that downloaded, with a note such as [1 of 3 attachments did not arrive] where the missing ones should be.
• --sandbox and --no-sandbox were removed in v2.1.300, so a startup script or wrapper that still passes either one makes the server exit instead of starting.
• One common cause of missing push notifications is a phone-side token. A /config row reading No mobile registered clears the next time Remote Control connects, once you have opened the Claude app so it can refresh its token.

Omniscio and Remote Control

Omniscio is the desktop app we make for running many Claude Code sessions at once. Remote Control is Anthropic's feature, and there is no Omniscio tie to it: the app does not start it, proxy it, or repair it, and nothing in its spawn path passes --remote-control or /remote-control. The remote control Omniscio does have is its own paired mobile-web device, which is a different mechanism with a different job.

There is one real consequence worth stating, and it is a limit rather than a feature. Two kinds of session the app starts talk to a host that is not api.anthropic.com. The first is a session on one of the Anthropic-compatible providers it supports, which are deepseek, kimi, glm, minimax, meta, qwen and openrouter, where the base URL and the auth token belong to that vendor. The second is a session on one of the app's own gateway lanes, which include Omniscio credits, the onboarding-managed credential and the developer subsidy, where the base URL belongs to the app's own gateway. Anthropic puts a base URL other than api.anthropic.com, and an auth token in place of a claude.ai login, on its list of things that make Remote Control unavailable, so it will not start on either kind of session, and no setting in Omniscio changes that.

A session signed in with your own claude.ai login looks like the case that should work, and it does not. That session is not redirected to another host, because any inherited base URL is stripped before the process starts, so the endpoint is fine. What stops Remote Control there is the shape of the session: Omniscio runs Claude Code as a background process instead of an interactive terminal, and it hands a login account's token to the binary as CLAUDE_CODE_OAUTH_TOKEN, a credential Anthropic documents as able to make model requests and unable to establish a Remote Control session. The practical answer is that Remote Control is not part of how an Omniscio session works on any lane, and the way to use it is claude --remote-control in a terminal of your own.

Omniscio's own phone access is a separate arrangement that serves the app's interface to a phone, and it is off by default until you turn it on; the Claude Code on a phone guide covers what it does, how it compares with Remote Control and Dispatch, and what it takes to set up. The features page lists what the app does, and the download page has the installers.

Sources

Every message and every behaviour on this page rests on one of these. The date beside each one is the day we read it.

• Remote Control, for what the feature is, its requirements, the three ways to start it, auto-connect, the connection model, the limitations and the whole troubleshooting catalogue. Read October 27, 2026.
• Claude Code in the Claude app, for the permission modes Remote Control sessions offer from the app. Read October 27, 2026.
• Claude Code error reference, for the login-refresh disconnect lines, the connection-renewal warning and its Poll: Authentication failed (401) ending, the account-change message and the desktop or IDE host messages. Read October 27, 2026.
• Settings reference, for the remoteControlAtStartup and disableRemoteControl settings. Read October 27, 2026.
• Environment variables, for ANTHROPIC_BASE_URL and the feature-flag variables named above. Read October 27, 2026.
• GitHub issue 102534, open, for the report that Remote Control drops on every idle session in the Claude desktop app and cannot be re-enabled until a message is sent from that machine. Read October 27, 2026.
• GitHub issue 100114, open, for the report that Remote Control is not restored after a relaunch on the Windows desktop app and connected sessions show as archived on the phone. Read October 27, 2026.
• Two captures run on this machine on October 27, 2026 against claude 2.1.311: claude --version, and claude remote-control --help, which lists the flags above and no --sandbox.

Anthropic's Remote Control page carries six version notes across the messages quoted here, and three of them change what a reader should type. Read it again before you trust a copy of this page from a few months back.

Common questions

Why does the session show as offline when the terminal is still open?

Look at the terminal. If it shows a Remote Control disconnected line, follow the reason it names, which is usually /login or /remote-control. If it shows no failure at all, an interactive session reconnects on its own once the machine is awake and online, so there is nothing to do; server mode gives up after about ten minutes and has to be started again.

Why did Remote Control stop after my laptop slept?

The sleep itself is survivable, because Claude Code reconnects when the machine comes back online, and the condition is that the claude process is still running when it does. If the process died while the machine was asleep, the session is offline until you bring it back: claude remote-control in the same directory within about four hours for server mode, or claude --continue or claude --resume for a session started with --remote-control or /remote-control. On a remote machine, run it inside tmux or screen so the process outlives the SSH connection.

Can I use Remote Control with an API key or a third-party model?

No. It needs a claude.ai login on Pro, Max, Team or Enterprise. An API key, an auth token, an apiKeyHelper setting or a long-lived token from claude setup-token cannot establish a session, and neither can a session routed to Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, or any host other than api.anthropic.com.

Why does it say another connection took over my session?

Another device or another Claude Code session picked that session up, so this is a handover rather than a fault. The other device holds it now, and running /remote-control on the machine you want it back on takes it there.