skip to content

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?

level: middleimportance: must knowfreq 12%

answer

  1. a system directory, not the home folder
  2. same JSON shape as settings.json
  3. MDM profile or HKLM registry instead
  4. managed-settings.d drop-ins merge alphabetically
  5. /status Setting sources line

basics

~10 s

In 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 s

Managed 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

for a junior

Know that an organization can deploy settings a developer cannot override, and that /status shows whether they reached your machine.

for a middle

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.

for a senior

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.

for a principal

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.