How do I use `--settings <file>` with `claude remote-control`?

Added --settings <file> to claude remote-control, which applies a settings file to every session it starts. Requires Claude Code v2.1.321 or later. The flag takes a path to a JSON settings file, and that file applies to every session the server starts.

This site is independent and not affiliated with Anthropic. We read Anthropic's changelog, Remote Control page and settings page on 2026-11-14. We did not run the command, so nothing below is a hands-on result, and we show no sample output.

What 2.1.321 added

Claude Code changelog, 2.1.321:

Added --settings <file> to claude remote-control, which applies a settings file to every session it starts; if the file changes, no new session starts until you restart claude remote-control

The Remote Control page lists the flag in its table of server options. Its description says it will "Apply a JSON settings file to the server's sessions". It adds: "Give a file path, not a JSON string." And it ends: "Requires Claude Code v2.1.321 or later."

Remote Control is the feature that lets you steer a Claude Code session running on your machine from claude.ai/code or the Claude app. Server mode is the form you start with claude remote-control, and the page says claude rc is an alias.

Put the flag after remote-control

Order matters here, and the page spells it out. Flags you type before the subcommand do not travel:

If you pass a global claude flag before remote-control, or a wrapper script adds one, Claude Code doesn't carry the flag over to the sessions the server creates.

The same paragraph gives the rule for settings files: "To pass a settings file, put --settings after remote-control." So claude --settings x.json remote-control is the wrong shape. The page says some flags, such as --verbose or --model, still start the server, but any other flag stops it from starting.

Write the file and start the server

Anthropic's settings page warns about the format: "Settings files are strict JSON: a // comment or a trailing comma is a syntax error". A file that parses is the first thing to check.

For the contents, we borrowed the example from that same page. It lets Claude run your lint and test commands without asking and stops it reading .env files:

{
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)"
    ]
  }
}

Our own file name and the command line above are adaptations of the documentation, not something we ran. For the rule syntax, our guide to Claude Code permissions goes through allow, ask and deny.

The Claude moves worth stealing, by email

Workflows tested on real jobs, sent only when they are worth it. Free.

Subscribe

Where the file ranks

The Remote Control page gives the file the same precedence as claude --settings. The settings page describes where that sits: "Claude Code applies it above your user, project, and local files and below managed settings."

For a key you set in the file, the page says: "A key you set there overrides the same key in your project and user settings files, and a key you leave out keeps its value from those files."

Two practical results follow:

• Your ~/.claude/settings.json still applies for every key your file does not mention.
• A managed key wins. The page puts it plainly: "Nothing in your own settings files or --settings overrides a managed key".

If your organization deploys managed settings, our managed settings guide explains what sits above you.

Sandboxing now goes through a file

The Remote Control page says the --sandbox and --no-sandbox flags were "Removed in v2.1.300." If you pass either one, the server exits with an error instead of starting. The page tells you to turn on sandboxing in a settings file instead.

That is a natural use for the new flag. A settings file passed with --settings after remote-control reaches every session the server starts, so one file can cover all of them. We did not test that sandboxing setup, so read the page before you rely on it. Our notes on Claude Code 2.1.299 and 2.1.300 mention the same removal.

Changing the file later

The changelog line carries a catch: "if the file changes, no new session starts until you restart claude remote-control". Edit the file, then restart the server, or new sessions will not begin.

The changelog does not say what happens to sessions that are already running, so we will not guess. Restarting is the safe habit. If you stop the server with Ctrl+C, the Remote Control page describes how to bring the sessions back: run claude remote-control again in the same directory.

What came after: exit status 4 and 69

Claude Code 2.1.325, released on November 13, 2026, changed how the server exits. The changelog says:

Improved claude remote-control: it now exits with status 4 when it stops by itself (single-session runs still exit 0) and 69 when it can't register, so a service manager can start it again

That matters if you run the server under a service manager and give it a settings file. Our reading: status 4 and status 69 are the cases where a restart makes sense. We have not set up a service manager with it, so we cannot show a working configuration.

Where this does not help

• We did not run it. We have no output to show. We cannot confirm how a bad settings file is reported, because the pages we read do not say.
• Plans are limited. The Remote Control page says it is "available on Pro, Max, Ultra, Team, and Enterprise plans. API keys are not supported."
• Managed settings win. If your organization sets a key, your file cannot change it.
• It is a start-time file. The flag applies when the server starts. To change a setting, you restart the server.
• Older versions lack it. The documentation says the flag requires Claude Code 2.1.321 or later.

If you want to see every option for the subcommand in your terminal, the page says to run claude remote-control --help.

Can I put --settings before remote-control?

No. Anthropic's Remote Control page says a global flag typed before remote-control is not carried over to the sessions the server creates. For a settings file, it says to put --settings after remote-control.

Can I pass inline JSON to claude remote-control --settings?

The Remote Control page says "Give a file path, not a JSON string." That differs from the general --settings flag on the settings page, which accepts inline JSON or a path. For the server, write a file and pass its path.

What exit codes does claude remote-control use?

From 2.1.325, per the changelog: status 4 when the server stops by itself, status 0 for single-session runs that stop by themselves, and status 69 when it cannot register. The changelog says this lets a service manager start it again.

Sources (checked 2026-11-14)

• Claude Code changelog: the 2.1.321 entry (November 9, 2026) and the 2.1.325 entry (November 13, 2026).
• Remote Control: server mode flags, plans, and the rule for global flags.
• Settings files and precedence: the command line level and the strict JSON warning.

If you want a note when Anthropic documents more server options, the newsletter will carry it. If your login runs out during a long Remote Control session, see our guide to checking login expiry.