Claude Code remote: leaving a session running on the Mac at home

A long task is running in a terminal on the Mac at home. The train leaves in ten minutes. The question is not whether a model can keep working, it is whether the session on that machine can be reached from a phone without leaving the terminal logged in to a VNC window all afternoon. Searching for claude code remote lands on a feature called Remote Control, and the useful part is knowing exactly which piece runs where, because that single fact decides what breaks when the laptop lid closes.

What Remote Control actually connects

Remote Control links claude.ai/code, or the Claude app for iOS and Android, to a Claude Code session that is already running on a specific machine. The process stays on that machine for the whole session. Filesystem access and command execution never move. The browser and the phone are windows into a local session, not a second copy of it.

That distinction is the whole feature. Local MCP servers stay available. Project configuration stays available. Typing the at sign in the phone app autocompletes file paths from the local project, because the path list is coming off the disk of the machine at home. A cloud session, which uses the same claude.ai/code interface, runs somewhere else entirely and has none of that.

Both surfaces stay live at once. A message typed in the terminal, a message typed in the browser, and a message typed on the phone all land in the same conversation, and subagent progress stays in sync across every connected device. Files and photos attached from the phone are handled two ways: Claude reads attached photos directly as part of the message, and other file types are downloaded to the local machine first and passed in as file references.

The session belongs to the machine, not to the account. Everything awkward about Remote Control follows from that, and so does everything useful.

Requirements, and the configurations that rule it out

Remote Control is available on the Pro, Max, Team, and Enterprise plans. API keys are not supported as an authentication method for it. On Team and Enterprise, the toggle is off until an Owner turns it on in the Claude Code admin settings, so an individual developer on a company plan cannot enable it alone.

Several setups exclude it outright. It does not work when Claude Code is pointed at Amazon Bedrock, Google Cloud's Agent Platform, or Microsoft Foundry. It does not work when the ANTHROPIC_BASE_URL environment variable points at a gateway or proxy rather than api.anthropic.com, so a shared company proxy has to be unset for the session that needs Remote Control. Signing in through an enterprise Claude apps gateway also rules it out, and organizations under Zero Data Retention requirements cannot enable it at all.

Two smaller preconditions cause most of the first-run confusion. Authentication has to go through claude.ai with /login, not an API key. And the project directory has to have been trusted once already, by running claude there and accepting the workspace trust dialog, because that dialog never saves trust for a home directory. Starting Remote Control from a real project directory rather than from the home folder avoids the whole class of problem.

For anyone who wants it off permanently on a machine, there is a disableRemoteControl setting rather than a habit to maintain.

Starting a session, and the two shapes it can take

There are two useful shapes, and picking the wrong one is the most common reason a session is not there later.

Server mode is claude remote-control, run inside the project directory. The first run explains what the feature does and asks for confirmation before starting. After that the process sits in the terminal waiting for connections, printing a session URL and connection status. Pressing the space bar shows a QR code, which is the fastest path from a Mac at a desk to a phone in a pocket. Useful flags include --name to give the session a title that is readable in the session list, --continue to bring back the session the last server in that directory started with, and --spawn worktree so that on-demand sessions each get their own git worktree instead of sharing one working directory.

The interactive shape is an ordinary Claude Code session that happens to be reachable, started with claude --remote-control or by running /remote-control inside a session that is already open. The Desktop app and the VS Code extension use the same slash command.

The difference that matters: an interactive process supports one remote session at a time, while server mode can serve several concurrently. Server mode also recovers better. If a session it serves crashes, sending a message from a connected device brings it back without restarting the server.

Keeping the Mac at home reachable

Remote Control is a local process, so the failure modes are the failure modes of a local process.

Closing the terminal window, quitting the Desktop app, or quitting VS Code stops the process, and unless Claude is mid-task the session shows as offline on the phone within seconds. Nothing is lost, but nothing is running either. The fix for a machine driven over SSH is to start the session inside tmux or screen, so that disconnecting the SSH session does not take the process with it. This is the single most valuable habit for the leave-it-running-at-home case.

Network interruptions are handled differently depending on the shape chosen above. An interactive session keeps retrying for as long as the outage lasts and reconnects on its own. A server started with claude remote-control gives up after roughly ten minutes of an unreachable network and exits, which then needs the command run again. There is also a quieter failure where the rest of the connection is fine but presence heartbeats keep failing. Claude Code re-registers for about thirty minutes before disconnecting, and the way back is /remote-control.

Sleep is more forgiving than it sounds. A laptop that sleeps or a network that drops does not end the session. Claude Code reconnects when the machine comes back online, and queues messages, permission prompts, and status updates in the meantime rather than dropping them. What does not survive is the process being killed, which is why the terminal it lives in matters more than the network does.

Push notifications are worth turning on for this pattern, because the whole point is not watching. While Remote Control is active Claude decides when to send one, typically when a long task finishes or when a decision is needed to continue, and asking for a push in the prompt itself works too. Beyond on and off there is no per-event configuration.

What the phone can actually steer

Steering from a phone is narrower than the terminal, and knowing the edges prevents a wasted train ride.

Permission prompts and clarifying questions stay open until answered, so a task that stops for approval will still be waiting. Other forwarded dialogs behave differently: by default Claude Code waits five minutes, then closes the dialog and continues with its no-action default. That deadline is adjustable through a dialogExpiry setting, and it is the thing to check when a remote answer arrives too late to matter.

Some commands are local-only regardless of arguments, including plugin management and session resumption. A useful set does work from mobile and web: compacting and clearing context, checking context and usage, recap, and exit. Commands that normally open a picker take the value as an argument instead, so choosing a model or an effort level means typing the value rather than scrolling a list. Server status for MCP works from the phone as a text summary, and reconnecting a failed server works from both surfaces.

Aspect	Remote Control	Cloud session
Where code runs	The machine that started it	Cloud infrastructure
Local MCP servers and project config	Available	Not available
Needs local setup first	Yes	No
Survives the local process being quit	No	Yes
Good for	Steering work already in progress	Starting fresh without local setup

Read that table as a choice about state, not about power. Work that depends on a half-finished local branch, a running dev server, or a folder of files that only exist on that Mac belongs in Remote Control. Work on a repository that is not even cloned locally belongs in a cloud session.

Who is allowed to connect

While a session is connected, the transcript, including messages, responses, and tool activity, is stored on Anthropic servers. That is what keeps the conversation in sync across devices and what allows a reconnect after a drop. Execution and filesystem access stay on the machine. For anyone weighing this, the line to hold on to is that the transcript travels and the files do not.

The connection itself is outbound only. The local session makes outbound HTTPS requests, registers with the API, and polls for work. No inbound port is opened on the machine, which is why this works from behind a home router without any port forwarding at all.

For tighter control there is a Trusted Devices setting, currently in beta, available on Pro, Max, Team, and Enterprise and off by default. With it on, viewing or steering a Remote Control session requires both an enrolled device and a sign-in no more than eighteen hours old. Rather than signing in daily, the step-up is a Face ID, Touch ID, Windows Hello, or passkey prompt, and the biometric check runs on the device through the operating system or browser. Enrolled devices are listed and revocable from the account settings page, and the setting applies only to Remote Control, leaving ordinary chat and terminal use untouched.

Where this leaves the folder problem

Remote Control solves reaching a session. It does not solve the shape of the work on the machine itself, and for file-heavy tasks that is usually the bigger cost. A cleanup or a rename pass still means a folder in one window, a shell in another, and an assistant in a third, with paths and listings carried between them by hand. Remote Control forwards that arrangement to a phone rather than simplifying it.

The part worth noticing is which half of the work is genuinely mobile. Answering a permission prompt, reading a diff, and saying continue all work on a small screen. Choosing which two hundred files to move does not. A file manager with a built-in terminal removes the transfers on the desk side, and what that looks like in practice is set out on the Features page, while the question of what is realistic to do from a phone at all is covered on the From iPhone and iPad page.

What to change first

Start the next long-running session with claude remote-control from inside a project directory, wrapped in tmux, and scan the QR code once so the phone is already paired before it is needed. If the tasks being steered remotely turn out to be mostly file work rather than code work, that is a signal about the desk setup rather than the remote one, and the Atriens comparison page is where that side-by-side lives.