Guide from the official docs

Claude Code managed settings: where the file goes, what a company can lock, and what it can't

How an organization limits Claude Code: managed-settings.json paths per OS, the four delivery routes, what each key locks, and where policy stops. From Anthropic's docs.

By AideDex desk · published

This guide follows the official docs and announcements, linked inline. AideDex did not test these products and does not score them. How we check facts.

Last checked Nov 9, 2026. Everything below comes from Anthropic’s documentation and the two third-party guides named in the text. We did not deploy a policy on a managed machine, so none of it is a test result.

Managed settings are the settings an 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 keys where a stricter lower-level value still counts (Deploy managed settings). On Nov 2, 2026 Bloomberg reported that Goldman Sachs had limited tools such as Claude Code to engineers, citing internal guidelines from October (The Decoder, Bloomberg). This guide is about the controls an administrator has, where they stop, and how to check that one took effect.

Where managed-settings.json goes

A file-based policy is a managed-settings.json in the system directory, in the same JSON shape as settings.json (Deploy managed settings):

SystemPath
macOS/Library/Application Support/ClaudeCode/managed-settings.json
Linux and WSL/etc/claude-code/managed-settings.json
WindowsC:\Program Files\ClaudeCode\managed-settings.json

The docs say Claude Code does not read the old Windows path C:\ProgramData\ClaudeCode\managed-settings.json. A second route exists on all three systems: a managed-settings.d/ folder next to the file. Claude Code merges the base file first, then every *.json in the folder in alphabetical order, and ignores hidden files and anything not ending in .json. Two teams can each own one fragment, such as 10-telemetry.json and 20-security.json.

The merge rules decide who wins. A single value, such as "model": "opus", is replaced by the later file. Lists such as permissions.deny combine with duplicates removed. Nested blocks such as env merge key by key (Deploy managed settings). A third-party course describes the same behaviour and warns about the consequence: two teams that set the same single value get no error, and the file that sorts later wins (Mastering Claude Code). Give each team keys the others do not touch.

On the Linux machine we checked, claude --version prints 2.1.319 and /etc/claude-code does not exist, so no file policy is present there.

Four ways a policy arrives

The file is one of four delivery routes. All carry the same keys (Deploy managed settings):

RouteHow it is deliveredWhen Claude Code reads it
Server-managedThe claude.ai admin console, or a self-hosted Claude apps gatewayAt startup, then polled hourly
MDM or OS policyA macOS configuration profile (com.anthropic.claudecode) or a Windows HKLM registry valueAt startup, checked for changes every 30 minutes
Filemanaged-settings.json and managed-settings.d/At startup, reloaded when a file changes
Windows HKCUA per-user registry valueAt startup, every 30 minutes; used only when no admin source is present

The console route needs a Claude for Teams or Enterprise plan, the Owner or Primary Owner role to edit it, and network access to api.anthropic.com (Server-managed settings). Claude Code is included with every Team plan seat (Claude Help Center). The same page says the console applies one policy to everyone, and per-group settings are not supported yet.

By default Claude Code uses one route and ignores the rest. It takes the highest-ranked source that delivers at least one policy key: server-managed first, then MDM, then the files, then HKCU. It shows no warning for the sources it skips. Setting managedSourcesBehavior to "merge" in the top source makes it combine them instead, and that needs Claude Code 2.1.242 or later (Deploy managed settings). Under "merge" the lower sources add their permissions.allow rules and hooks to the policy, so the docs say to switch it on only when every lower source is under an administrator’s control.

Anthropic’s own advice on choosing: use server-managed settings for organizations without MDM or with unmanaged devices, and endpoint-managed settings where devices are enrolled, because the file can then be protected from the user at the OS level (Server-managed settings, Set up Claude Code for your organization).

A first policy

Anthropic’s example blocks two file reads, turns off bypass mode and makes Claude Code ignore permission rules from user, project and local files (Deploy managed settings):

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

The last line matters most. With allowManagedPermissionRulesOnly, Claude Code ignores allow, ask and deny rules in user, project, local and --settings files, ignores --allowedTools, hides the always-allow choices in permission prompts and stops saving new rules (Settings reference). That is the setting that answers the problem in Claude Code’s “Don’t ask again” file, where a standing approval saves a command, and sometimes a password, into .claude/settings.local.json. Without the lock, developers can still add allow rules next to your deny rules. Deny rules from any level beat allow rules, so a managed deny cannot be undone by a developer (Configure permissions).

What an administrator can lock

Anthropic’s decision table lists the control areas and the keys behind them (Set up Claude Code for your organization). The ones most organizations ask about:

GoalKeysWhat the docs add
Stop --dangerously-skip-permissionspermissions.disableBypassPermissionsModeWorks from any scope, but only managed placement stops a user from undoing it (Configure permissions)
Limit which models people can pickavailableModels, enforceAvailableModelsApplies to /model, --model, the environment variable, subagents and skills. A managed model alone is only a default (Model configuration)
Limit MCP serversallowedMcpServers, deniedMcpServers, allowManagedMcpServersOnly; or a deployed managed-mcp.jsonA managed-mcp.json gives exclusive control: users cannot add or use other servers (Managed MCP configuration)
Require one loginforceLoginMethod, forceLoginOrgUUIDSet these in the MDM policy or file as well as the console (Deploy managed settings)
Limit API providersallowedProvidersNeeds 2.1.285 or later; a session on an unlisted provider is refused
Control hooks, plugins, skillsallowManagedHooksOnly, strictKnownMarketplaces, strictPluginOnlyCustomizationstrictPluginOnlyCustomization blocks skills, agents, hooks and MCP servers from user and project sources
Set a version floor or rangeminimumVersion, requiredMinimumVersion, requiredMaximumVersionminimumVersion only stops auto-update from installing below the floor; the required pair stops Claude Code from starting outside the range (Set up Claude Code for your organization)
Isolate executionsandbox.enabled, sandbox.network.allowedDomainsOS-level filesystem and network limits

Cloud sessions have their own admin switches. On Team and Enterprise plans an Owner turns Remote Control and cloud sessions on or off for the organization in Claude Code admin settings, and cloud sessions have no per-device managed key (Deploy managed settings).

A deny rule is not a wall

One third-party guide offers a deny list with Bash(curl:*) and Bash(wget:*) and calls permissions.deny the rule that “earns its keep” (Tygart Media). Anthropic’s permissions page is more careful: a Bash rule matches the command text Claude writes, so Bash(curl *) stops curl https://example.com but not /usr/bin/curl https://example.com or sh -c 'curl https://example.com'. The docs say such a rule “isn’t a security boundary around the program” and point to sandboxing for enforcement that does not depend on command text (Configure permissions). The admin guide gives the same warning from the other side: denying WebFetch blocks the fetch tool, but if Bash is allowed, curl and wget still reach any URL, and a sandbox with a network domain allowlist closes that gap (Set up Claude Code for your organization).

Anthropic’s example repository ships settings-strict.json, which asks before every Bash command, denies WebSearch and WebFetch, and sets both allowManagedPermissionRulesOnly and allowManagedHooksOnly. Its README labels these files community-maintained and possibly unsupported or incorrect (GitHub).

What the policy does not reach

Anthropic lists the gaps itself.

GapWhat the docs say
A managed model is a default, not a lock--model and ANTHROPIC_MODEL still pick the model for a session. Use availableModels to restrict the choice (Deploy managed settings).
Local administratorsA developer who is an administrator on the machine can edit the managed source itself. MDM tools can redeploy the file on a schedule.
Other toolsManaged settings bind Claude Code only. Someone who calls the API from another tool is not under them.
Server-managed settings are a client-side controlThe docs say they are “not a security boundary” on unmanaged devices, where a user needs no admin rights to bypass them: running an older Claude Code that predates the feature, or a modified binary, avoids them. A user who sets CLAUDE_CODE_USE_BEDROCK, Vertex, Foundry or a non-default ANTHROPIC_BASE_URL also bypasses them (Server-managed settings).
Cloud sessions and CoworkA session on Anthropic’s hosted environment does not read a device’s profile or file, so those need server-managed settings. Cowork in Claude Desktop never fetches the console settings, and reads the device policy instead, unless a full VM sandbox is required (Deploy managed settings).
API-key fleetsA Console API key belongs to a different organization than your claude.ai plan, so console settings do not reach it. The docs advise MDM or files for those fleets (Model configuration).

If the console fetch fails, the default is to continue on cached settings, and a machine that has never fetched runs without server-managed ones. forceRemoteSettingsRefresh: true reverses that: Claude Code blocks at startup until it fetches fresh settings and exits if it cannot. The docs warn that if api.anthropic.com is unreachable, nobody can start Claude Code (Server-managed settings).

Telemetry: what switching it off costs

To turn off Anthropic’s usage metrics for everyone, put DISABLE_TELEMETRY in the env block of managed settings; Claude Code applies a value of 1 without an approval dialog. The cost: it stops the usage data behind your organization’s analytics dashboard for those developers, and also turns off feature-flag fetching (Deploy managed settings). Remote Control can become unavailable (Data usage). Setting CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC goes further and also covers error reports and surveys. Visibility has a separate route: administrators can point OpenTelemetry export at their own collector through the same env block (Monitoring usage). Turning telemetry off therefore removes Anthropic’s view without removing yours, if you configure the collector.

Checking that it applied

Run /status on one machine and read the Setting sources line. It names Enterprise managed settings and the route in parentheses: (remote), (plist) or (HKLM), (file), (drop-ins), or a list ending in , merged. A second line, Skipped sources, names sources Claude Code found and did not use, which separates a policy that never arrived from one that a higher source overrode. claude doctor lists entries Claude Code dropped, with source and field (Deploy managed settings).

Mistakes have different costs by type. A policy file that is not valid JSON, or whose top level is not an object, makes Claude Code refuse to start, even when another route delivers a valid policy. A root-only file the user cannot read makes sessions start without that source, when no other admin source supplies a policy. An invalid entry in an otherwise valid file is dropped with a warning, except locks such as allowManagedPermissionRulesOnly, which read as their restrictive value until you fix them. And if a deny list cannot be read, Claude Code withholds the allow list so grants never apply without the restrictions beside them. Check the file with a JSON parser before it reaches a fleet. Anthropic’s example README says to test files locally before deploying them (GitHub).

Claude Code is one of several agents with settings an organization or a person has to manage. Claude Code sent users’ email addresses to websites covers a recent privacy report, and AI agents and prompt injection explains why a command filter alone is weak. For how agents hold logins and card details, see How AI agents handle your passwords and payments and Is it safe to connect Gmail to an AI agent?. The Cowork gap above is covered from the user side in How to set up Claude Cowork and Claude Cowork safety. Usage caps are a separate control: AI agent usage limits.

FAQ

Does a managed-settings.json reach the VS Code and JetBrains extensions?

Yes. The docs list the terminal, the VS Code and JetBrains extensions, the Code tab of the desktop app and Agent SDK sessions as reading these sources. Agent SDK sessions load managed settings even when the app excludes the user, project and local files (Deploy managed settings).

My developers use WSL on Windows. Which file do they get?

By default WSL reads only /etc/claude-code. To extend a Windows registry or C:\Program Files\ClaudeCode policy to WSL, set wslInheritsWindowsSettings: true in the HKLM registry or in that Windows file. Claude Desktop turns WSL sessions off on devices it detects as organization-managed unless a registry value enables them (Set up Claude Code for your organization).

Can a developer see why a setting is locked?

/status shows the managed route that applies, and the settings documentation says a managed model is named in the startup header. The settings page tells developers to ask their administrator if a policy should change, because nothing they put in their own files can win (Settings files and precedence).

Yes. Claude Code reads the file the link points to, and the policy still applies when the target is outside the system directory. It then shows a warning naming the file in /status and claude doctor; pointing the link at a target inside the system directory clears it (Deploy managed settings).

Sources

16 pages
  1. Claude Code Docs: Deploy managed settings code.claude.com
  2. Claude Code Docs: Configure server-managed settings code.claude.com
  3. Claude Code Docs: Set up Claude Code for your organization code.claude.com
  4. Claude Code Docs: Settings files and precedence code.claude.com
  5. Claude Code Docs: Settings reference code.claude.com
  6. Claude Code Docs: Configure permissions code.claude.com
  7. Claude Code Docs: Model configuration code.claude.com
  8. Claude Code Docs: Managed MCP configuration code.claude.com
  9. Claude Code Docs: Data usage code.claude.com
  10. Claude Code Docs: Monitoring usage code.claude.com
  11. GitHub: anthropics/claude-code, examples/settings github.com
  12. Claude Help Center: Use Claude Code with your Team or Enterprise plan support.claude.com
  13. The Decoder: Goldman Sachs pulls AI coding tools from traders and bankers (Nov 2, 2026) the-decoder.com
  14. Bloomberg: Goldman restricts traders and bankers from using some AI tools (Nov 2, 2026) bloomberg.com
  15. Tygart Media: Claude Code Managed Settings: Org-Wide Policy Guide tygartmedia.com
  16. Mastering Claude Code: Managed Settings learn.agentpatterns.ai

Spotted something wrong or out of date? Report an error · Corrections log