Put mandatory policy in managed settings

Learning objective

Separate organization-managed, project, and personal configuration scopes and enforce non-negotiable policy through managed settings.

Core idea

Instructions from multiple scopes enter context; settings resolve configuration values. The professional decision is which owner may change each requirement, and whether the deployment channel actually makes that owner’s policy effective on the target session.

A rule copied into every repository is still a repository rule. Contributors can delete it, a newly created repository can omit it, and local configuration can differ. Put mandatory organizational controls in managed settings, then prove the selected managed source carries them. Reserve project settings for team choices and personal settings for individual preferences.

How it works

Assign a requirement to the owner who can change it

The settings scopes distinguish deployment authority:

For ordinary settings values, precedence runs managed, command-line --settings, project local, shared project, then user. This describes the settings stack, not every flag or environment variable. For example, a managed model is a starting default rather than a selection lock; availableModels is the restriction mechanism. Check a setting’s reference entry before claiming that putting its default in managed policy makes it immutable.

Lists such as permissions.allow generally combine across settings files. Permission decisions then evaluate deny before ask before allow, rather than letting a more specific local allow defeat a managed deny. Model lists and ordered settings have their own merge rules; do not generalize list union to availableModels when managed settings define it.

Apply only the locks the requirement needs

A managed deny can coexist with useful team pre-approvals. If the organization prohibits one operation but lets teams approve their own build commands, deploy the prohibition without discarding all team rules.

If policy instead requires central ownership of permission rules, set allowManagedPermissionRulesOnly: true. It ignores allow, ask, and deny rules from user, project, local, and --settings files, and ignores --allowedTools. Command-line --disallowedTools and session deny or ask rules still apply because they add restrictions. On Claude Code v2.1.282 or later, the lock also ignores allowed-tools grants from affected project and personal skills. It is a deliberate loss of team flexibility, not a mandatory companion to every managed deny.

Other managed controls answer different questions. allowManagedHooksOnly restricts hook sources; allowManagedMcpServersOnly makes the managed allowedMcpServers list authoritative while deniedMcpServers still combines from all sources. These settings are not interchangeable. Review the exact restriction and its exceptions before enabling it across the organization; distribution is covered in 7.1.4.

Choose delivery for the actual session

System file locations include /Library/Application Support/ClaudeCode/managed-settings.json on macOS, /etc/claude-code/managed-settings.json on Linux and WSL, and C:\Program Files\ClaudeCode\managed-settings.json on Windows. MDM or OS policy is useful when endpoint administrators own the devices. A local administrator can edit managed sources, so organizational enforcement also depends on device administration.

Server-managed settings are available to Claude for Teams and Enterprise customers and are edited by Primary Owners or Owners. Their delivery requires a direct Anthropic API connection and an eligible credential. A Claude Console API key belongs to its Console organization, so it does not fetch the settings of a separate claude.ai Team or Enterprise organization. Put endpoint-managed policy on an API-key-authenticated runner when that is the chosen delivery route.

Device files and MDM do not travel from a laptop into an Anthropic-hosted cloud session. Server-managed settings provide that route. They apply uniformly across the organization; they cannot deliver one configuration to a pilot group and another to everyone else. Use endpoint-managed targeting or a suitable gateway policy for group-specific delivery.

Verify the selected managed source

By default, managedSourcesBehavior: "first-wins" selects the highest-ranked managed source with a policy key. Remote settings precede MDM or OS policy, which precedes managed files; Windows also has a user-writable HKCU fallback under the documented conditions. Lower sources are skipped, apart from documented cross-source keys. Do not assume an MDM restriction survives because an unrelated remote policy exists beside it.

To compose admin sources, set managedSourcesBehavior: "merge" in the highest-ranked source that delivers policy or this control key. This requires Claude Code v2.1.242 or later. Most values use priority, ordinary lists union, and locks take the strictest value; restriction allowlists such as allowedMcpServers are taken whole from the highest source that sets them. Merge only sources the administrators trust.

Under first-wins a remote policy leaves an MDM restriction skipped; under merge both sources compose.

Run /status and inspect Setting sources; on v2.1.242 or later, Skipped sources also names managed sources not selected. Run claude doctor for rejected configuration entries. A policy file’s presence on disk does not establish that its settings took effect.

Key distinctions and trade-offs

Mandatory restriction versus preferred default: Centrally supplying a value does not necessarily lock the underlying choice. Use the documented lock, such as availableModels, for that purpose.

One authoritative channel versus composition: One channel simplifies attribution. Composition supports multiple administrators but requires per-key merge review and version control over every contributing source.

Managed enforcement versus device authority: Claude Code policy governs Claude Code. Endpoint administration determines whether a developer can replace the policy itself; service authorization still governs access to external systems.

Architecture / decision scenario

A financial-services firm has 80 managed laptops and 8 Console-key CI runners. Security requires approved MCP destinations; application teams need to pre-approve test commands. An architect proposes placing every permission rule in each repository and considers the rollout complete when the file exists.

The platform owner instead deploys managed MCP restrictions, retaining team build approvals because central ownership of every permission is unnecessary. The laptops are meant to receive MDM policy, while a server-managed configuration also exists for cloud sessions; the runners receive a system managed file rather than depending on the separate claude.ai organization’s remote settings. A pilot finds 18 of 20 laptops using the intended source and 2 selecting a remote policy that displaced their MDM configuration. The owner consolidates the policy or deliberately enables managed-source composition, then verifies the result before expanding access.

Common exam traps

• Treating project settings as non-negotiable organization policy.
• Applying settings precedence to accumulated instruction text.
• Assuming every list merges or every managed default is a lock.
• Assuming multiple managed sources all contribute by default.
• Expecting a laptop’s MDM policy to reach a cloud session.
• Enabling allowManagedPermissionRulesOnly without budgeting for lost team approvals.

What to remember

Assign policy by change authority, deliver it through a channel the session reads, and verify the selected source. Managed locks enforce particular restrictions; they do not replace deployment verification or external authorization.

Knowledge check

References

• Anthropic, Settings files and precedence
• Anthropic, Deploy managed settings
• Anthropic, Configure server-managed settings
• Anthropic, Settings reference
• Anthropic, Configure permissions