Deploy managed settings

Deploy managed settings to every developer’s machine: delivery mechanisms per OS, which managed source Claude Code uses, and how to verify enforcement.

Managed settings are the settings your organization deploys to every developer’s machine. Claude Code applies them above every other level, so no user, project, local, or --settings value overrides them, apart from a few security-sensitive exceptions where a stricter value from a lower level still counts.

This page is for the administrator who deploys managed settings or debugs why one isn’t applying. To decide what to enforce, start with the Decide what to enforce table. For the claude.ai console path, see Server-managed settings. For which file a developer’s own values go in, see Settings.

Deploy a managed settings file

This is the quickest way to put a policy on each machine: a managed-settings.json file. If you haven’t picked how to deliver managed settings yet, or your devices are under MDM or developers run cloud sessions, read Choose a delivery mechanism first.

1. Write managed-settings.json

   Write a managed-settings.json that holds the keys you’ve decided to enforce, in the same JSON shape as settings.json. The Decide what to enforce table lists the keys behind each control, and each entry in the settings reference says whether a managed source can set it. This file blocks two file reads, turns off bypass mode, and makes Claude Code ignore permission rules from user, project, and local files and from --allowedTools:

   managed-settings.json

   {
     "permissions": {
       "deny": [
         "Read(./.env)",
         "Read(./secrets/**)"
       ],
       "disableBypassPermissionsMode": "disable"
     },
     "allowManagedPermissionRulesOnly": true
   }
   

   For a fuller example that shows the shape of more managed keys, including the login method, models, MCP servers, and marketplaces, see An organization’s managed settings.

2. Place the file on each machine

   Save the file as managed-settings.json in the system directory for the operating system, using whatever tooling already places files on your fleet:

   • macOS: /Library/Application Support/ClaudeCode/managed-settings.json
   • Linux and WSL: /etc/claude-code/managed-settings.json
   • Windows: C:\Program Files\ClaudeCode\managed-settings.json
3. Confirm the policy applied

   On one machine, run /status inside Claude Code. The Setting sources line shows Enterprise managed settings (file). Roll out to the rest of the fleet after that; Check that a policy is in force covers what to look at when the line is missing.

Choose a delivery mechanism

The file in the steps above is one of four ways to get managed settings onto a machine. Every mechanism carries the same policy keys as a settings.json file, so the settings reference applies to all of them. A few keys are tied to particular sources, and each entry’s Scope line says which:

• Delivery controls: policyHelper and wslInheritsWindowsSettings
• Gateway login keys: forceLoginGatewayUrl and the "gateway" value of forceLoginMethod

A managed settings file, an MDM profile, or the claude.ai console applies one policy to everyone it reaches. To give one group of developers a different policy, deploy a different file or profile to that group; the claude.ai console can’t target a group yet, while a self-hosted Claude apps gateway delivers managed settings per IdP group.

When more than one mechanism delivers a policy to the same machine, Claude Code uses one and ignores the others; Which managed source Claude Code uses gives the order.

The MDM and file rows are together called endpoint-managed settings, because the policy is stored on the developer’s device, as opposed to the server-managed row, where Claude Code fetches it.

Pick a mechanism by how you already manage devices, using the table below.

Mechanism	How you deliver it	When Claude Code reads it	Use it when
Server-managed settings	In the claude.ai admin console, or on a self-hosted Claude apps gateway	Fetched at startup and polled hourly; see changes that need approval	You want one place to change policy for a claude.ai organization without touching each machine
MDM or OS-level policy	As a macOS configuration profile or a Windows HKLM registry value, through Jamf, Intune, Group Policy, or a similar tool; see where each mechanism stores the policy	Read at startup and checked for changes every 30 minutes	You already manage devices with MDM or Group Policy
File-based	As managed-settings.json in a system directory on each machine; see where each mechanism stores the policy	Read at startup and reloaded when a file changes	Machines without MDM, Linux hosts, or images you build yourself
HKCU registry, Windows and WSL	As a Windows HKCU registry value; see where each mechanism stores the policy	Read at startup and checked for changes every 30 minutes; Claude Code uses it only when no other managed source delivers a policy key and no host-supplied parent settings supply a restrictive key	You can’t write the machine-level HKLM key

Starter templates for Jamf, Iru, Intune, and Group Policy are in the MDM examples repository.

For managed MCP servers, which you deploy alongside any of these through managed-mcp.json, see Managed MCP configuration.

Where and when a policy applies

A deployed policy reaches the developer’s sessions as follows:

• Surfaces: every surface that runs Claude Code on the machine reads these sources: the terminal, the VS Code and JetBrains extensions, the desktop app, and Agent SDK sessions, which load managed settings even when settingSources excludes the user, project, and local files.
• Cloud sessions: a session in an Anthropic-hosted environment doesn’t read a device’s MDM profile or file, so policy for it has to come from server-managed settings. A session in a self-hosted environment reads the managed settings file in its runner image only when server-managed settings deliver no keys, apart from the keys Claude Code reads from every admin source.
• Running sessions: a session picks up most changes on the schedule in the table without a restart. Claude Code reads forceRemoteSettingsRefresh and requiredMinimumVersion only at session start, arms a new or changed policyHelper entry at the next launch, and reads some user-editable keys once at session start.
• Changes that need approval: a server-managed change to a setting that needs approval, such as a hook or an env variable, waits for the developer to accept the dialog in an interactive session, and applies for the current run in a session an IDE extension or the Agent SDK hosts. Other server-managed changes apply on the next poll.
• Long-lived sessions: a session left open for weeks can still lag a rollout. requiredMinimumVersion blocks an outdated binary from starting and doesn’t end a session that’s already running.

Where each mechanism stores the policy

The keys are the same everywhere, but each mechanism stores them in a different place and shape:

• Server-managed: Anthropic’s servers, or your gateway, hold the policy. Claude Code keeps a local cache that it applies at startup and replaces on each successful fetch.
• macOS configuration profile: the com.anthropic.claudecode managed preferences domain. Use the same top-level keys as managed-settings.json, with nested settings as dictionaries and lists as plist arrays.
• Windows HKLM registry: the JSON as a REG_SZ or REG_EXPAND_SZ value named Settings under HKLM\SOFTWARE\Policies\ClaudeCode.
• File-based: managed-settings.json, an optional managed-settings.d/ directory, and managed-mcp.json in the system directory: /Library/Application Support/ClaudeCode/ on macOS, /etc/claude-code/ on Linux and WSL, and C:\Program Files\ClaudeCode\ on Windows. Claude Code doesn’t read the legacy Windows path C:\ProgramData\ClaudeCode\managed-settings.json.
• Windows HKCU registry: the same Settings value under HKCU\SOFTWARE\Policies\ClaudeCode.

Split a file-based policy across teams

If several teams own parts of one policy, put each part in its own file in managed-settings.d/, next to managed-settings.json in the same system directory, instead of editing one shared file.

Claude Code merges managed-settings.json first, then every *.json file in the directory in alphabetical order. Name the files with numeric prefixes to control the order, such as 10-telemetry.json and 20-security.json. Claude Code ignores hidden files and files that don’t end in .json.

When two files set the same key, Claude Code combines them by these rules:

• Single values, such as "model": "opus" or "cleanupPeriodDays": 7: the later file’s value replaces the earlier one
• Lists, such as permissions.deny or sandbox.network.allowedDomains: the two lists combine, with duplicates removed
• Nested blocks, such as env or sandbox: the two blocks merge key by key, and each key inside follows these same rules
• fallbackModel: the later chain replaces the earlier one whole
• extraKnownMarketplaces: a later entry with the same name replaces the earlier one whole

Which managed source Claude Code uses

When your organization delivers more than one managed source, Claude Code uses the first of these sources that delivers at least one policy key and ignores the rest rather than merging them, apart from the few cross-source keys covered in Keys read from every admin source.

Claude Code shows no warning for the sources it skips. To see which source it used, run /status.

Two terms recur in this section:

• Policy key: any settings key other than the control key wslInheritsWindowsSettings. A managed settings file or MDM policy that contains only that key doesn’t count, and Claude Code moves on to the next source.
• Admin source: one of the first three sources below. The HKCU registry is user-writable and isn’t one.

Claude Code checks the sources in this order, highest priority first:

1. Remote settings, delivered from claude.ai as server-managed settings or by a Claude apps gateway. Claude Code fetches this source only when the session authenticates to Anthropic’s API directly with an eligible login or key, or signs in to a gateway with /login. On other providers, or when ANTHROPIC_BASE_URL points somewhere other than Anthropic’s API, it starts at the next source
2. MDM or OS-level policies: the macOS plist or the HKLM registry key
3. Managed settings files, managed-settings.d/*.json and managed-settings.json merged together
4. The HKCU registry, on Windows, and on WSL once the HKLM registry or the Windows managed settings file turns wslInheritsWindowsSettings on and the HKCU value also sets it. Claude Code reads it only when no source above it delivers a policy key and no host-supplied parent settings supply a restrictive key

This diagram shows the ranking, with examples of the cross-source keys Claude Code reads from the first three sources:

Keys read from every admin source

For most keys, Claude Code reads only the source it selected. A value in a lower-ranked source is ignored even when the selected source leaves that key unset.

A few keys work differently. Claude Code reads them from every admin source, so a lower-ranked MDM policy or managed settings file can still set them when the selected source doesn’t. Claude Code leaves the user-writable HKCU registry out of that scan; when HKCU is the only source and no host supplies parent settings, HKCU applies like any selected source.

The cross-source keys include:

• sandbox.network.allowManagedDomainsOnly and sandbox.filesystem.allowManagedReadPathsOnly: a true in any admin source turns the lock on. While a lock is on, Claude Code unions the allowlist it locks, sandbox.network.allowedDomains together with WebFetch(domain:...) allow rules, or sandbox.filesystem.allowRead, across every admin source. Without the lock, an unselected admin source’s allowlist is ignored like any other key from an unselected source
• allowAllClaudeAiMcps
• The sandbox binary paths sandbox.bwrapPath and sandbox.socatPath
• The sandbox ripgrep binary, sandbox.ripgrep
• sandbox.filesystem.disabled and sandbox.network.strictAllowlist
• useAutoModeDuringPlan and syncClaudeAiSkills, where a false from any admin source turns the behavior off. A false in the developer’s user or local settings turns it off too; each key can only deny
• A commit-trailer opt-out in attribution, or in the deprecated includeCoAuthoredBy, from any tier
• forceRemoteSettingsRefresh
• env, merged per variable across the admin sources: each variable comes from the highest-priority source that defines it, so lower sources fill in variables the higher ones leave unset. A few variables follow their own rules; Per-key exceptions across managed sources names each one. Requires Claude Code v2.1.223 or later. Before v2.1.223, Claude Code applied the selected source’s whole env block only

Compute the policy with a helper program

A policyHelper is an executable your MDM policy or managed settings file names, and Claude Code runs it to compute managed settings at startup. When the selected source configures one and the helper emits a managedSettings object, that output changes what Claude Code reads:

• The emitted managedSettings object is the only managed settings for the session, including for the keys it otherwise reads from every admin source, apart from forceRemoteSettingsRefresh, which Claude Code checks in every admin source at startup before the helper runs. A helper that exits 0 without emitting one contributes nothing, and the sources apply as usual; a helper that fails stops Claude Code from starting, as the policyHelper entry describes

Claude Code selects the source at startup, and that selection decides whether a helper runs. The policyHelper entry says which sources can configure a helper.

Let an embedding host add policy

When another application launches Claude Code, such as Claude Desktop, an IDE extension, or an Agent SDK app, that host can pass its own managed settings through the SDK managedSettings option. Claude Code calls these parent settings.

By default, Claude Code ignores parent settings whenever an admin source is present: server-managed settings, an MDM or OS-level policy, or a managed settings file.

To have Claude Code merge parent settings alongside an admin source, set parentSettingsBehavior to "merge" in the highest-priority managed source; Claude Code reads the key from that source only.

Claude Code then keeps only the host’s values that restrict what Claude can do, with one gap to know about: unless you also set the allowManaged*Only locks, the host’s permission allow rules and sandbox allowlists still apply. See Restrict parent settings for the locks.

A policyHelper can turn parent merging off regardless of this key; its entry says when.

Claude Code also applies these checks to parent-supplied values on their own:

• When any admin source sets allowManagedPermissionRulesOnly, Claude Code drops parent-supplied permission allow rules and additionalDirectories as it reads them, even when a higher-priority source leaves the key unset. The key’s effect on your own permission rules still comes only from the selected source, or from parent settings you’ve chosen to merge
• A forceLoginOrgUUID or allowedMcpServers value in the highest-priority admin source blocks a parent-supplied one, and Claude Code enforces the admin value. A value in an admin source that isn’t the highest-priority one neither applies nor blocks the parent’s. Before v2.1.223, a value in any admin source blocked the parent’s
• An availableModels value follows the same rule as forceLoginOrgUUID and allowedMcpServers

What a developer can change

A developer’s own settings files, --settings values, and project files never override a managed value; the exceptions only let a stricter lower-level value count. Four things sit outside that rule:

• The model for a session: a managed model is a default, not a lock. --model and ANTHROPIC_MODEL still pick the model for that session, so deploy availableModels to restrict the choice.
• Local admin rights: a developer who is an administrator on the machine can edit the managed source itself, which is why MDM tooling can redeploy the profile or file on a schedule and why the HKLM registry and the macOS managed preferences domain exist.
• The server-managed cache: server-managed settings come from Anthropic’s servers, and an edit to the local cache lasts only until the next successful fetch.
• Other tools: managed settings bind Claude Code only. A developer who calls the API from another tool isn’t under them.

Check that a policy is in force

A developer reports that a policy isn’t applying, or you want to confirm a rollout landed before pushing it to the fleet. Two commands on that machine answer it: /status shows which managed source Claude Code selected, and claude doctor lists what it dropped.

Read the source in /status

On the developer’s machine, run /status inside Claude Code and read the Setting sources line. When a managed source is in effect, the line lists Enterprise managed settings with the source Claude Code selected in parentheses:

• (remote): server-managed settings from claude.ai or a gateway
• (plist) or (HKLM): an MDM or OS policy
• (file), (drop-ins), or (file + drop-ins): managed-settings.json, the drop-in directory, or both
• (HKCU): the user-writable registry fallback
• (parent process): an embedding host supplied restrictive settings
• (helper): a policyHelper configured by the selected MDM or file source

When the policy isn’t applying, the line tells you which of two problems you have:

• The line is missing: Claude Code found no managed source that delivers a policy key. Check that the file sits at the path for the OS, that it’s valid JSON, and that it contains a key other than wslInheritsWindowsSettings.
• The line names a source other than the one you deployed: a higher-priority source is present and Claude Code ignored yours. Which managed source Claude Code uses gives the order.

Find entries Claude Code dropped

When a managed settings file, MDM profile, registry value, or server-managed payload fails schema validation, Claude Code first skips the individual entries it can repair, such as one invalid permission rule, with a warning for each, then drops any top-level key whose value still fails and keeps enforcing every remaining valid key. Claude Code is stricter with the managedSettings a policyHelper emits: it makes the same entry repairs, but any schema violation that survives fails the whole helper run, and at startup Claude Code refuses to start, the same as for a helper that exits non-zero. A managed settings file or drop-in file that isn’t valid JSON contributes no settings at all; Claude Code reports it with the other validation errors and reads the remaining sources as usual.

To find a dropped entry, look in one of three places:

• Interactive sessions show a dialog at startup listing the invalid entries.
• Non-interactive runs with -p print a summary to stderr.
• claude doctor lists each invalid entry with its source and field.

Keys that fail closed

A few enforcement keys aren’t dropped when invalid. Claude Code enforces a stricter fallback until the value is fixed; the table shows what it enforces for each key:

Field	Behavior when present but invalid
allowedMcpServers	Enforced as an empty allowlist, so no MCP servers are admitted until the value is fixed. An individual invalid entry is stripped and the valid subset is enforced.
allowManagedHooksOnly	Treated as true until fixed: the hook restrictions apply and, unless disableCommandPluginSources is explicitly false, command-sourced plugins are disabled.
allowManagedMcpServersOnly	Treated as true.
disableCommandPluginSources	Treated as true, so command-sourced plugins stay disabled until the value is fixed.
availableModels	Enforced as an empty allowlist until fixed, so only the Default model is available; a non-string entry is stripped and the valid subset enforced.
enforceAvailableModels	Treated as true.
forceLoginOrgUUID	No organization is permitted to log in until the value is fixed.
deniedMcpServers	An individual invalid entry is stripped and the valid subset is enforced. A wholly invalid value is dropped with a warning, since denying every server would block servers the policy never named.
sandbox.credentials	A recoverable invalid entry is degraded to mode: "deny" with a warning; an unrecoverable one is stripped; valid entries stay enforced. See invalid credential entries

requiredMinimumVersion and requiredMaximumVersion fail open by design: an invalid value is dropped rather than enforced, so a bad policy push can’t prevent Claude Code from starting.

This tolerance applies only to managed settings. User, project, and local settings files remain strict: a file whose JSON or top-level shape fails validation is rejected as a whole and reported, and an individual entry that fails, such as a malformed permission rule, is skipped with a warning while the rest of the file applies.

Keys only a managed source can set

Claude Code reads the following keys only from a managed source; placing them in user or project settings files has no effect.

Most of them are locks: the value a lock governs, such as permission rules or sandbox.network.allowedDomains, is an ordinary key that any level can set, and the lock tells Claude Code to honor only the managed value.

The table covers the permission, plugin, and delivery controls. For any key not listed here, the Scope column of the settings reference index says whether it’s managed-only; the remaining managed-only keys there include the gateway login URL, version, browser, mobile-simulator, SSH host, sandbox binary path, and CLAUDE.md controls.

Setting	Description
allowAllClaudeAiMcps	Load the claude.ai connectors alongside a deployed managed-mcp.json instead of suppressing them
allowedChannelPlugins	Allowlist of channel plugins that may push messages. Replaces the default Anthropic allowlist when set. Requires channelsEnabled: true. See Restrict which channel plugins can run
allowManagedHooksOnly	When true, restricts which hooks run; see what runs under allowManagedHooksOnly for the full effect list
allowManagedMcpServersOnly	When true, only allowedMcpServers from managed settings are respected. deniedMcpServers still merges from all sources. See Managed MCP configuration
allowManagedPermissionRulesOnly	Only managed permission rules apply; the entry lists every source it ignores
blockedMarketplaces	Blocklist of marketplace sources. Blocked sources are checked before downloading, so they never touch the filesystem. See managed marketplace restrictions
channelsEnabled	Allow channels for the organization. See enterprise controls for the default on each plan
disableCommandPluginSources	When true, blocks command plugin sources entirely, so the marketplace-declared command never runs. When unset, follows allowManagedHooksOnly. Requires Claude Code v2.1.229 or later
disableSideloadFlags	Reject the --plugin-dir, --plugin-url, --agents, and --mcp-config flags at startup. In cloud sessions, Claude Code drops the MCP servers the server delivered through --mcp-config, other than in-process type: "sdk" entries, and starts the session. Requires Claude Code v2.1.193 or later
forceRemoteSettingsRefresh	When true, blocks CLI startup until remote managed settings are freshly fetched and exits if the fetch fails. See fail-closed enforcement
parentSettingsBehavior	Whether host-supplied parent settings merge under the managed policy
pluginSuggestionMarketplaces	Marketplaces whose plugins Claude Code may suggest to users
pluginTrustMessage	Custom message appended to the plugin trust warning shown before installation
policyHelper	Executable that computes managed settings at startup; see Compute managed settings with a policy helper
sandbox.filesystem.allowManagedReadPathsOnly	When true, only filesystem.allowRead paths from managed settings are respected. denyRead still merges from all sources
sandbox.network.allowManagedDomainsOnly	Honor only managed allowedDomains and WebFetch(domain:...) allow rules; block other domains without prompting
strictKnownMarketplaces	Controls which plugin marketplace sources users can add and install plugins from. See managed marketplace restrictions
strictPluginOnlyCustomization	Block skills, agents, hooks, and MCP servers from user and project sources; true locks all four, an array names which
wslInheritsWindowsSettings	When set in the HKLM registry or a file under C:\Program Files\ClaudeCode, have WSL read the Windows policy chain, and read /etc/claude-code only when no managed settings file or drop-in under that directory delivers a policy key other than wslInheritsWindowsSettings; the entry gives the order

On Team and Enterprise plans, an Owner enables or disables Remote Control and web sessions organization-wide in Claude Code admin settings. Remote Control can additionally be disabled per device with the disableRemoteControl setting. Web sessions have no per-device managed settings key.

See also

• Set up Claude Code for your organization: decide what to enforce and how
• Server-managed settings: deliver policy from the claude.ai console or a gateway
• Managed MCP configuration: control which MCP servers developers can use
• Settings reference: every key, with whether a managed source can set it
• Example settings files: a complete managed-settings.json showing the shape of the managed keys