Deploy managed settings

Managed settings are the configuration an organisation pushes to developer machines. They sit above every other layer: nothing in a user file, project file, local file or --settings flag overrides them, apart from a short list of security-sensitive keys where a stricter lower value is still honoured (see settings).

This page is for the person deploying that policy, or the person trying to work out why it is not taking effect. If you have not yet decided what to enforce, start at organisation setup. For the console-based route, see server-managed settings.

The fastest route: one file

If you just want a policy on a handful of machines, drop a file in place.

1. Write the policy. It uses exactly the same JSON shape as settings.json. This example keeps Claude away from a credentials folder and a local database dump, removes bypass mode, and means only managed permission rules count:

{
  "permissions": {
    "deny": [
      "Read(./config/credentials/**)",
      "Read(./*.sqlite)"
    ],
    "disableBypassPermissionsMode": "disable"
  },
  "allowManagedPermissionRulesOnly": true
}

The settings reference says, per key, whether a managed source may set it, and settings examples has a fuller organisational file.

2. Place it. Save as managed-settings.json in the system directory:

The old Windows location under C:\ProgramData\ClaudeCode is no longer read.

3. Check it. On one machine, run /status. The Setting sources line should include Enterprise managed settings (file). Only then roll out to everyone.

Choosing a delivery mechanism

The file is one of four channels. They all carry the same keys; what differs is how you push them and how often Claude Code looks.

The MDM and file channels together are called endpoint-managed settings, because the policy lives on the device. Anthropic publishes starter templates for Jamf, Iru, Intune and Group Policy in the examples/mdm folder of the anthropics/claude-code GitHub repository.

How each channel stores the policy:

• Server-managed: held remotely; a local cache is applied at startup and replaced on each successful fetch.
• macOS profile: the com.anthropic.claudecode managed preferences domain. Top-level keys match the JSON, nested objects become dictionaries and lists become arrays.
• Windows HKLM / HKCU: the JSON as a string (REG_SZ or REG_EXPAND_SZ) in a value named Settings under SOFTWARE\Policies\ClaudeCode.
• File: managed-settings.json, an optional managed-settings.d/ folder, and managed-mcp.json, all in the system directory.

Every channel applies one policy to everyone it reaches. Different groups need different files or profiles. The claude.ai console cannot target groups yet; a Claude apps gateway can deliver per IdP group.

A handful of keys are tied to particular sources: the delivery controls policyHelper, wslInheritsWindowsSettings and managedSourcesBehavior, and the gateway login keys forceLoginGatewayUrl, gatewayInternalNetworks and the "gateway" value of forceLoginMethod.

Splitting a file policy between teams

If security, platform and data teams each own a slice of policy, give each a drop-in file in managed-settings.d/ rather than fighting over one file. Claude Code reads managed-settings.json first, then every *.json in the folder alphabetically, skipping hidden files. Prefix with numbers to control order:

/etc/claude-code/
  managed-settings.json
  managed-settings.d/
    10-platform.json
    20-security.json
    30-data-team.json

When two files set the same key:

Which sessions see the policy

• Local surfaces. The terminal, VS Code and JetBrains extensions, the desktop app's Code tab and Agent SDK sessions all read every channel. SDK sessions load managed settings even if settingSources leaves out user, project and local.
• Anthropic-hosted cloud sessions cannot see a device's file or MDM profile, so their policy must come from server-managed settings. Sessions in self-hosted environments also read the file in their runner image, by default only when server-managed settings supply no policy key.
• Claude Tag sessions do not get server-managed settings, though in self-hosted environments they read the runner image's file.
• Cowork (in Claude Desktop) never fetches server-managed settings from the admin console. On the user's machine it reads the local MDM policy and file. Inside a full VM sandbox (requireCoworkFullVmSandbox) or in remote Cowork, there is no device policy to read. claude.ai does still enforce the console's strictKnownMarketplaces and blockedMarketplaces when anyone adds a marketplace from claude.ai or Cowork's Customize.
• Running sessions pick up most changes on the schedule above without restarting. Exceptions that wait for the next start: forceRemoteSettingsRefresh, requiredMinimumVersion, a new or changed policyHelper, and some user-editable keys. Server-managed changes that need approval (hooks, certain env variables) wait for the developer to accept a dialog in interactive sessions.
• Very long sessions can lag a rollout. requiredMinimumVersion stops an old binary starting; it does not kill one already running.

How Claude Code combines several managed sources

If a machine receives policy from more than one channel, managedSourcesBehavior decides what happens:

• "first-wins" (default): use the highest-ranked source that contains at least one policy key, and ignore the rest. No warning is shown, but /status lists what was skipped.
• "merge" (v2.1.242+): apply every admin source that has a policy key, combined by kind of key.

The ranking, highest first:

1. Remote: server-managed settings from claude.ai or a gateway. Only fetched when the session talks to Anthropic's API directly with an eligible login, or signs into a gateway. On other providers, or with ANTHROPIC_BASE_URL pointing elsewhere, Claude Code starts at step 2.
2. OS policy: the macOS profile or the HKLM key.
3. Files: managed-settings.json plus managed-settings.d/*.json, merged.
4. HKCU on Windows (and on WSL when inheritance is turned on and the HKCU value also sets it).

Two definitions matter here. A policy key is any key other than the control keys wslInheritsWindowsSettings and managedSourcesBehavior; a source carrying only those is passed over. An admin source is one of the first three; HKCU is user-writable so it never counts.

HKCU is never used if an admin document is present above it. A document is present when it sets any policy key to a non-null value (even an unreadable value), or when an HKLM value, file or drop-in folder exists but cannot be read.

Keys read from every admin source

Even under "first-wins", a few keys are gathered from all admin sources (HKCU excluded), so a lower MDM profile or file can still supply them:

• The sandbox locks sandbox.network.allowManagedDomainsOnly and sandbox.filesystem.allowManagedReadPathsOnly. A true anywhere switches the lock on, and while it is on the locked allowlists (domains plus WebFetch(domain:...) rules, or filesystem.allowRead) are unioned across admin sources.
• allowManagedMcpServersOnly (v2.1.273+). A true anywhere turns the MCP allowlist lock on; the allowedMcpServers list then comes from the highest admin source that sets one, with a server-managed list replacing lower lists.
• deniedMcpServers and disableClaudeAiConnectors (v2.1.273+), and allowAllClaudeAiMcps.
• Sandbox binaries and switches: sandbox.bwrapPath, sandbox.socatPath, sandbox.ripgrep, sandbox.filesystem.disabled, sandbox.network.strictAllowlist.
• Deny-only toggles: useAutoModeDuringPlan, syncClaudeAiSkills, syncClaudeAiPlugins and enableArtifact (v2.1.242+). A false anywhere, including the developer's own files, turns the feature off.
• maxEffortLevel (v2.1.267+): the lowest cap wins, and a developer can only lower it further.
• A commit-trailer opt-out in attribution or the older includeCoAuthoredBy.
• forceRemoteSettingsRefresh.
• env (v2.1.223+), merged per variable: each variable comes from the highest source that defines it.

The gateway login keys are never read from server-managed settings, so the highest admin source on the machine supplies them. allowedProviders (v2.1.285+) has its own combination rule, described in the settings reference.

Turning on merge

Set "managedSourcesBehavior": "merge" in the highest-ranked source you deploy; lower sources cannot opt themselves in. If some machines never receive server-managed settings, put it in their MDM profile too. HKCU never merges. Only use merge when every lower source is admin-controlled, because their allow rules and hooks get added.

Policy helpers

A policyHelper is an executable named in your MDM policy or file. Claude Code runs it at startup, and if it emits a managedSettings object, that object becomes the entire managed policy for the session, including the cross-source keys above (with a special startup rule for forceRemoteSettingsRefresh). Useful when policy depends on something only known at runtime, such as the user's group.

Policy supplied by a host application

When Claude Desktop, an IDE extension or an Agent SDK app launches Claude Code, it can pass its own managed settings via the SDK managedSettings option. These are parent settings. By default they are ignored whenever any admin source exists. Set parentSettingsBehavior: "merge" in your top source to combine them; Claude Code then keeps only the host's restrictive values, although the host's allow rules and sandbox allowlists still apply unless you also set the allowManaged*Only locks. A policy helper can veto parent merging.

Some checks apply to parent values regardless: allowManagedPermissionRulesOnly in any admin source strips the host's allow rules and additionalDirectories; your applied forceLoginOrgUUID, allowedMcpServers, availableModels, strictKnownMarketplaces (v2.1.282+) and allowedProviders (v2.1.285+) block the host's versions; and a host's blockedMarketplaces adds to yours.

Cowork and allowManagedPermissionRulesOnly. Cowork grants folder access with allow rules it passes at launch. Under that lock those rules vanish, so Cowork writes fail as "blocked". Add allow rules for the folders your users connect to the managed source that is actually selected (on an MDM fleet, the MDM profile):

{
  "allowManagedPermissionRulesOnly": true,
  "permissions": {
    "allow": ["Edit(~/Documents/ClientWork/**)"]
  }
}

What developers can still change

• The session model. A managed model is a default. --model and ANTHROPIC_MODEL still override it per session; use availableModels to restrict.
• The auto-compact window. A managed autoCompactWindow is a default; --autocompact and CLAUDE_CODE_AUTO_COMPACT_WINDOW override per session.
• The source itself, if they are local admins. That is why MDM tools reapply profiles and why HKLM and the managed preferences domain exist.
• The server-managed cache, but only until the next fetch.
• Other tools. Managed settings only bind Claude Code.

Checking that a policy is in force

Reading /status

Run /status and look at Setting sources. With a managed source active it shows Enterprise managed settings and, in brackets, which one:

From v2.1.242, a Skipped sources line lists anything found but not selected. So:

• No managed entry at all? Nothing delivered a policy key. Check the path and that the file contains a real policy key. For server-managed settings, run claude doctor to see the fetch result.
• A different source than you expected? Something higher-ranked won. Skipped sources will show yours.

Owners can also switch Remote Control and cloud sessions on or off for the organisation in the claude.ai Claude Code admin settings. When Remote Control is turned off, connected sessions on v2.1.286+ disconnect at their next hourly policy refresh. disableRemoteControl turns it off per device. claude doctor (v2.1.261+) prints an Organization policy line showing where that organisation policy came from or why it failed.

Finding entries that were dropped

Managed sources are validated forgivingly. Claude Code repairs what it can (dropping one bad permission rule, for instance), warns, and then discards values that still fail, except for keys that fail closed. You will see the problems in a startup dialog, on stderr in -p runs, and in claude doctor with source and field.

Some failures stop Claude Code launching altogether. If a managed file, drop-in, plist or HKLM value exists but is not a JSON object (invalid JSON, a plutil failure, an empty or non-string registry value), Claude Code refuses to start and names the source, even if another source is fine. Absent sources, an empty file (treated as {}) and a malformed HKCU value do not block launch.

If a source exists but cannot be read and no other admin source supplies policy: an OS permission denial lets sessions start without it (and records the failure); any other read error stops every session with a "contact your administrator" message.

Fail-closed keys

From v2.1.282, a top-level key with a single restrictive value (such as allowManagedPermissionRulesOnly, disableAutoMode or skipDangerousModePermissionPrompt) that is set to something unreadable is treated as that restrictive value, and reported as was present but invalid. A null simply removes the key. An invalid disableAllHooks is dropped rather than enforced, so your own managed hooks keep running. Quoted booleans like "true" are accepted with a notice asking you to remove the quotes.

The permissions, autoMode, worktree and attribution blocks are repaired field by field. Locks inside them go restrictive, an invalid permissions.defaultMode becomes default, and an unreadable deny or ask list withholds allow and additionalDirectories so you never get grants without their matching restrictions. The same applies in autoMode: a bad soft_deny or hard_deny withholds allow and environment.

Keys with their own fallback when invalid:

requiredMinimumVersion and requiredMaximumVersion deliberately fail open. This tolerance is for managed sources only; user, project and local files are rejected whole if their top-level shape is wrong.

Inside sandbox (v2.1.283+), each field is validated separately. Invalid booleans go to whichever value is strictest (enabled reads as true, allowUnsandboxedCommands as false), except failIfUnavailable, which is dropped so a typo cannot stop your whole fleet launching. Bad list entries are removed. An invalid network.deniedDomains withholds network.allowedDomains, and an invalid filesystem.denyRead or denyWrite withholds both filesystem allow lists. Before v2.1.283 one bad field dropped the whole block apart from credentials.

Keys only a managed source can set

These are ignored in user and project files. Most are locks that tell Claude Code to honour only the managed version of an ordinary key.

Turning telemetry off for everyone

Sessions that use the Anthropic API (directly, via a gateway or a custom ANTHROPIC_BASE_URL) send operational telemetry by default. To switch it off fleet-wide:

{
  "env": { "DISABLE_TELEMETRY": "1" }
}

A value of 1 applies without the usual approval dialog. Be aware it also stops the data that feeds your analytics dashboard and disables feature-flag fetching for those users.

Related

• Organisation setup
• Server-managed settings
• Managed MCP
• Settings reference
• Debug your configuration