Claude Code Remote Control: Drive Local Sessions Remotely

I started a long migration on my laptop, closed the lid, and spent the next hour on a bus watching the same session tick through files on my phone — approving two permission prompts on the way. Nothing about that run had moved to the cloud. The laptop was still doing every byte of the work; the phone was a screen.

That distinction is the entire feature, and confusing it with Claude Code on the web leads to the wrong tool for the job in both directions. This post covers the three ways to start a Remote Control session, the flags that matter in server mode, the security model, the surprisingly long list of configurations that silently make it unavailable, and what actually works from a phone once you are connected.

It is a window onto a local process, not a cloud session

When you start Remote Control, Claude keeps running locally the entire time. Your filesystem, your MCP servers, your tools and your project configuration all stay available, and typing an at-sign on your phone autocompletes file paths from your local project. Claude Code on the web is the opposite: it executes in cloud infrastructure, which is what you want for a repo you have not cloned, and useless for the work already open on your desk.

The consequence is that the local process is load-bearing. Close the terminal, quit the editor, or stop the process any other way and the session goes offline within seconds. To keep one alive on a remote machine after you disconnect from SSH, start it inside tmux or screen — this is the single most common way people lose a session they thought was durable.

Three ways in, and only one of them serves more than one session

Server mode is the one worth learning properly. It keeps a process in your terminal waiting for connections, prints a session URL, and shows a QR code when you press the spacebar. It defaults to a capacity of 32 concurrent sessions, and the spawn mode decides whether those sessions fight over the same working directory or each get their own git worktree.

# Server mode — one process serving many sessions. Stays in
# your terminal, prints a session URL, spacebar shows a QR code.
claude remote-control --name "Porto rebuild" --capacity 8

#   --spawn same-dir   all sessions share the cwd (default)
#   --spawn worktree   each on-demand session gets its own git worktree
#   --spawn session    serve exactly ONE session, reject the rest
#   press w at runtime to toggle same-dir <-> worktree

# Interactive: a normal session you can also drive remotely.
claude --remote-control "Porto rebuild"     # or --rc

# Already mid-session? Carries the conversation history over.
/remote-control Porto rebuild               # or /rc

# Bring back sessions after Ctrl+C, for about four hours:
claude remote-control                       # all of them
claude remote-control --continue            # just the one it started with
claude remote-control --session-id abc123   # one by id

The other two modes serve exactly one remote session per process. Stopping a server with Ctrl+C does not archive its sessions — you have roughly four hours to bring them back from the same directory, after which you start fresh. Sessions started with the interactive flag or the slash command come back through the ordinary conversation resume path instead.

Auto-connect, and the asymmetry that makes it safe

Remote Control only activates when you ask for it, unless auto-connect is on. You can toggle it in config, in Desktop settings, in the VS Code command menu, or with a settings key — and the settings key behaves differently depending on which file it lives in, deliberately.

// ~/.claude/settings.json — connect every interactive session
// automatically. Note the deliberate asymmetry below.
{
  "remoteControlAtStartup": true
}

// In .claude/settings.json or .claude/settings.local.json,
// Claude Code honours a FALSE and ignores a TRUE — so a
// checked-in repo file can turn Remote Control OFF for a
// repository but can never turn it ON for everyone who
// clones it. The asymmetry is the whole security property.

// To remove the capability entirely:
{
  "disableRemoteControl": true
}

The security model, stated plainly

Your local session makes outbound HTTPS requests only and never opens an inbound port on your machine. 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. All of it is TLS over the same transport as any other Claude Code session, using multiple short-lived credentials each scoped to one purpose and expiring independently.

Organisations on Team and Enterprise can go further with Trusted Devices, currently in beta and off until an Owner enables it. It ties Remote Control access to an enrolled device and a sign-in no more than eighteen hours old, refreshed with Face ID, Touch ID, Windows Hello or a passkey. The biometric check runs on the device through the operating system or browser, and Anthropic stores only the device's public key and basic metadata — never fingerprint or face data.

The configurations that make it silently unavailable

This is where I lost an afternoon. Remote Control is not available on Bedrock, Google Cloud's Agent Platform or Microsoft Foundry, it needs subscription authentication rather than an API key, and it refuses if you point the base URL at anything other than the Anthropic API — including your own LLM gateway or proxy. Less obviously, four separate privacy environment variables each disable the feature-flag evaluation that availability depends on, so a session that has one of them set fails in a way that looks like a bug rather than a policy.

# Remote Control silently refuses in more configurations
# than people expect. Each of these is a hard "not available":

ANTHROPIC_BASE_URL=https://gateway.internal   # any host that is
                                              # not api.anthropic.com

# Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry
# An enterprise Claude apps gateway sign-in
# API keys — subscription auth only (Pro, Max, Team, Enterprise)

# And these four each disable the feature-flag evaluation that
# Remote Control availability depends on:
DISABLE_TELEMETRY=1
DO_NOT_TRACK=1
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
DISABLE_GROWTHBOOK=1

# Unset them wherever they are set — shell OR the env block of
# a settings.json file — or the failure looks like a bug.

What a phone can actually do

Once connected, a device shows the conversation as it happens, including compaction progress and the point where the conversation was compacted. You can attach photos and files, which Claude sees directly or downloads to your machine and passes as file references. Commands split into three groups, and knowing which is which saves a lot of typing into a phone that will not answer:

• Text-output commands work everywhere — compact, clear, context, usage, recap, reload-plugins and exit.
• Model, effort, fast, colour and rename work if you pass the value as an argument, because the phone has no picker or slider to open.
• Terminal-only commands such as plugin and resume never work remotely, argument or not.

Choosing between Remote Control and Claude Code on the web

Both surfaces are the same claude.ai interface, which is exactly why people pick the wrong one. The only question that matters is where the session runs, and everything else follows from it.

Four questions that settle it:

Use Remote Control when the work is already local and you want to keep steering it from somewhere else; use the web when you want to start something without any local setup at all. The rule I now follow is to start anything I might want to leave running inside tmux, because the one failure this feature cannot recover from is the terminal window I closed without thinking.