skip to content

For a Claude Code fleet of MDM-managed laptops, unmanaged contractor machines and cloud sessions, how do you split policy between server-managed and endpoint-managed settings?

level: principalimportance: nice to knowfreq 3%

answer

  1. one reaches the cloud, one is OS-protected
  2. a client-side control, not a boundary
  3. one managed source wins by default
  4. a fetch can be skipped or fail
  5. merging sources is an opt-in

basics

~20 s

Enforce on managed laptops with endpoint-managed settings (MDM or the system file), use server-managed settings for cloud sessions and unmanaged machines, treat the latter as a client-side control, and remember Claude Code applies one managed source by default.

solid answer

~40 s

The two channels have opposite strengths. **Endpoint-managed** settings — an MDM profile, the `HKLM` registry or the system `managed-settings.json` — are protected by the operating system on enrolled devices, but never reach Anthropic-hosted cloud sessions. **Server-managed** settings from the claude.ai console reach any session that authenticates into the organization, including cloud sessions, but are a client-side control: a third-party provider variable or a non-default `ANTHROPIC_BASE_URL` skips the fetch, the local cache can be edited, and the console can't target groups or deliver `managed-mcp.json`. Claude Code ranks server-managed first and by default **uses only one source**, so an MDM policy is ignored once the console delivers any policy key — unless `managedSourcesBehavior: "merge"` (2.1.242+) is set. `forceRemoteSettingsRefresh: true` makes startup fail closed.

go deeper

for a junior

Know that policy can come from the claude.ai console or from files and profiles on the device, and that /status shows which one applied.

for a middle

Explain the source ranking and why, by default, a console policy hides an MDM profile on the same machine.

for a senior

Diagnose skipped fetches, edited caches and first-launch windows, and decide where forceRemoteSettingsRefresh is worth its availability cost.

for a principal

Own the split: weigh device coverage against tamper resistance, choose first-wins or merge per fleet, and say what remains unenforced.

## The two channels Claude Code reads organization policy from **managed settings**, which sit above every developer-controlled level. They arrive through two families of channel. | | Server-managed | Endpoint-managed | | :- | :- | :- | | Delivered by | The claude.ai admin console (Teams or Enterprise, Owner role) or a self-hosted gateway | MDM profile, `HKLM` registry value, or system `managed-settings.json` | | Reaches cloud sessions | Yes | No, apart from a self-hosted runner's image | | Reaches unmanaged machines | Yes, once the user signs in to the organization | Only if someone places the file | | Tamper resistance | Client-side; the cached copy is editable until the next fetch | OS-protected on enrolled devices | | Per-group policy | Not yet | Deploy different profiles per group | | Can carry `managed-mcp.json` or `policyHelper` | No | Yes | ## Where server-managed settings don't hold The documentation is explicit that server-managed settings are **not a security boundary**. They fail to apply when: - The developer exports a `CLAUDE_CODE_USE_*` provider variable or a non-default `ANTHROPIC_BASE_URL`: the fetch is skipped, and a server-delivered `env` block can't undo it because it arrives through the skipped fetch. - The session authenticates with a key from an `apiKeyHelper` script or with workload-identity federation, neither of which triggers the fetch. - The cache is edited (it applies at startup until the next fetch restores it) or deleted (first-launch behaviour returns). - The client predates server-managed settings, or the binary is modified. - On first launch the fetch is still running: Claude Code waits up to five seconds only when the developer signs in at startup, otherwise opens with a brief unenforced window. `claude doctor` reports the fetch outcome on its `Managed settings (remote)` line. ## One source wins by default When several managed sources exist on a machine, Claude Code ranks them: 1. Remote settings — server-managed or gateway 2. MDM or OS-level policy — macOS plist or `HKLM` 3. Managed settings files — `managed-settings.json` plus `managed-settings.d/` 4. The user-writable `HKCU` registry, only when no admin document is present above it Under the default `managedSourcesBehavior` value, `"first-wins"`, Claude Code applies the **highest-ranked source that delivers a policy key** and ignores the rest, without warning; `/status` names the selected and skipped sources. A few cross-source keys are read from every admin source anyway — `allowManagedMcpServersOnly`, `deniedMcpServers`, the sandbox allowlist locks, `forceRemoteSettingsRefresh`, and `env` merged per variable. Most other keys in the MDM profile, including `forceLoginOrgUUID`, are ignored as soon as the console delivers any policy key. Since Claude Code 2.1.242, `managedSourcesBehavior: "merge"` in the highest-ranked source applies every admin source: lists union, locks take the strictest value, restriction allowlists come whole from the highest source that sets one. Because lower sources' `allow` rules and hooks then join the policy, merge is safe only when every lower source is administrator-controlled. ## Failing closed By default a failed startup fetch falls back to the cached policy, or to none on a fresh machine. `forceRemoteSettingsRefresh: true` blocks startup until a fresh fetch succeeds and exits otherwise; it caches itself and can be set in an endpoint source too, so it holds from the first launch. The cost is availability: if `api.anthropic.com` is unreachable, nobody starts Claude Code, though `claude auth` subcommands stay usable for re-authentication. ## A defensible split 1. Put the enforceable baseline — deny rules, the `allowManaged…Only` locks, login pinning, `managed-mcp.json` — on MDM-enrolled laptops. 2. Mirror the policy in the console for cloud sessions and for contractor machines that can't be enrolled. 3. Decide deliberately between `"first-wins"` with duplicated keys and `"merge"` across sources you control. 4. Add `forceRemoteSettingsRefresh` where an unenforced start is worse than a blocked one. 5. Verify each machine class with `/status` and `claude doctor`. ## The tradeoff There is no single right answer, only trades to make explicitly: - **Endpoint delivery** buys tamper resistance at the cost of device coverage — it does nothing for cloud sessions or machines you can't enroll. - **Server delivery** buys coverage at the cost of enforcement strength — a shell export or an edited cache can step around it. - **Fail-closed startup** buys certainty at the cost of availability — an outage on the path to `api.anthropic.com` stops every developer. - **Merging sources** buys composability at the cost of predictability — every lower source becomes part of the policy. Write down which risks remain unenforced on each machine class; that list is the honest output of the design.

  • A contractor exports `CLAUDE_CODE_USE_BEDROCK=1` in their shell. What happens to the organization's console policy, and how do you fix it?
    Claude Code skips the server-managed fetch for those sessions, and `claude doctor` and `/status` report the skip and its cause. A server-delivered `env` block can't clear the export because it arrives through the skipped fetch. Remove the export, set the variable to an empty string in user settings, or enforce through endpoint-managed settings instead.
  • When is `managedSourcesBehavior: "merge"` risky?
    Under merge, lower sources' list entries — such as `permissions.allow` rules and hooks — are added to the policy. If any lower source isn't under an administrator's control, it can widen what the organization grants. It also has to be set in the highest-ranked source, because a lower source can't opt itself into merging.

  • Server-managed settings are a security boundary that users can't get around.
  • With both console and MDM policy present, Claude Code merges them by default.
  • An MDM-delivered managed settings file also reaches Anthropic-hosted cloud sessions.
  • forceRemoteSettingsRefresh makes Claude Code fall back to cached settings when offline.
  • The admin console can already push a different policy to each group.

Assumes Claude Code 2.1.286; managedSourcesBehavior "merge" and the Skipped sources line in /status require 2.1.242 or later, and first-wins is the default.