Getting Remote Control working takes two things most people miss: an eligible claude.ai login (not an API key), and workspace trust accepted in the project directory you start from. Everything else is one command.
In a hurry? Sign in with /login, run claude once in your project directory to accept the trust dialog, then run claude --remote-control. Scan the QR code with your phone.
Will it work on your setup?
Remote Control refuses to start for about a dozen different reasons, and the error it prints does not always name the real one. Answer these and this will tell you what would block you, with the fix for each. Everything below is on this site already; this just narrows it to your case.
Requirements
Subscription
Remote Control is in research preview and available on Pro, Max, Team, and Enterprise plans. On Team and Enterprise it is off by default. An Owner has to switch on the Remote Control toggle in Claude Code admin settings first.
API keys are not supported. Remote Control needs a claude.ai OAuth session, because there has to be a claude.ai account for the phone or browser to pair with.
Authentication
Run claude and use /login to sign in through claude.ai if you have not already.
- Without an eligible login,
claude remote-controlexits with an error. claude --remote-controlstill starts an interactive session, then shows a Remote Control failure notification shortly after launch.- Long-lived tokens from
claude setup-tokenorCLAUDE_CODE_OAUTH_TOKENwill not work, because they can only make model requests.
API endpoint
Remote Control talks to api.anthropic.com directly. It is not available on Amazon Bedrock, Google Cloud Agent Platform, or Microsoft Foundry. From v2.1.196 it is also disabled when ANTHROPIC_BASE_URL points anywhere other than api.anthropic.com, such as an LLM gateway or corporate proxy. Unset the variable to use Remote Control.
Feature-flag evaluation
This one catches privacy-conscious developers. Each of these variables disables the feature-flag evaluation that Remote Control availability depends on:
DISABLE_TELEMETRYDO_NOT_TRACKCLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFICDISABLE_GROWTHBOOK
If any of them is set, Remote Control will refuse to start. Unset it in your shell environment and in the env block of any settings.json file.
Workspace trust
Run claude in your project directory at least once and accept the workspace trust dialog. Important detail: the startup trust dialog never saves trust for your home directory, so always start Remote Control from a real project directory, not from ~.
Setup checklist
| Check | How to confirm |
|---|---|
| Eligible plan | Pro, Max, Team, or Enterprise. On Team/Enterprise, confirm an Owner enabled the toggle. |
| Signed in via claude.ai | Run /status and confirm the login method is claude.ai, not an API key. |
No ANTHROPIC_API_KEY set | echo $ANTHROPIC_API_KEY returns nothing. |
No custom ANTHROPIC_BASE_URL | echo $ANTHROPIC_BASE_URL returns nothing. |
| No telemetry-disabling vars | None of the four variables above are set. |
| Workspace trust accepted | You have run claude in the project directory once. |
If something is off, claude doctor reports which individual eligibility check failed.
Your first session
From your project directory:
cd ~/projects/my-app
claude --remote-controlThat starts an interactive session that is also reachable remotely. To convert a session you already have open, run /remote-control instead. For a server that hosts several sessions, use claude remote-control. Either way Claude Code prints a session URL. In server mode, press the spacebar to show a QR code.
Then connect from another device:
- Open the session URL in any browser to land on the session at claude.ai/code.
- Scan the QR code to open it in the Claude mobile app.
- Or open claude.ai/code (or the Claude app, then tap Code) and pick the session from the list. Remote Control sessions show a computer icon with a green dot when online.
If the environment already has an active session, Claude Code asks whether to continue it or start a new one.
Running several sessions at once
Two approaches, depending on what you want:
| Approach | How | Trade-off |
|---|---|---|
| Multiple processes | Run claude --remote-control in several terminal windows. Each registers one remote session. | Simple, but each session needs its own terminal. |
| Server mode | Run claude remote-control once. Default capacity is 32 concurrent sessions. | One process hosts many sessions. Use --spawn worktree so sessions do not fight over the same files. |
In server mode, --spawn same-dir (the default) means every session shares the working directory and can conflict when editing the same files. --spawn worktree gives each on-demand session its own git worktree, which is usually what you want for parallel work. Press w at runtime to toggle.
Keeping a session alive on a remote machine
Remote Control runs as a local process. If you close the terminal or quit VS Code, the session ends. To keep one running on a box you reach over SSH, start it inside tmux or screen so it survives your disconnect.
tmux new -s claude
cd ~/projects/my-app
claude remote-controlDetach with Ctrl-b d. The Remote Control session keeps running and stays reachable from your phone.
Auto-connecting every session
Run /config inside Claude Code and set Enable Remote Control for all sessions to true. Set false to never auto-connect, or default to fall back to your organization or Claude Code default. The Desktop app exposes the same switch under Settings, Claude Code.
Turning it off
To disable Remote Control entirely on a machine, use the disableRemoteControl setting. Organizations with Zero Data Retention or similar compliance configurations cannot enable Remote Control at all.