OmniscioGuidesClaude Code managed settings
Claude Code managed settings: one policy for every machine
The hard part of a Claude Code rollout is not deciding what the policy should be. It is knowing that the policy actually reached the machine and actually won.
This page is the administrator's road: the one file that does the job on a small fleet, the four mechanisms for a larger one, what a developer can still change, and the two commands that end an argument about whether a policy is live.
Last checked against Anthropic's Claude Code documentation on November 18, 2026. By the Omniscio team. Updated .
What "managed" means
Managed settings sit above every other level of Claude Code configuration. A user's own files, a project's settings, a local override and a --settings flag all lose to them, with a small set of security-sensitive exceptions where a stricter value from a lower level still counts.
The exceptions are narrower settings that can only tighten, never loosen: a developer's own lower cap on maxEffortLevel still applies, and a false for enableArtifact in a user, project or local file turns that tool off for them whatever the policy says. Nothing in that set lets a lower level grant more than you deployed.
They are written in the same JSON shape as settings.json, so anything you already know about a setting's name and values applies here too. What changes is the scope: a managed value is policy, not a default a developer can adjust.
Source: the introduction of Anthropic's managed settings page, read November 18, 2026.
The quickest road: one file
- Write the file. A
managed-settings.jsonholding only the keys you have decided to enforce. This one blocks two file reads, turns off bypass mode, and makes Claude Code ignore permission rules from user, project and local files and from--allowedTools:
{
"permissions": {
"deny": [
"Read(./.env)",
"Read(./secrets/**)"
],
"disableBypassPermissionsMode": "disable"
},
"allowManagedPermissionRulesOnly": true
}- Place it on each machine in the system directory for the operating system:
/Library/Application Support/ClaudeCode/managed-settings.jsonon macOS,/etc/claude-code/managed-settings.jsonon Linux and WSL, andC:\Program Files\ClaudeCode\managed-settings.jsonon Windows, using whatever tooling already places files on your fleet. The legacy Windows pathC:\ProgramData\ClaudeCode\managed-settings.jsonis not read. - Confirm it on one machine. Run
/status: theSetting sourcesline showsEnterprise managed settings (file). Only then roll out to the rest.
Two conveniences are worth knowing before you build an image. The file can be a symbolic link and Claude Code follows it, with a warning in /status and claude doctor if the target sits outside the system directory. And an optional managed-settings.d/ directory beside it lets several teams own parts of one policy: files merge in alphabetical order, so numeric prefixes such as 10-telemetry.json and 20-security.json control the sequence.
Source: "Deploy a managed settings file", "Where each mechanism stores the policy" and "Split a file-based policy across teams" in Anthropic's managed settings page, read November 18, 2026.
Four delivery mechanisms
Pick by how you already manage devices.
- Server-managed settings. Set in the claude.ai admin console or on a self-hosted gateway, fetched at startup and polled hourly. Right when you want one place to change policy for an organization without touching machines.
- MDM or OS-level policy. A macOS configuration profile or a Windows
HKLMregistry value, through Jamf, Intune, Group Policy or similar. Read at startup and checked every 30 minutes. Right when you already manage devices that way. - File-based. The
managed-settings.jsonabove. Read at startup and reloaded when it changes. Right for machines without MDM, Linux hosts, and images you build yourself. - Windows
HKCUregistry. The same value in the user-writable key, used only when no admin document sits above it. Right when you cannot write the machine-levelHKLMkey.
The MDM and file rows are together called endpoint-managed settings, because the policy is stored on the developer's device; the server-managed row is the one where Claude Code fetches it.
Source: the delivery mechanism table in Anthropic's managed settings page, read November 18, 2026.
Where each one stores the policy
Same keys everywhere, different containers:
- macOS profile: the
com.anthropic.claudecodemanaged preferences domain, with the same top-level keys, nested settings as dictionaries and lists as plist arrays. - Windows
HKLM: the JSON as aREG_SZorREG_EXPAND_SZvalue namedSettingsunderHKLM\SOFTWARE\Policies\ClaudeCode. TheHKCUfallback mirrors it underHKCU\SOFTWARE\Policies\ClaudeCode. - File-based:
managed-settings.json, the optionalmanaged-settings.d/directory, andmanaged-mcp.json, all in the OS system directory. - Server-managed: Anthropic's servers or your gateway hold it, and Claude Code keeps a local cache it can apply at startup and replaces on each successful fetch.
Starter templates for Jamf, Iru, Intune and Group Policy live in Anthropic's MDM examples repository. Managed MCP servers are their own file or key, managed-mcp.json or managedMcpServers.
Source: "Where each mechanism stores the policy" in Anthropic's managed settings page, read November 18, 2026.
What a developer can still change
A managed value holds, but a few things sit outside that rule and are worth knowing before someone reports a hole:
- The model for a session. A managed
modelis a default, not a lock:--modelandANTHROPIC_MODELstill pick the model for that session. DeployavailableModelsif you need to restrict the choice. - The auto-compact window. Also a default:
--autocompactandCLAUDE_CODE_AUTO_COMPACT_WINDOWstill set it for a session. - Local admin rights. Someone who administers the machine can edit the managed source itself — which is why MDM tooling redeploys the profile, and why the
HKLMand managed-preferences roads exist. - The server-managed cache. A local edit lasts only until the next successful fetch.
- Other tools. Managed settings bind Claude Code. Someone calling the API from another client is not under them.
Source: "What a developer can change" in Anthropic's managed settings page, read November 18, 2026.
When several sources reach one machine
The ranking, highest priority first, is the same under either setting:
- Remote settings — server-managed settings from claude.ai or a gateway, fetched only when the session authenticates to Anthropic's API directly or signs in to a gateway. On a third-party provider it starts at the next source.
- MDM or OS policy — the macOS plist or the Windows
HKLMkey. - Managed settings files —
managed-settings.jsonandmanaged-settings.d/*.json, merged together. - The Windows
HKCUregistry, read only when no admin document is present above it.
By default Claude Code uses the highest-ranked source that delivers at least one policy key and ignores the rest, apart from a handful of cross-source keys it reads from every admin source — the sandbox locks, env merged variable by variable, maxEffortLevel where the lowest cap wins, and forceRemoteSettingsRefresh among them. It shows no warning for the sources it skips, which is exactly why a rollout can look dead when it is merely beaten by something else.
The managedSourcesBehavior key changes that. Set to merge, Claude Code applies every admin source that delivers a policy key and combines them: on most keys the higher-ranked value wins, lists union, and locks take the strictest value. It needs Claude Code v2.1.242 or later.
Source: "How Claude Code combines managed sources" in Anthropic's managed settings page, read November 18, 2026.
Prove it applied
Two commands answer it. /status shows which source Claude Code selected; claude doctor lists what it dropped.
The Setting sources line reads Enterprise managed settings with the source in parentheses: (remote) for server-managed, (plist) or (HKLM) for an OS policy, (file), (drop-ins) or (file + drop-ins) for the file roads, (HKCU) for the user-writable registry, and a list ending in merged when every source is composed. When a source was found and not selected, a Skipped sources line names it — that is the difference between a policy that never arrived and one that lost.
Two failure modes are worth memorising because they look different from the outside:
- A missing line means no managed source delivering a policy key was found. Check the path for the OS, and check that the file holds a policy key rather than only control keys.
- A file that cannot be parsed — invalid JSON, or a top level that is not an object — makes Claude Code refuse to start and print an error naming the source, even when another admin source is valid. An absent file is fine; an empty one counts as
{}.
Individual entries are gentler: Claude Code repairs what it can, warns about each entry it skipped, and drops the rest — except for keys that fail closed, such as allowManagedPermissionRulesOnly or disableAutoMode set to a value it cannot read, which hold the restrictive value until you fix them.
A file that cannot be parsed is different from a remote fetch that never arrived. When the server-managed copy cannot be fetched or applied, Claude Code says so in a warning with its own causes and endings, covered in remote managed settings failed to load.
Source: "Check that a policy is in force" and "Keys that fail closed" in Anthropic's managed settings page, read November 18, 2026.
Keys only a managed source can set
Some keys do nothing outside a managed source, and most of them are locks: the thing they govern is an ordinary setting any level can write, and the lock tells Claude Code to honour only the managed value. The ones asked about most:
allowManagedPermissionRulesOnly— managed settings become the only source of permission rules.allowManagedHooksOnly— restricts which hooks may run.allowManagedMcpServersOnly— only the managedallowedMcpServersare respected.strictKnownMarketplacesandblockedMarketplaces— which plugin marketplaces can be added and installed from.disableSideloadFlags— rejects--plugin-dir,--plugin-url,--agentsand--mcp-configat startup.forceRemoteSettingsRefresh— blocks startup until remote managed settings are freshly fetched, and exits if the fetch fails.sandbox.network.allowManagedDomainsOnly— honour only managed domains and block the rest without prompting.policyHelper— an executable that computes managed settings at startup.
One use of the env block is worth its own note. Delivering DISABLE_TELEMETRY as "1" through managed settings turns off operational telemetry for everyone the policy reaches, with no approval dialog — and it also stops the usage data that feeds your organization's analytics dashboard for those developers.
Sources: "Keys only a managed source can set" and "Turn telemetry off for your organization" in Anthropic's managed settings page, read November 18, 2026.
Where these answers come from
- Everything on this page: Deploy managed settings, read November 18, 2026.
- The whole catalogue of keys: Settings reference.
- The console road instead of a device file: Server-managed settings.
- What to enforce in the first place: Set up Claude Code for your organization.
- Where a single developer's settings go: the settings.json locations.
Common questions
Where does managed-settings.json go?
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.
Can a developer override a managed setting?
No. Managed settings outrank user, project, local and --settings values, except where a security-sensitive exception lets a stricter lower-level value count.
How do I know the policy is applying?
/status, and read the Setting sources line: Enterprise managed settings with the source in parentheses. claude doctor adds the fetch outcome and any entry it dropped.
What happens if the file is not valid JSON?
Claude Code refuses to start and prints an error naming the source, even if another admin source holds a valid policy. Fix the file before rolling out.