Where does an administrator place Claude Code's managed-settings.json on macOS, Linux and Windows, and how do you confirm a session enforces it?
answer
- a system directory, not the home folder
- same JSON shape as settings.json
- MDM profile or HKLM registry instead
- managed-settings.d drop-ins merge alphabetically
- /status Setting sources line
basics
~10 sIn the system directory: /Library/Application Support/ClaudeCode/ on macOS, /etc/claude-code/ on Linux and WSL, C:\Program Files\ClaudeCode\ on Windows. Then run /status and look for Enterprise managed settings (file) on the Setting sources line.
solid answer
~40 sManaged settings use the same JSON shape as `settings.json` and sit above every other level, so no user, project, local or `--settings` value overrides them. File-based delivery puts `managed-settings.json` in a system directory: `/Library/Application Support/ClaudeCode/` on macOS, `/etc/claude-code/` on Linux and WSL, `C:\Program Files\ClaudeCode\` on Windows; an optional `managed-settings.d/` beside it holds drop-in files merged alphabetically. The same keys can arrive instead as a macOS configuration profile, a Windows `HKLM` registry value, or server-managed settings from the claude.ai admin console. To confirm, run `/status` on the machine: the `Setting sources` line shows `Enterprise managed settings` with the source in parentheses, and `Skipped sources` names any source a higher one overrode. `claude doctor` lists entries that were dropped as invalid.
go deeper
Know that an organization can deploy settings a developer cannot override, and that /status shows whether they reached your machine.
Name the system directory per operating system, the MDM and server-managed alternatives, how drop-in files merge, and what the Setting sources line reports.
Diagnose a policy that isn't applying: missing line versus a skipped source, a refused start on bad JSON, and dropped entries in claude doctor.
Choose the delivery channel from how the fleet is already managed, and plan for administrators with local rights who can edit the file.
## What managed settings are **Managed settings** are the settings an organization deploys to every developer's machine. Claude Code applies them above every other level — user, shared project, local project and the `--settings` flag — so a developer's own files cannot override a managed value. A handful of security-sensitive keys are the exception in one direction only: a *stricter* value from a lower level can still count. The file uses exactly the same JSON shape as `settings.json`, so any key the settings reference marks as settable by a managed source can go in it. ## Four ways to deliver the same keys | Mechanism | Where the policy lives | When Claude Code reads it | | :- | :- | :- | | Server-managed | The claude.ai admin console (Teams and Enterprise, Owner or Primary Owner role) | Fetched at startup, polled hourly | | MDM or OS policy | macOS managed preferences domain `com.anthropic.claudecode`; Windows value `Settings` under `HKLM\SOFTWARE\Policies\ClaudeCode` | At startup, then checked every 30 minutes | | File | `managed-settings.json` and `managed-settings.d/` in the system directory | At startup, reloaded when a file changes | | HKCU registry | `Settings` under `HKCU\SOFTWARE\Policies\ClaudeCode` | Only when no admin document is present above it; it is user-writable | The MDM and file rows are called **endpoint-managed** settings because the policy is stored on the device. ## The file and its drop-ins The system directories are: - **macOS**: `/Library/Application Support/ClaudeCode/managed-settings.json` - **Linux and WSL**: `/etc/claude-code/managed-settings.json` - **Windows**: `C:\Program Files\ClaudeCode\managed-settings.json` — the legacy `C:\ProgramData\ClaudeCode` path is not read When several teams own parts of the policy, each part can live in its own `*.json` file in `managed-settings.d/` next to the main file. Claude Code merges `managed-settings.json` first, then the drop-ins in alphabetical order, so numeric prefixes such as `10-telemetry.json` and `20-security.json` control the order. Single values from a later file replace earlier ones, lists such as `permissions.deny` combine with duplicates removed, and nested blocks such as `env` merge key by key. ## Confirming the policy is in force Verify on one machine before rolling out to the fleet: 1. Start Claude Code and run `/status`. 2. Read the **`Setting sources`** line. With a policy in force it lists `Enterprise managed settings` and the selected source: `(file)`, `(drop-ins)` or `(file + drop-ins)` for the file, `(plist)` or `(HKLM)` for MDM, `(remote)` for server-managed. 3. Read **`Skipped sources`** if present: it names a source Claude Code found but did not select because a higher-ranked one delivered policy. 4. Run `claude doctor` to list any entry dropped for failing validation, with its source and field. If the managed line is missing entirely, Claude Code found no source with a policy key: check the path for the operating system and that the file holds a real policy key. A file that isn't valid JSON doesn't produce a missing line — Claude Code **refuses to start** and names the broken source. ## Where a deployed policy reaches The same managed sources apply on every surface that runs on the developer's machine, with a few boundaries worth knowing: - **Local surfaces**: the terminal, the VS Code and JetBrains extensions, the desktop app's Code tab and Agent SDK sessions all read them; an SDK session loads managed settings even when `settingSources` excludes the user, project and local files. - **Cloud sessions** in Anthropic-hosted environments don't read a device's MDM profile or file, so their policy has to come from server-managed settings. - **Running sessions** pick up most changes on the schedule in the table above, without a restart; a few keys wait for the next session start. ## What a developer can still change Managed means "not overridable by the developer's settings", not "impossible to change": - A managed `model` is a default, not a lock: `--model` and `ANTHROPIC_MODEL` still pick the session's model, so restriction needs `availableModels`. - A developer with local administrator rights can edit the file itself, which is why device-management tools redeploy it on a schedule. - Managed settings bind Claude Code only; another tool calling the API is not under them. ## Summary Put the JSON in the operating system's system directory (or deliver the same keys through MDM or the admin console), then let `/status` prove which source is active before trusting the rollout.
- You deployed the file, but `/status` shows `Enterprise managed settings (remote)`. Why isn't your file applying?By default Claude Code uses only the highest-ranked managed source that delivers a policy key — server-managed, then MDM, then the file — and ignores the rest apart from a few cross-source keys. Server-managed settings from the admin console outrank your file, so `Skipped sources` lists it. Move the keys into the selected source, or opt in to merging sources with `managedSourcesBehavior`.
- What does Claude Code do when the managed settings file has a JSON syntax error?It refuses to start and prints an error naming the source, even if another admin source delivers a valid policy. That is deliberate: a broken policy must not silently fall back to no policy. An individual invalid entry inside valid JSON is different — Claude Code skips it with a warning, and `claude doctor` lists it.
- Managed settings go in ~/.claude/managed-settings.json in the user's home.
- A developer's --settings flag overrides managed values for one session.
- On Windows the managed file lives under C:\ProgramData\ClaudeCode.
- A malformed managed file is skipped and Claude Code starts on user settings.
- A managed model key locks every developer to that one model.