What Claude Code managed settings are
Claude Code managed settings are the settings an organization deploys to every developer's machine. They use the same JSON shape as a normal settings.json, but Claude Code applies them above every other level: user settings, project settings, local settings and the --settings flag. A developer can make a managed rule stricter for themselves in a few security-sensitive cases. They cannot loosen it.
The same policy reaches the terminal, the VS Code and JetBrains extensions, the desktop app's Code tab and Agent SDK sessions on that machine. So if most of your team lives in the desktop app, they are covered by the same file as the people in the terminal. My take: if more than a couple of people use Claude Code on company code, you want at least a small managed policy in place, even if all it does is block bypass mode and keep secrets files out of reach.
The three ways to deliver managed settings
Every delivery method carries the same keys. What changes is where the policy lives and how quickly a change reaches a running session. Pick the one that matches how you already manage devices.
Claude Code managed settings delivery methods
| Method | Where it lives | When Claude Code reads it | Use it when |
|---|---|---|---|
| Server-managed settings | Organization settings > Claude Code > Managed settings in the claude.ai admin console | At startup, then polled hourly | You have a Team or Enterprise plan and no device management, or developers use cloud sessions |
| MDM or OS policy | A macOS configuration profile in the com.anthropic.claudecode domain, or a Settings value under HKLM\SOFTWARE\Policies\ClaudeCode on Windows | At startup, then checked every 30 minutes | You already run Jamf, Intune, Group Policy or similar |
| Managed settings file | managed-settings.json in the system directory | At startup, and reloaded when the file changes | Machines without MDM, Linux hosts, or images you build yourself |
The file goes in /Library/Application Support/ClaudeCode/ on macOS, /etc/claude-code/ on Linux and WSL, and C:\Program Files\ClaudeCode\ on Windows. Claude Code does not read the old C:\ProgramData\ClaudeCode path, so check for that if you are migrating an older rollout.
If you have MDM, use it. A file that a developer with admin rights can edit is weaker than a profile your device management redeploys. Server-managed settings are the easiest to change, since there is nothing to push to machines, but they are a client-side control rather than a security boundary: on an unmanaged device a user does not need admin rights to get around them. For a team that already has MDM and also uses cloud sessions, run both, because cloud sessions do not read anything on a developer's laptop.
A starter managed-settings.json
Start small. A first policy that blocks reading secrets, turns off bypass mode and makes managed permission rules the only ones that count looks like this, written as plain JSON in the file:
- permissions.deny with Read(./.env) and Read(./secrets/**), so Claude cannot open those files in any project.
- permissions.disableBypassPermissionsMode set to "disable", so nobody can start a session that skips every permission prompt.
- allowManagedPermissionRulesOnly set to true, so allow and deny rules from user, project and local files and from --allowedTools are ignored. Only your managed rules apply.
Be careful with that last one. It is the right call for a locked-down team, but it also throws away every allow rule your developers set up to stop repeat prompts. If you turn it on, add the allow rules people actually need to the managed file, or expect a week of complaints. Claude Code permissions explained covers the rule syntax.
From there, the keys teams reach for most are availableModels to restrict which models people can pick, an env block for things like telemetry endpoints or a proxy, allowedMcpServers and deniedMcpServers for MCP control, and a sandbox block for network allowlists. A managed model value is only a default: --model and ANTHROPIC_MODEL still override it for a session, so use availableModels when you need an actual limit.
Keys only managed settings can set
Some keys do nothing in a user or project file. Claude Code reads them only from a managed source. Most are locks: the thing they protect, such as permission rules or a domain allowlist, can be set anywhere, and the lock tells Claude Code to honor only the managed version.
Managed-only keys worth knowing first
| Key | What it does |
|---|---|
| allowManagedPermissionRulesOnly | Managed settings become the only source of permission rules |
| allowManagedHooksOnly | Restricts which hooks run, so a cloned repo cannot bring its own |
| allowManagedMcpServersOnly | Only the managed allowedMcpServers list counts. deniedMcpServers still merges from every source |
| sandbox.network.allowManagedDomainsOnly | Only managed allowed domains count. Other domains are blocked without a prompt |
| strictKnownMarketplaces | Controls which plugin marketplaces people can add and install from |
| forceRemoteSettingsRefresh | Blocks startup until server-managed settings are freshly fetched, and exits if the fetch fails |
| disableSideloadFlags | Rejects --plugin-dir, --agents, --mcp-config and similar flags at startup |
If you are writing a policy for client work or regulated code, these are the ones that close the obvious gaps. Hooks and MCP servers are the two places a project can bring its own code into a session, so the hooks guide and the MCP server list are worth reading before you decide what to allow.
Server-managed settings from the admin console
On a Team or Enterprise plan, an Owner or Primary Owner can paste the policy JSON into Organization settings > Claude Code > Managed settings. Claude Code fetches it when a developer signs in with an eligible credential, applies a cached copy on later launches, and checks for changes every hour. On a first sign-in, it waits up to five seconds for the fetch so the policy can apply from the first screen.
- It applies to everyone in the organization. Per-group policies are not supported in the console yet, so a different policy for one team means a file or MDM profile for that team.
- Hooks, shell-command settings like apiKeyHelper and statusLine, some sandbox settings and some env variables show the developer an approval dialog first. If they reject it, Claude Code exits.
- Exporting a CLAUDE_CODE_USE_* provider variable or a custom ANTHROPIC_BASE_URL in the shell skips the fetch entirely. If your team routes through a gateway, plan on file or MDM delivery.
- A Console API key belongs to a separate organization from your claude.ai Team or Enterprise organization, so a CI job using one does not receive the console policy. Use a managed file on that machine, or a long-lived OAuth token from claude setup-token.
When more than one source is present
This is where most rollouts go wrong. Claude Code ranks the managed sources in this order: server-managed settings, then MDM or OS policy, then managed settings files, then the Windows HKCU registry. By default it uses the highest-ranked source that sets at least one policy key and ignores the others entirely. It does not merge them, and it does not warn you.
So if someone pastes a two-line policy into the admin console as a test, every carefully built managed-settings.json on your fleet stops applying for most keys. A short list of keys, including the env block, sandbox locks and the MCP allowlist lock, are read from every admin source anyway. If you want every source combined on purpose, set managedSourcesBehavior to "merge" in your highest-ranked source. Lists then combine, locks take the strictest value, and most other keys come from the higher source.
My recommendation: pick one primary delivery method and write it down. Mixing sources is fine when it is deliberate. When it happens by accident, it looks exactly like a policy that silently stopped working.
Check that the policy is actually in force
Never roll out to the whole team without checking one machine first. Two commands answer almost every question.
- Run /status inside Claude Code and read the Setting sources line. It shows Enterprise managed settings with the source in brackets: (remote), (plist), (HKLM), (file), (drop-ins) and so on. A Skipped sources line names any managed source Claude Code found and ignored.
- If the line is missing, Claude Code found no managed source with a policy key. Check the file path for that operating system, and check the file contains a real policy key rather than only control keys.
- Run claude doctor. It lists every entry Claude Code dropped for failing validation, with its source and field, and for server-managed settings it reports whether the fetch loaded, failed or was skipped and why.
- Run /permissions to see the effective permission rules, so you can confirm your deny list is there.
One failure mode to know: a managed settings file that is not valid JSON does not get ignored. Claude Code refuses to start and prints an error naming the file. Validate the JSON in your deployment pipeline before it reaches anyone's machine. Some invalid values also fail closed, so a typo in a lock reads as the strict setting until you fix it, which is safe but confusing if you do not know to look.
Short, practical drops on skills, MCP, agents, prompts, and more. No spam, unsubscribe anytime.
Frequently asked questions
Where is the Claude Code managed-settings.json file?
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 reads it at startup and reloads it when the file changes.
Can developers override Claude Code managed settings?
Not from their own settings files, project files or the --settings flag. A few exceptions let a stricter lower-level value count. A managed model is only a default, so use availableModels to restrict model choice, and a developer with admin rights can edit a local managed file, which is why MDM delivery is stronger.
What are server-managed settings in Claude Code?
Policy you set in the claude.ai admin console under Organization settings > Claude Code > Managed settings. It needs a Team or Enterprise plan and the Owner or Primary Owner role. Claude Code fetches it at startup and checks for changes hourly.
Why are my Claude Code managed settings not applying?
Run /status and read the Setting sources line. If it is missing, the file is in the wrong place or has no policy key. If it names a different source, a higher-ranked source such as server-managed settings is in use and yours was skipped. claude doctor lists dropped entries and failed fetches.
Do managed settings apply to the Claude Code desktop app?
Yes. The desktop app's Code tab reads the same managed sources as the terminal and the IDE extensions on that machine. Cloud sessions are different: they only get policy from server-managed settings.
Last reviewed by David Iya on November 2, 2026
