How to Fix Claude Code Remote Control Disconnects

When Claude Code Remote Control will not start, drops its connection, or refuses to reconnect, diagnose four layers in order: subscription and organization access, Claude authentication, the direct Anthropic API path, and the local Claude process that owns the session. Start a fresh sandboxed server session, confirm it appears on claude.ai or the Claude mobile app, then keep the local process running. Repeatedly scanning QR codes will not fix a failed layer underneath it.

This guide follows the current Remote Control contract and covers the common failure messages, expected results, and safe recovery sequence. It does not require opening an inbound port or exposing your development machine to the internet.

How Remote Control Actually Works

Remote Control does not move your repository into the cloud. Claude Code continues to run on your computer with access to the same files, tools, MCP servers, and project configuration. The local process makes outbound HTTPS connections through Anthropic's API, while the web or mobile client attaches to that session.

That architecture gives you a useful diagnostic boundary:

Remote Control currently does not support API-key authentication, third-party model gateways, Bedrock, Google Cloud, Microsoft Foundry, or a custom ANTHROPIC_BASE_URL.

Prerequisites

Before troubleshooting, confirm:

• Claude Code is current for the installation method you use;

• you can open and trust the project directory locally;

• claude auth status reports the intended claude.ai account;

• your network permits outbound HTTPS to api.anthropic.com;

• your Team or Enterprise owner has enabled Remote Control, if applicable;

• you can keep the local terminal or VS Code window running during the remote session.

Run the built-in health check before changing configuration:

claude --version
claude doctor
claude auth status

Expected result: Claude Code identifies its version, the diagnostic completes without a blocking installation error, and authentication belongs to the account you will use on the remote client.

Step 1: Remove Incompatible Authentication and Endpoint Overrides

Check whether the shell has an API key or custom endpoint without printing a secret:

if [ -n "${ANTHROPIC_API_KEY:-}" ]; then
  printf 'ANTHROPIC_API_KEY is set\n'
else
  printf 'ANTHROPIC_API_KEY is unset\n'
fi

printf 'ANTHROPIC_BASE_URL=%s\n' "${ANTHROPIC_BASE_URL:-<unset>}"

Expected result: ANTHROPIC_API_KEY is unset and ANTHROPIC_BASE_URL is unset. A setup token in CLAUDE_CODE_OAUTH_TOKEN also does not provide the full account scope Remote Control needs.

Test a clean invocation without changing your shell profile:

env -u ANTHROPIC_API_KEY \
  -u ANTHROPIC_BASE_URL \
  -u CLAUDE_CODE_OAUTH_TOKEN \
  claude auth login

Complete the browser login with the same account you will use remotely. If the organization shown after login is stale or incorrect, log out and repeat the login rather than copying tokens between machines.

Step 2: Start One Fresh Sandboxed Server Session

From the trusted project directory, run:

env -u ANTHROPIC_API_KEY \
  -u ANTHROPIC_BASE_URL \
  -u CLAUDE_CODE_OAUTH_TOKEN \
  claude remote-control \
  --sandbox \
  --name "remote-debug" \
  --verbose

Expected result: the terminal prints a session URL and QR code, the session appears under Remote Control in claude.ai or the Claude mobile app, and the local process remains active. --sandbox is explicit because server-mode sandboxing is not enabled by default.

If you prefer to attach Remote Control to an existing interactive session, run Claude normally and enter:

/remote-control

The shorter /rc command is equivalent. The session status should show Remote Control as active.

Step 3: Verify Both Directions Before Leaving the Machine

Send a harmless prompt from the remote client:

Report the current working directory and git branch. Do not change files or run network actions

Expected result: the answer matches the local project and branch. Then send one prompt from the local Claude session and confirm it appears remotely. This proves the remote client is attached to the intended local process, not an older session with a similar name.

Keep the local process and computer awake. Closing the terminal, quitting VS Code, or stopping Claude ends the execution host even if the remote page still exists.

Step 4: Recover a Dropped Session in the Right Order

If the status indicator disappears or the client stops receiving updates:

1. Read the local terminal first. Preserve the exact error and timestamp.

2. Confirm the machine is awake and still has outbound HTTPS access.

3. In an interactive session, run /remote-control again.

4. If the network was unavailable for roughly 10 minutes, restart the local Claude process and create a new session.

5. If reconnection repeatedly fails on the current release, stop retrying the same pairing and collect claude --version, claude doctor, the operating system, and the local error for a reproducible bug report.

Expected result: either the original local session reconnects, or one newly created session replaces it. Do not leave several ambiguous server sessions running while diagnosing one failure.

Match the Error to the Broken Layer

Do not delete Claude configuration, repositories, or credential stores as a first response. The official recovery path is to correct the failing account, endpoint, network, or process layer.

Use Aident Actions Without Moving Provider Keys to Your Phone

Because Remote Control executes through the local Claude process, its local tools remain available to the remote client. You can use that boundary for a read-only real-world check without pasting a provider token into a mobile prompt.

First verify Aident and Vault locally:

aident account auth status
aident vault vault --action status

Then, from the remote client, ask Claude:

Use Aident to find a read-only GitHub issue search Action, show me its current
input schema, and list open Claude Code Remote Control issues created in the
last seven days. Do not write, comment, or change provider state

Expected result: Claude discovers the Action, inspects its current input contract, and returns provider-owned issue state through the local session. The GitHub credential stays in Aident Vault rather than in the prompt.

For related setup, see how to connect Claude Code to real-world tools, how to reduce MCP token usage, and how to diagnose MCP connection failures.

Use Aident Loadout to complete one read-only Action from a verified Remote Control session. Measure success as one current provider result returned from your phone without copying a provider credential into the conversation.

Why This Fix Order Works

Each step proves one boundary before moving to the next. Authentication proves account eligibility. Removing endpoint overrides proves the supported network path. A fresh sandboxed server session proves the local host process. A two-way prompt proves that the remote client attached to the correct session. Only then is reconnection behavior worth debugging.

This is the repeatable structure behind Aident's Ollama networking guide: use exact problem language, answer early, run reproducible checks, state expected results, explain the boundary, and map concrete failures to fixes. It does not assume that one popular topic will transfer to another.

Sources

• Remote Control, Anthropic, accessed July 25, 2026

• Sandboxing, Anthropic, accessed July 25, 2026

• Remote Control silently drops after auto-compaction, GitHub, July 23, 2026

• Remote Control gives up after three bridge retries, GitHub, July 25, 2026

• Remote Control never reconnects after initial pairing, GitHub, July 25, 2026

• Remote Control fails to start in WSL2, GitHub, July 25, 2026

• Remote Control can remain in a failed disconnect loop, GitHub, July 25, 2026

Refresh this guide when Anthropic changes Remote Control eligibility, authentication, supported endpoints, sandbox defaults, reconnection behavior, or its research-preview status.