Skillforge Field notes on shipping with AI tools

Claude Code Remote Control Server Mode: Flags and Limits

claude-coderemote-control

claude remote-control turns one terminal on your machine into a server that claude.ai/code or the Claude mobile app can attach to. Claude and its tools keep running on your computer, and the web or phone client only shows the session. This page covers the server-mode flags that decide how sessions are created, how long you have to resume them, and one flag whose documentation and behavior currently disagree.

Verified against: the Remote Control and errors pages on code.claude.com fetched 2026-11-12, the GitHub changelog for 2.1.321, and claude remote-control --help plus two failing invocations run on Claude Code 2.1.322 on 2026-11-12. We did not connect a phone or browser to a live server: Remote Control is refused inside the cloud session we ran in (Error: Remote Control is not available inside a cloud session.), so session behavior below is as documented, not observed.

Requirements that catch people out

From the documentation:

  • A claude.ai plan (Pro, Max, Ultra, Team or Enterprise). API keys are not supported.
  • Not available on Bedrock, Google Cloud's Agent Platform or Microsoft Foundry, and not when ANTHROPIC_BASE_URL points anywhere other than api.anthropic.com.
  • Unavailable if CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC or CLAUDE_CODE_DISABLE_FEATURE_FLAGS is set. DISABLE_TELEMETRY and DO_NOT_TRACK alone are allowed from 2.1.283 (2.1.304 in the Desktop app), unless your organization requires Trusted Devices.
  • An untrusted directory prompts Trust <directory>? [y/N]. With no terminal on stdin or stdout the command cannot ask and exits with a Workspace not trusted error, so trust the folder once interactively before you script it.

Start it

cd ~/projects/my-repo
claude remote-control --name "my-repo" --spawn worktree --capacity 4

claude rc is an alias. Press the spacebar in the server terminal for a QR code. Traffic is outbound HTTPS only; the docs say it never opens an inbound port.

Spawn modes

| --spawn | What it does | | - | - | | same-dir (default when no mode is saved) | Every session shares the working directory, so two sessions can edit the same files. | | worktree | Each on-demand session gets its own git worktree. Needs a git repository or a WorktreeCreate hook. | | session | Serves exactly one session and rejects further connections. Set at startup only. |

Two details worth knowing. Press w in the server terminal to toggle between same-dir and worktree, and the mode you switch to is saved as the default for that project, even if you started the run with an explicit --spawn. And --capacity <N> (default 32) cannot be combined with --spawn session. Both appear in --help as well as the docs.

With worktree mode the pre-created session (on by default, --no-create-session-in-dir turns it off) stays in the current directory, and only sessions you start on demand get isolated worktrees.

Resume after Ctrl+C

Stopping the server stops the sessions responding, but they are not archived, with two exceptions: you ran another claude remote-control in the same directory, or you started with --no-create-session-in-dir. In the same directory:

  • claude remote-control brings back every session the server was serving.
  • claude remote-control --continue brings back only the session it started with.
  • claude remote-control --session-id <id> brings back one session. The ID is the part of the claude.ai/code URL between /code/ and any ?.

The documented window is about four hours after the server stopped. --help agrees ("within roughly the last 4 hours"). --continue and --session-id cannot be combined with the spawn flags or --capacity.

The --settings flag: docs and binary disagree

The changelog for 2.1.321 says: "Added --settings <file> to claude remote-control, which applies a settings file to every session it starts." The 2.1.322 --help lists it:

--settings <file>   JSON settings file for spawned sessions.
                    Read once, at start: if it changes, no session
                    starts until you restart Remote Control. Keep
                    it where sessions can't write.

The same help text says that with it, sessions started from a project do not get auto-compact, or auto mode ahead of this computer's own settings, which Remote Control otherwise turns on for them. We did not test what that means in practice.

The Remote Control page we fetched on 2026-11-12 only mentions --settings as an example of a global flag that makes Claude Code refuse to start. That is true only for the flag placed before the verb. We ran both forms on 2.1.322:

claude --settings s.json remote-control
# Error: `--settings` before `remote-control` is not carried over to the sessions
# Remote Control starts, so Remote Control refuses to start rather than drop it ...
# Pass settings with `claude remote-control --settings <file>`.   (exit 1)

claude remote-control --settings s.json
# Error: Remote Control is not available inside a cloud session.  (exit 1)

The first shows the new error message already points you at the right form. The second only proves the flag is accepted and parsed (it got as far as the cloud-session check); it does not prove the settings are applied. Put --settings after remote-control. The Remote Control page's flag table does not list it yet, and its paragraph on --settings only describes the before-the-verb case, so expect that page to change.

Because the file is read once and sessions can write to places they can reach, keep it somewhere read-only to them, as the help text says.

Failure behavior to plan around

  • If a served session crashes, send it a message from a connected device and it is served again (2.1.238 or later). You do not restart the server.
  • If the machine is awake but offline, server mode gives up after roughly 10 minutes and the process exits. An interactive session keeps retrying instead. For unattended use, wrap the server in a supervisor that restarts it.
  • Closing the terminal ends the session. On a remote machine, run it inside tmux or screen.
  • The transcript is stored on Anthropic servers while connected. Organizations with Zero Data Retention or the HIPAA configuration cannot enable Remote Control, and disableRemoteControl turns it off.

FAQ

Can I run several sessions from one process? Yes, in server mode: up to --capacity concurrent sessions, 32 by default. Outside server mode each interactive process supports one remote session.

Does --sandbox work? No. Both --sandbox and --no-sandbox were removed in 2.1.300 and now exit with an error. Turn on sandboxing in a settings file instead, which is a use for the --settings flag above (we did not test that combination).

Can I use it with an API key? No, per the documentation. It needs a claude.ai login.