Deploy managed settings changedmanaged-settings
Nearest release: v2.1.296, published 5 hours before upstream edited the page. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Upstream edited this page at 9 Oct 2026 22:32 UTC, give or take a minute or two: the time comes from Anthropic’s own sitemap rather than from a commit. This site recorded the change at 20 Oct 2026 18:37 UTC.
Upstream edited
Recorded here
Lines+40added
Lines−70removed
From line
10
where the diff opens
First seen
21 Aug 2026
this site's first read of the page
Recorded edits57to this page, all time
### When an admin document counts as present
The whole hunk
from line 10, old and new numbered
/
from line 10
1010
1111This is the quickest way to put a policy on each machine: a `managed-settings.json` file. If you haven't picked how to deliver managed settings yet, or your devices are under MDM or developers run cloud sessions, read [Choose a delivery mechanism](#choose-a-delivery-mechanism) first.
1212
13<Steps>
14 <Step title="Write managed-settings.json">
15 Write a `managed-settings.json` that holds the keys you've decided to enforce, in the same JSON shape as `settings.json`. The [Decide what to enforce](/docs/en/admin-setup#decide-what-to-enforce) table lists the keys behind each control, and each entry in the [settings reference](/docs/en/settings-reference) says whether a managed source can set it. This file blocks two file reads, turns off bypass mode, and makes Claude Code ignore permission rules from user, project, and local files and from `--allowedTools`:
13**1. Write managed-settings.json**
1614
17 ```json managed-settings.json theme={null}
18 {
19 "permissions": {
20 "deny": [
21 "Read(./.env)",
22 "Read(./secrets/**)"
23 ],
24 "disableBypassPermissionsMode": "disable"
25 },
26 "allowManagedPermissionRulesOnly": true
27 }
28 ```
15Write a `managed-settings.json` that holds the keys you've decided to enforce, in the same JSON shape as `settings.json`. The [Decide what to enforce](/docs/en/admin-setup#decide-what-to-enforce) table lists the keys behind each control, and each entry in the [settings reference](/docs/en/settings-reference) says whether a managed source can set it. This file blocks two file reads, turns off bypass mode, and makes Claude Code ignore permission rules from user, project, and local files and from `--allowedTools`:
2916
30 For a fuller example that shows the shape of more managed keys, including the login method, models, MCP servers, and marketplaces, see [An organization's managed settings](/docs/en/settings-example#an-organizations-managed-settings).
31 </Step>
17```json managed-settings.json theme={null}
18{
19 "permissions": {
20 "deny": [
21 "Read(./.env)",
22 "Read(./secrets/**)"
23 ],
24 "disableBypassPermissionsMode": "disable"
25 },
26 "allowManagedPermissionRulesOnly": true
27}
28```
3229
33 <Step title="Place the file on each machine">
34 Save the file as `managed-settings.json` in the system directory for the operating system, using whatever tooling already places files on your fleet:
30For a fuller example that shows the shape of more managed keys, including the login method, models, MCP servers, and marketplaces, see [An organization's managed settings](/docs/en/settings-example#an-organizations-managed-settings).
3531
36 * **macOS**: `/Library/Application Support/ClaudeCode/managed-settings.json`
37 * **Linux and WSL**: `/etc/claude-code/managed-settings.json`
38 * **Windows**: `C:\Program Files\ClaudeCode\managed-settings.json`
39 </Step>
32**2. Place the file on each machine**
4033
41 <Step title="Confirm the policy applied">
42 On one machine, run `/status` inside Claude Code. The `Setting sources` line shows `Enterprise managed settings (file)`. Roll out to the rest of the fleet after that; [Check that a policy is in force](#check-that-a-policy-is-in-force) covers what to look at when the line is missing.
43 </Step>
44</Steps>
34Save the file as `managed-settings.json` in the system directory for the operating system, using whatever tooling already places files on your fleet:
4535
46<span id="managed-settings-delivery" />
36* **macOS**: `/Library/Application Support/ClaudeCode/managed-settings.json`
37* **Linux and WSL**: `/etc/claude-code/managed-settings.json`
38* **Windows**: `C:\Program Files\ClaudeCode\managed-settings.json`
4739
48<span id="delivery-mechanisms" />
40**3. Confirm the policy applied**
4941
42On one machine, run `/status` inside Claude Code. The `Setting sources` line shows `Enterprise managed settings (file)`. Roll out to the rest of the fleet after that; [Check that a policy is in force](#check-that-a-policy-is-in-force) covers what to look at when the line is missing.
43
5044## Choose a delivery mechanism
5145
5246The file in the steps above is one of four ways to get managed settings onto a machine. Every mechanism carries the same policy keys as a `settings.json` file, so the [settings reference](/docs/en/settings-reference) applies to all of them. A few keys are tied to particular sources, and each entry's Scope line says which:
from line 89
9589* **Changes that need approval**: apart from the [updates that wait for the next launch](/docs/en/server-managed-settings#fetch-and-caching-behavior), a server-managed change to a setting that [needs approval](/docs/en/server-managed-settings#security-approval-dialogs), such as a hook or an `env` variable, waits for the developer to accept the dialog in an interactive session, and applies for the current run in a session an IDE extension or the Agent SDK hosts. Other server-managed changes apply on the next poll.
9690* **Long-lived sessions**: a session left open for weeks can still lag a rollout. [`requiredMinimumVersion`](/docs/en/settings-reference#requiredminimumversion) blocks an outdated binary from starting and doesn't end a session that's already running.
9791
98<span id="format-the-policy-for-each-platform" />
99
10092### Where each mechanism stores the policy
10193
10294The keys are the same everywhere, but each mechanism stores them in a different place and shape:
from line 114
122114* **[`extraKnownMarketplaces`](/docs/en/settings-reference#extraknownmarketplaces) and [`managedMcpServers`](/docs/en/settings-reference#managedmcpservers)**: a later entry with the same name replaces the earlier one whole
123115* **[`modelPicker`](/docs/en/settings-reference#modelpicker)**: the later lineup replaces the earlier one whole
124116
125<span id="precedence-within-the-managed-tier" />
126
127<span id="which-managed-source-claude-code-uses" />
128
129117## How Claude Code combines managed sources
130118
131119When your organization delivers more than one managed source to the same machine, the [`managedSourcesBehavior`](/docs/en/settings-reference#managedsourcesbehavior) key decides what Claude Code does with the others:
from line 135
147135
148136This diagram shows the ranking, with examples of the cross-source keys Claude Code reads from the first three sources under either setting:
149137
150<img src="https://mintcdn.com/claude-code/zuWID2B-Rxm8DEC8/images/managed-source-precedence.svg?fit=max&auto=format&n=zuWID2B-Rxm8DEC8&q=85&s=53f6be49f06eff48e01422c8ae1bc2e6" className="dark:hidden" alt="Diagram showing the four managed settings sources ranked from remote settings at the top through MDM, managed settings files, and the HKCU registry at the bottom. By default the first source with a policy key supplies the policy and the rest are skipped; with managedSourcesBehavior set to merge, every admin source with a policy key contributes, combined by kind of key, and the HKCU registry stays out. A side panel shows that cross-source keys such as the sandbox locks, forceRemoteSettingsRefresh, and the per-variable env merge are read from every admin source, which excludes the HKCU registry." width="680" height="330" data-path="images/managed-source-precedence.svg" />
138
151139
152<img src="https://mintcdn.com/claude-code/zuWID2B-Rxm8DEC8/images/managed-source-precedence-dark.svg?fit=max&auto=format&n=zuWID2B-Rxm8DEC8&q=85&s=ae407a9a08a3d680e80cf1a2af845d71" className="hidden dark:block" alt="Diagram showing the four managed settings sources ranked from remote settings at the top through MDM, managed settings files, and the HKCU registry at the bottom. By default the first source with a policy key supplies the policy and the rest are skipped; with managedSourcesBehavior set to merge, every admin source with a policy key contributes, combined by kind of key, and the HKCU registry stays out. A side panel shows that cross-source keys such as the sandbox locks, forceRemoteSettingsRefresh, and the per-variable env merge are read from every admin source, which excludes the HKCU registry." width="680" height="330" data-path="images/managed-source-precedence-dark.svg" />
140### When an admin document counts as present
153141
154<h3 id="present-admin-documents">
155 When an admin document counts as present
156</h3>
157
158142In the [ranking of managed sources](#how-claude-code-combines-managed-sources), Claude Code never applies the user-writable HKCU registry beneath an admin document that is present. A document is present when:
159143
160144* It sets any policy key to a value other than `null`, even a value Claude Code can't read
from line 207
223207
224208For which helper runs fail, and what Claude Code does when one does, see [Helper failures](/docs/en/settings-reference#helper-failures).
225209
226<span id="parent-settings-from-embedding-hosts" />
227
228<span id="control-policy-from-an-embedding-host" />
229
230<span id="merge-policy-from-an-embedding-host" />
231
232210### Let an embedding host add policy
233211
234212When another application launches Claude Code, such as Claude Desktop, an IDE extension, or an Agent SDK app, that host can pass its own managed settings through the SDK `managedSettings` option. Claude Code calls these parent settings.
from line 259
281259* **The server-managed cache**: server-managed settings come from Anthropic's servers, and an edit to the local cache [lasts only until the next successful fetch](/docs/en/server-managed-settings#security-considerations).
282260* **Other tools**: managed settings bind Claude Code only. A developer who calls the API from another tool isn't under them.
283261
284<span id="verify-enforcement" />
285
286<span id="verify-that-a-policy-is-in-force" />
287
288262## Check that a policy is in force
289263
290264A developer reports that a policy isn't applying, or you want to confirm a rollout landed before pushing it to the fleet. Two commands on that machine answer it: `/status` shows which managed source Claude Code selected, and `claude doctor` lists what it dropped.
from line 286
312286 When you deployed through server-managed settings instead, run `claude doctor`, which reports the [fetch outcome](/docs/en/server-managed-settings#verify-settings-delivery).
313287* **The line names a source other than the one you deployed**: a higher-priority source is present and Claude Code ignored yours, and `Skipped sources` lists it. [How Claude Code combines managed sources](#how-claude-code-combines-managed-sources) gives the order.
314288
315<span id="invalid-entries-in-managed-settings" />
316
317289### Find entries Claude Code dropped
318290
319291If your managed settings file, MDM profile, registry value, or server-managed payload fails schema validation, Claude Code first skips each individual entry it can repair, such as one invalid permission rule, and warns about each one. Claude Code then drops any value that still fails, unless the value belongs to one of the keys that [fail closed](#keys-that-fail-closed) instead.
from line 378
406378* While `network.deniedDomains` or any entry in it is invalid, Claude Code also withholds `network.allowedDomains`, so the managed allowlist grants nothing until you fix the deny list.
407379* While `filesystem.denyRead`, `filesystem.denyWrite`, or any entry in either is invalid, Claude Code also withholds both `filesystem.allowRead` and `filesystem.allowWrite` until you fix the deny list.
408380
409<span id="managed-only-settings" />
410
411381## Keys only a managed source can set
412382
413383Claude Code reads the following keys only from a managed source; placing them in user or project settings files has no effect.
from line 410
440410| [`strictPluginOnlyCustomization`](/docs/en/settings-reference#strictpluginonlycustomization) | Block skills, agents, hooks, and MCP servers from user and project sources; `true` locks all four, an array names which |
441411| [`wslInheritsWindowsSettings`](/docs/en/settings-reference#wslinheritswindowssettings) | When set in the HKLM registry or a file under `C:\Program Files\ClaudeCode`, have WSL read the Windows policy chain, and read `/etc/claude-code` only when [no Windows admin document is present](#present-admin-documents); the entry gives the order |
442412
443<Note>
444 On Team and Enterprise plans, an Owner enables or disables [Remote Control](/docs/en/remote-control) and [cloud sessions](/docs/en/claude-code-on-the-web) organization-wide in [Claude Code admin settings](https://claude.ai/admin-settings/claude-code). When an Owner turns Remote Control off, already-connected sessions that run Claude Code v2.1.286 or later disconnect too. Each one disconnects the next time it refreshes your organization's policy, about once an hour. For what happens in those sessions, see [`Remote Control was turned off by your organization's policy`](/docs/en/remote-control#remote-control-was-turned-off-by-your-organizations-policy).
445
446 Remote Control can additionally be disabled per device with the [`disableRemoteControl`](/docs/en/settings-reference#disableremotecontrol) setting. Cloud sessions have no per-device managed settings key.
447
448 To check whether these organization settings reached a given machine, run `claude doctor` there and read the `Organization policy` line, which says where Claude Code loaded the policy from or why it didn't load. Requires Claude Code v2.1.261 or later. In a running session, `/status` shows the same line when the policy didn't load.
449</Note>
413> [!NOTE]
414>
415> On Team and Enterprise plans, an Owner enables or disables [Remote Control](/docs/en/remote-control) and [cloud sessions](/docs/en/claude-code-on-the-web) organization-wide in [Claude Code admin settings](https://claude.ai/admin-settings/claude-code). When an Owner turns Remote Control off, already-connected sessions that run Claude Code v2.1.286 or later disconnect too. Each one disconnects the next time it refreshes your organization's policy, about once an hour. For what happens in those sessions, see [`Remote Control was turned off by your organization's policy`](/docs/en/remote-control#remote-control-was-turned-off-by-your-organizations-policy).
416>
417> Remote Control can additionally be disabled per device with the [`disableRemoteControl`](/docs/en/settings-reference#disableremotecontrol) setting. Cloud sessions have no per-device managed settings key.
418>
419> To check whether these organization settings reached a given machine, run `claude doctor` there and read the `Organization policy` line, which says where Claude Code loaded the policy from or why it didn't load. Requires Claude Code v2.1.261 or later. In a running session, `/status` shows the same line when the policy didn't load.
450420
451421## Turn telemetry off for your organization
452422
No line in this hunk matches that.