remote-control diff

remote-control.md +205 −0 added

Details

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

5# Continue local sessions from any device with Remote Control

7> Continue a local Claude Code session from your phone, tablet, or any browser using Remote Control. Works with claude.ai/code and the Claude mobile app.

9<Note>

10 Remote Control is available on all plans. On Team and Enterprise, it is off by default until an admin enables the Remote Control toggle in [Claude Code admin settings](https://claude.ai/admin-settings/claude-code).

11</Note>

13Remote Control connects [claude.ai/code](https://claude.ai/code) or the Claude app for [iOS](https://apps.apple.com/us/app/claude-by-anthropic/id6473753684) and [Android](https://play.google.com/store/apps/details?id=com.anthropic.claude) to a Claude Code session running on your machine. Start a task at your desk, then pick it up from your phone on the couch or a browser on another computer.

15When you start a Remote Control session on your machine, Claude keeps running locally the entire time, so nothing moves to the cloud. With Remote Control you can:

17* **Use your full local environment remotely**: your filesystem, [MCP servers](/en/mcp), tools, and project configuration all stay available

18* **Work from both surfaces at once**: the conversation stays in sync across all connected devices, so you can send messages from your terminal, browser, and phone interchangeably

19* **Survive interruptions**: if your laptop sleeps or your network drops, the session reconnects automatically when your machine comes back online

21Unlike [Claude Code on the web](/en/claude-code-on-the-web), which runs on cloud infrastructure, Remote Control sessions run directly on your machine and interact with your local filesystem. The web and mobile interfaces are just a window into that local session.

23<Note>

24 Remote Control requires Claude Code v2.1.51 or later. Check your version with `claude --version`.

25</Note>

27This page covers setup, how to start and connect to sessions, and how Remote Control compares to Claude Code on the web.

29## Requirements

31Before using Remote Control, confirm that your environment meets these conditions:

33* **Subscription**: available on Pro, Max, Team, and Enterprise plans. API keys are not supported. On Team and Enterprise, an admin must first enable the Remote Control toggle in [Claude Code admin settings](https://claude.ai/admin-settings/claude-code).

34* **Authentication**: run `claude` and use `/login` to sign in through claude.ai if you haven't already.

35* **Workspace trust**: run `claude` in your project directory at least once to accept the workspace trust dialog.

37## Start a Remote Control session

39You can start a dedicated Remote Control server, start an interactive session with Remote Control enabled, or connect a session that's already running.

41<Tabs>

42 <Tab title="Server mode">

43 Navigate to your project directory and run:

45 ```bash theme={null}

46 claude remote-control

47 ```

49 The process stays running in your terminal in server mode, waiting for remote connections. It displays a session URL you can use to [connect from another device](#connect-from-another-device), and you can press spacebar to show a QR code for quick access from your phone. While a remote session is active, the terminal shows connection status and tool activity.

51 Available flags:

53 | Flag | Description |

54 | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

55 | `--name "My Project"` | Set a custom session title visible in the session list at claude.ai/code. |

56 | `--spawn <mode>` | How concurrent sessions are created. Press `w` at runtime to toggle.<br />• `same-dir` (default): all sessions share the current working directory, so they can conflict if editing the same files.<br />• `worktree`: each on-demand session gets its own [git worktree](/en/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees). Requires a git repository. |

57 | `--capacity <N>` | Maximum number of concurrent sessions. Default is 32. |

58 | `--verbose` | Show detailed connection and session logs. |

59 | `--sandbox` / `--no-sandbox` | Enable or disable [sandboxing](/en/sandboxing) for filesystem and network isolation. Off by default. |

60 </Tab>

62 <Tab title="Interactive session">

63 To start a normal interactive Claude Code session with Remote Control enabled, use the `--remote-control` flag (or `--rc`):

65 ```bash theme={null}

66 claude --remote-control

67 ```

69 Optionally pass a name for the session:

71 ```bash theme={null}

72 claude --remote-control "My Project"

73 ```

75 This gives you a full interactive session in your terminal that you can also control from claude.ai or the Claude app. Unlike `claude remote-control` (server mode), you can type messages locally while the session is also available remotely.

76 </Tab>

78 <Tab title="From an existing session">

79 If you're already in a Claude Code session and want to continue it remotely, use the `/remote-control` (or `/rc`) command:

81 ```text theme={null}

82 /remote-control

83 ```

85 Pass a name as an argument to set a custom session title:

87 ```text theme={null}

88 /remote-control My Project

89 ```

91 This starts a Remote Control session that carries over your current conversation history and displays a session URL and QR code you can use to [connect from another device](#connect-from-another-device). The `--verbose`, `--sandbox`, and `--no-sandbox` flags are not available with this command.

92 </Tab>

93</Tabs>

95### Connect from another device

97Once a Remote Control session is active, you have a few ways to connect from another device:

99* **Open the session URL** in any browser to go directly to the session on [claude.ai/code](https://claude.ai/code). Both `claude remote-control` and `/remote-control` display this URL in the terminal.

100* **Scan the QR code** shown alongside the session URL to open it directly in the Claude app. With `claude remote-control`, press spacebar to toggle the QR code display.

101* **Open [claude.ai/code](https://claude.ai/code) or the Claude app** and find the session by name in the session list. Remote Control sessions show a computer icon with a green status dot when online.

102

103The remote session title is chosen in this order:

104

1051. The name you passed to `--name`, `--remote-control`, or `/remote-control`

1062. The title you set with `/rename`

1073. The last meaningful message in existing conversation history

1084. Your first prompt once you send one

109

110If the environment already has an active session, you'll be asked whether to continue it or start a new one.

111

112If you don't have the Claude app yet, use the `/mobile` command inside Claude Code to display a download QR code for [iOS](https://apps.apple.com/us/app/claude-by-anthropic/id6473753684) or [Android](https://play.google.com/store/apps/details?id=com.anthropic.claude).

113

114### Enable Remote Control for all sessions

115

116By default, Remote Control only activates when you explicitly run `claude remote-control`, `claude --remote-control`, or `/remote-control`. To enable it automatically for every interactive session, run `/config` inside Claude Code and set **Enable Remote Control for all sessions** to `true`. Set it back to `false` to disable.

117

118With this setting on, each interactive Claude Code process registers one remote session. If you run multiple instances, each one gets its own environment and session. To run multiple concurrent sessions from a single process, use server mode with `--spawn` instead.

119

120## Connection and security

121

122Your local Claude Code session makes outbound HTTPS requests only and never opens inbound ports on your machine. When you start Remote Control, it registers with the Anthropic API and polls for work. When you connect from another device, the server routes messages between the web or mobile client and your local session over a streaming connection.

123

124All traffic travels through the Anthropic API over TLS, the same transport security as any Claude Code session. The connection uses multiple short-lived credentials, each scoped to a single purpose and expiring independently.

125

126## Remote Control vs Claude Code on the web

127

128Remote Control and [Claude Code on the web](/en/claude-code-on-the-web) both use the claude.ai/code interface. The key difference is where the session runs: Remote Control executes on your machine, so your local MCP servers, tools, and project configuration stay available. Claude Code on the web executes in Anthropic-managed cloud infrastructure.

129

130Use Remote Control when you're in the middle of local work and want to keep going from another device. Use Claude Code on the web when you want to kick off a task without any local setup, work on a repo you don't have cloned, or run multiple tasks in parallel.

131

132## Limitations

133

134* **One remote session per interactive process**: outside of server mode, each Claude Code instance supports one remote session at a time. Use server mode with `--spawn` to run multiple concurrent sessions from a single process.

135* **Terminal must stay open**: Remote Control runs as a local process. If you close the terminal or stop the `claude` process, the session ends. Run `claude remote-control` again to start a new one.

136* **Extended network outage**: if your machine is awake but unable to reach the network for more than roughly 10 minutes, the session times out and the process exits. Run `claude remote-control` again to start a new session.

137* **Ultraplan disconnects Remote Control**: starting an [ultraplan](/en/ultraplan) session disconnects any active Remote Control session because both features occupy the claude.ai/code interface and only one can be connected at a time.

138

139## Troubleshooting

140

141### "Remote Control requires a claude.ai subscription"

142

143You're not authenticated with a claude.ai account. Run `claude auth login` and choose the claude.ai option. If `ANTHROPIC_API_KEY` is set in your environment, unset it first.

144

145### "Remote Control requires a full-scope login token"

146

147You're authenticated with a long-lived token from `claude setup-token` or the `CLAUDE_CODE_OAUTH_TOKEN` environment variable. These tokens are limited to inference-only and cannot establish Remote Control sessions. Run `claude auth login` to authenticate with a full-scope session token instead.

148

149### "Unable to determine your organization for Remote Control eligibility"

150

151Your cached account information is stale or incomplete. Run `claude auth login` to refresh it.

152

153### "Remote Control is not yet enabled for your account"

154

155The eligibility check can fail with certain environment variables present:

156

157* `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` or `DISABLE_TELEMETRY`: unset them and try again.

158* `CLAUDE_CODE_USE_BEDROCK`, `CLAUDE_CODE_USE_VERTEX`, or `CLAUDE_CODE_USE_FOUNDRY`: Remote Control requires claude.ai authentication and does not work with third-party providers.

159

160If none of these are set, run `/logout` then `/login` to refresh.

161

162### "Remote Control is disabled by your organization's policy"

163

164This error has three distinct causes. Run `/status` first to see which login method and subscription you're using.

165

166* **You're authenticated with an API key or Console account**: Remote Control requires claude.ai OAuth. Run `/login` and choose the claude.ai option. If `ANTHROPIC_API_KEY` is set in your environment, unset it.

167* **Your Team or Enterprise admin hasn't enabled it**: Remote Control is off by default on these plans. An admin can enable it at [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code) by turning on the **Remote Control** toggle. This is a server-side organization setting, not a [managed settings](/en/permissions#managed-only-settings) key.

168* **The admin toggle is grayed out**: your organization has a data retention or compliance configuration that is incompatible with Remote Control. This cannot be changed from the admin panel. Contact Anthropic support to discuss options.

169

170### "Remote credentials fetch failed"

171

172Claude Code could not obtain a short-lived credential from the Anthropic API to establish the connection. Re-run with `--verbose` to see the full error:

173

174```bash theme={null}

175claude remote-control --verbose

176```

177

178Common causes:

179

180* Not signed in: run `claude` and use `/login` to authenticate with your claude.ai account. API key authentication is not supported for Remote Control.

181* Network or proxy issue: a firewall or proxy may be blocking the outbound HTTPS request. Remote Control requires access to the Anthropic API on port 443.

182* Session creation failed: if you also see `Session creation failed — see debug log`, the failure happened earlier in setup. Check that your subscription is active.

183

184## Choose the right approach

185

186Claude Code offers several ways to work when you're not at your terminal. They differ in what triggers the work, where Claude runs, and how much you need to set up.

187

189| :--------------------------------------------- | :--------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------ |

195

196## Related resources

197

198* [Claude Code on the web](/en/claude-code-on-the-web): run sessions in Anthropic-managed cloud environments instead of on your machine

199* [Ultraplan](/en/ultraplan): launch a cloud planning session from your terminal and review the plan in your browser

200* [Channels](/en/channels): forward Telegram, Discord, or iMessage into a session so Claude reacts to messages while you're away

201* [Dispatch](/en/desktop#sessions-from-dispatch): message a task from your phone and it can spawn a Desktop session to handle it

202* [Authentication](/en/authentication): set up `/login` and manage credentials for claude.ai

203* [CLI reference](/en/cli-reference): full list of flags and commands including `claude remote-control`

204* [Security](/en/security): how Remote Control sessions fit into the Claude Code security model

205* [Data usage](/en/data-usage): what data flows through the Anthropic API during local and remote sessions

remote-control.md Claude Code Docs, 2026-01-14 00:05 UTC → 2026-04-04 03:46 UTC