claude remote-control Server Mode: Run Claude Code as a Session Server

People searching for a “claude code server” usually mean one of two things: a Claude Code process that keeps running on a machine so they can drive it from somewhere else, or a way to start several sessions on that machine without opening several terminals. Both are the same feature. claude remote-control, with no other flags, starts Claude Code in server mode: a process that sits in your terminal, registers with Anthropic, and serves sessions to claude.ai/code and the Claude mobile app until you stop it. This post is about that mode specifically, as the Remote Control documentation describes it in late October 2026: how it differs from running /remote-control inside a normal session, the spawn modes, how to bring sessions back after you stop the server, and the knobs for permissions, Chrome and debugging.

If you have not used Remote Control at all yet, start with our Remote Control guide; this post assumes you know what the session list at claude.ai/code is.

Three ways to start Remote Control, and why server mode is different

The CLI gives you three invocations. claude --remote-control (or --rc) starts a normal interactive session that is also reachable from your phone; you can keep typing in the terminal while it is connected. /remote-control (or /rc) does the same from inside a session you already have open, carrying the conversation history with it. And claude remote-control, the subcommand, is the server.

# interactive session, also reachable remotely
claude --remote-control "My Project"

# from inside a running session
/remote-control My Project

# server mode: no local prompt, serves sessions to your devices
claude remote-control --name "My Project"

The docs draw the line plainly: unlike the server, an interactive session lets you type messages locally. The server has no local prompt. It prints a session URL, shows a QR code when you press the spacebar, and then displays connection status and tool activity while remote devices work. Outside server mode, each Claude Code process supports one remote session at a time; the server is the way to run multiple concurrent sessions from a single process. The first time you run it, it explains what it does and asks Enable Remote Control? (y/n); decline and it exits and asks again next time. In a directory you have not trusted yet, it also asks Trust <directory>? [y/N] before starting, and if its input is not a terminal it cannot ask and exits with a workspace-not-trusted error.

Spawn modes: same-dir, worktree, session

The flag that decides what kind of server you get is --spawn. It has three values.

While the server runs in same-dir or worktree mode, pressing w in its terminal switches to the other one, and the mode you switch to becomes the saved default for that project. That is why a later start may print Spawn mode: worktree (saved for this folder; press w to change): the server is honouring a choice you made earlier, either by answering its Spawn mode for this project: question (1 for same-dir, 2 for worktree) or by pressing w during a previous run. --spawn <mode> overrides it for one run. The default ceiling is 32 concurrent sessions; change it with --capacity <N>.

# isolated parallel sessions, each in its own worktree, up to 8 at once
claude remote-control --spawn worktree --capacity 8

# one session only, nothing else may connect
claude remote-control --spawn session

By default the server also pre-creates one session in the current directory so you have somewhere to type immediately; in worktree mode that first session stays in the directory while on-demand ones get worktrees. --no-create-session-in-dir starts with none, with a consequence that matters later: the server then archives its sessions when you stop it, so there is nothing to resume.

Permissions, Chrome, naming and debugging

--permission-mode <mode> sets the starting permission mode for every session the server creates, for example acceptEdits; manual is accepted as an alias for default, and an unrecognised mode stops the server at startup and lists the valid ones. This is the setting people reach for when the point of the server is to hand tasks to it from a phone and not be asked about every file edit; our post on turning auto mode off again covers the other direction.

--chrome and --no-chrome (v2.1.273 or later) decide whether the sessions the server creates can use Chrome on your machine while you work from another device. Without either flag, the pre-created session and any session you start yourself from claude.ai/code or the app begin with Chrome off, even if you enabled Chrome by default elsewhere; a session the server starts for one of your project threads follows that setting instead, except in bypassPermissions mode.

--name "My Project" sets the title shown in the session list. Without it, names are auto-generated as <hostname>-graceful-unicorn, and --remote-control-session-name-prefix (or the CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX variable) replaces the hostname part, which is useful when several machines serve sessions into the same account. For diagnosing a server that will not connect, -d / --debug (v2.1.282+, filter only in the --debug=api,hooks form), --debug-file <path> and --verbose are there; claude remote-control --help prints the full flag list (before v2.1.302 it returned a sign-in error instead when you were not logged in).

Two things do not work the way you might expect. --sandbox and --no-sandbox were removed in v2.1.300 and now make the server exit with an error; to sandbox the sessions it starts, turn sandboxing on in a settings file. And a global claude flag placed before remote-control is not carried into the sessions the server creates: harmless ones such as --verbose or --model are let through, but anything that would change what sessions can do, such as --settings, makes the server refuse to start and name the flag.

Stopping the server and bringing sessions back

Ctrl+C stops the server, and the sessions it was serving stop responding from your phone or browser. They are not archived, as long as you were not running a second server in the same directory and did not start with --no-create-session-in-dir. For about four hours afterwards, three commands in the same directory bring them back:

# bring back every session the server was serving
claude remote-control

# only the session the server started with; exits when it ends
claude remote-control --continue

# one specific session; the ID is the part of the claude.ai/code URL
# between /code/ and any ?
claude remote-control --session-id <id>

--continue and --session-id need v2.1.200 or later, cannot be combined with each other or with --spawn, --capacity or --create-session-in-dir, and on v2.1.228 or later they unarchive a session you archived in the meantime. If the directory has no record, --continue falls back to the newest one from the repository's other worktrees. After the four hours, run a plain claude remote-control to start fresh. Sessions you started with claude --remote-control or /remote-control are different: those come back with claude --continue or claude --resume, like any conversation.

A crash is handled without a restart: if a session served by the server crashes, send it a message from a connected device and Claude Code serves it again (v2.1.238+). A network outage is not. In server mode, if the machine is awake but cannot reach the network, the process gives up after roughly ten minutes and exits, and you run claude remote-control again; an interactive session, by contrast, keeps retrying for the whole outage. Once a session is connected, HTTP 403 refusals (typical after a VPN change) are retried for up to three minutes before Claude Code disconnects and names what refused.

Running it on a remote machine

The server is a local process; close the terminal and it is gone. On a box you reach over SSH, the docs' own advice is to start it inside tmux or screen so it survives the SSH session ending:

ssh dev-box
tmux new -s claude
cd ~/repo
claude remote-control --spawn worktree --name "dev-box repo"
# Ctrl+B D to detach; the server keeps serving

Networking is outbound only. The session registers with the Anthropic API over HTTPS and polls for work; no inbound port is opened, which is what makes this workable behind a home router or a corporate NAT. The trade-off is that, while connected, the transcript (your messages, Claude's responses and tool activity) is stored on Anthropic servers to keep devices in sync and allow reconnects; execution and filesystem access stay on the machine. Organisations with Zero Data Retention or the HIPAA configuration cannot enable Remote Control at all, and it needs a Pro, Max, Team or Enterprise login (API keys, Bedrock, Foundry, the Agent Platform and a custom ANTHROPIC_BASE_URL are out). On Team and Enterprise an Owner has to switch the Remote Control toggle on in the Claude Code admin settings first. If your shell sets CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC or DISABLE_GROWTHBOOK, Remote Control is unavailable until you unset them.

One more thing a headless box needs: notifications. The server shows tool activity in its own terminal, which nobody is looking at. Turn on mobile push in /config (Push when Claude decides, Push when actions required), and for the tmux case see notifications over tmux and SSH.

Server mode versus the alternatives

The docs line up the ways to work away from the terminal, and it helps to know which one you are asking for. Server mode runs on your machine and is for steering work from another device; a cloud session runs on Anthropic-managed infrastructure and needs no local setup, which is better for a repo you have not cloned or for many parallel tasks. Channels push events into a local CLI session from Telegram, Discord or your own server, for reacting to CI failures rather than typing prompts. Dispatch sends a task from the mobile app to the Desktop app with minimal setup. And if you only want to background one session in your own terminal, that is the claude --bg agent view, not Remote Control at all. Pick server mode when the sentence is “I want this machine to keep serving Claude sessions, several at once, that I drive from my phone or browser.”

A sensible first configuration

• Run it in a git repository with --spawn worktree, so a second task started from your phone cannot trample the first.
• Give it a --name; auto-generated names are fine for one machine and confusing for three.
• Leave the permission mode at the default until you have seen what the sessions ask for, then consider --permission-mode acceptEdits rather than anything broader.
• Add --chrome only if the tasks need the browser; otherwise sessions start with it off anyway.
• On a remote box, wrap it in tmux, and plan for the ten-minute network give-up by checking the session list the next morning.
• When you stop it, remember the four-hour window for --continue; after that it is a fresh server.

To end a session rather than the server, our guide to stopping a running Claude Code task covers stopping subagents from a connected device, which the server then stops on the machine.