Claude Code managed settings for enterprises

Managed settings are the policy an organization deploys to every developer’s machine, and Claude Code applies them above user, project, local and –settings values. Deploy a managed-settings.json file to a system directory, or send the same keys through MDM or claude.ai server-managed settings. Then run /status to confirm the policy loaded.

Deploy a managed-settings.json file

The file is the quickest way to put one policy on each machine. It uses the same JSON shape as settings.json, and the settings reference says which keys a managed source can set. The steps below follow Claude Code’s managed settings guide.

1. Write managed-settings.json with the keys you have decided to enforce. The example below blocks two file reads, turns off bypass mode, and makes Claude Code ignore permission rules from user, project and local files and from –allowedTools.
2. Save the file as managed-settings.json in the system directory for each operating system:
   • macOS: /Library/Application Support/ClaudeCode/
   • Linux and WSL: /etc/claude-code/
   • Windows: C:\Program Files\ClaudeCode\
3. On one machine, run /status and check that the Setting sources line shows Enterprise managed settings (file). Roll out to the rest of the fleet after that.

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

Claude Code reads the file at startup and reloads it when the file changes. A file that is not valid JSON stops Claude Code from starting, so run the file through a JSON parser before you copy it to the fleet.

Choose how the policy reaches each machine

The file is one of four ways to deliver managed settings. Each one carries the same policy keys, but each stores them in a different place and reads them on a different schedule.

Mechanism	Where the policy is stored	When Claude Code reads it	Use it when
Server-managed	Anthropic’s servers, or a self-hosted Claude apps gateway	Fetched at startup and polled hourly	You want one place to change policy for a claude.ai organization
MDM or OS-level policy	The com.anthropic.claudecode preferences domain on macOS, or HKLM\SOFTWARE\Policies\ClaudeCode on Windows	Read at startup and checked every 30 minutes	You already manage devices with MDM or Group Policy
File-based	managed-settings.json and an optional managed-settings.d/ directory in the system directory	Read at startup and reloaded when a file changes	Machines without MDM, Linux hosts, or images you build yourself
HKCU registry (Windows and WSL)	HKCU\SOFTWARE\Policies\ClaudeCode	Read at startup and checked every 30 minutes, only when no admin document sits above it	You cannot write the machine-level HKLM key

Cloud sessions do not read a device’s MDM profile or file, so policy for them has to come from server-managed settings. A developer’s own settings files do not override a managed key, apart from the few security keys covered below.

Know which managed source wins

When one machine receives more than one managed source, the default behavior is first-wins. Claude Code takes the highest-ranked source that delivers at least one policy key, and it ignores the rest rather than merging them. The ranking runs from top to bottom:

1. Remote settings, delivered as server-managed settings or by a Claude apps gateway
2. MDM or OS-level policy
3. Managed settings files, managed-settings.d/*.json and managed-settings.json merged together
4. The HKCU registry, which is user-writable and never merges with the others

Setting managedSourcesBehavior to "merge" in the highest-ranked source makes Claude Code apply every admin source, and it needs v2.1.242 or later. Under merge, lists such as permissions.allow and hooks combine across sources, so turn it on only when every lower source is under administrator control. The /status command lists skipped sources on a Skipped sources line.

If several teams own parts of one policy, split it into files in managed-settings.d/. Claude Code merges them in alphabetical order, so numeric prefixes such as 10-telemetry.json and 20-security.json set the order. List keys combine with duplicates removed, and a single value in a later file replaces the earlier one.

See how managed settings rank against developer files

Settings precedence runs from managed settings at the top to user settings at the bottom. A key set at a higher level overrides the same key set lower down.

1. Managed settings
2. Command line, through --settings
3. Project local, in .claude/settings.local.json
4. Shared project, in .claude/settings.json
5. User, in ~/.claude/settings.json

List keys merge instead of overriding, so entries in a project file add to the entries in the user file. Some security keys are the exception. A true for disableClaudeAiConnectors in any scope stays on even when a managed source sets false, and the same rule lets a stricter value from a lower scope count for a few other keys.

Lock permission rules and bypass mode

Claude Code checks permission rules in one order: deny, then ask, then allow. The first match decides the outcome, and an allow rule cannot carve an exception out of a deny rule. Setting allowManagedPermissionRulesOnly to true removes the other sources of rules. Claude Code then ignores allow, ask and deny rules in user, project, local and --settings files, and it ignores --allowedTools. It also hides the always-allow choices in permission prompts and stops saving new rules.

Bypass mode is a separate switch. The following setting blocks it, and Claude Code then rejects the --dangerously-skip-permissions flag.

{
  "permissions": {
    "disableBypassPermissionsMode": "disable"
  }
}

A Bash deny rule has a limit that matters for enforcement. It matches the command text Claude writes, so Bash(curl *) does not stop /usr/bin/curl or sh -c 'curl ...'. The settings reference says to enable the sandbox for OS-level enforcement, so pair the rule with the sandbox.

Restrict hooks and MCP servers

Set allowManagedHooksOnly to true to run only hooks that come from managed settings. Claude Code still runs hooks from the Agent SDK and from plugins that managed settings force-enable. It blocks hooks in user, project and local settings, and it disables plugins with a command source.

{
  "allowManagedHooksOnly": true
}

For MCP servers, allowManagedMcpServersOnly makes Claude Code read allowedMcpServers from managed settings alone. Developers can still add their own servers, but only servers that match the managed allowlist load. The deniedMcpServers list still merges from every settings scope, so a developer can block a server for themselves. The restrict MCP servers post covers the allowlist in detail.

{
  "allowManagedMcpServersOnly": true,
  "allowedMcpServers": [
    { "serverName": "github" }
  ]
}

Map each control to its key

Each control maps to one key. The version column gives what the docs say about that key. The managed settings page gives no CLI version for the file-based setup itself, so the version column is the only version guidance on those pages.

Control	Key	What it does	Version the docs state
Permission rules from managed settings only	allowManagedPermissionRulesOnly	Ignores permission rules in user, project, local and --settings files	Before v2.1.257, command-line and session rules were dropped at the first settings reload
No bypass mode	permissions.disableBypassPermissionsMode	Rejects --dangerously-skip-permissions	Before v2.1.223, frontmatter permission mode applied even with bypass disabled
Managed hooks only	allowManagedHooksOnly	Runs only managed, SDK and force-enabled plugin hooks	Blocking headersHelper commands needs v2.1.238 or later
Managed MCP allowlist only	allowManagedMcpServersOnly	Reads allowedMcpServers from managed settings alone	Reading the lock from any admin source needs v2.1.273 or later

Gotchas that weaken a managed policy

• Local admin rights. A developer who is an administrator on the machine can edit the managed file. Have MDM tooling redeploy the file or profile on a schedule.
• A managed model is a default. --model and ANTHROPIC_MODEL still pick the model for a session. Deploy availableModels to restrict the choice.
• Other tools. Managed settings bind Claude Code only. A developer who calls the API from another tool is not under them.
• Control keys alone. A managed file that holds only wslInheritsWindowsSettings or managedSourcesBehavior does not count as a policy, and Claude Code moves on to the next source.
• Symbolic links. A link that points outside the system directory still applies, but /status and claude doctor show a warning. Point the link inside the directory to clear it.
• Invalid entries. Claude Code skips a single bad entry it can repair and warns about it. It drops any value that still fails validation, except for keys that fail closed. Check /status and claude doctor after each change.

Enforcing this with AIControls

The managed file sets Claude Code policy on each machine. AIControls covers the parts that are confirmed today: Claude Code through the gateway (CLI and VS Code), per-user tokens, and per-user and per-session cost and budget limits. The governance for AI coding agents page is the pillar for this topic, and the AIControls download page is the product page. For the key-by-key walkthroughs, read the destructive commands post and the gateway routing post.

Frequently asked questions

Can a developer override a managed setting in their own settings file?

For most keys, no. Managed settings sit above user, project, local and --settings values, so those files cannot change a managed key. A few keys are the exception. A true value for disableClaudeAiConnectors in any scope stays on even when a managed source sets false. A developer with local admin rights can still edit the managed file, so redeploy it through MDM on a schedule.

Where does managed-settings.json go on each operating system?

On macOS it goes in /Library/Application Support/ClaudeCode/, on Linux and WSL in /etc/claude-code/, and on Windows in C:\Program Files\ClaudeCode\. Claude Code does not read the legacy Windows path C:\ProgramData\ClaudeCode\managed-settings.json. After you place the file, run /status and check that the Setting sources line shows Enterprise managed settings (file).

Does a managed setting stop a developer from choosing a different model?

Not by itself. A managed model is a default, not a lock. The --model flag and ANTHROPIC_MODEL still pick the model for a session. To restrict the choice, deploy availableModels in managed settings. When managed settings define that list, Claude Code applies it as written and ignores entries a developer adds in user, project or local settings.

Which Claude Code version do I need for managed settings?

The file-based setup does not state a CLI version on the managed settings page. Individual keys do. Combining several managed sources with merge needs v2.1.242 or later, and reading the MCP allowlist lock from any admin source needs v2.1.273 or later. Check the version column in the key table, and run claude doctor on a test machine to see anything Claude Code dropped.