Claude Code managed settings: enforce agent guardrails across a team

The short answer

Write a managed-settings.json in the same JSON shape as settings.json, and place it at /Library/Application Support/ClaudeCode/managed-settings.json on macOS, /etc/claude-code/managed-settings.json on Linux and WSL, or C:\Program Files\ClaudeCode\managed-settings.json on Windows. Claude Code applies managed settings above every other level, so no user, project, local or --settings value overrides them.¹ Run /status on one machine; the Setting sources line should show Enterprise managed settings (file).¹

Why managed, and not a shared settings.json

A committed .claude/settings.json is a good default for a team, and it’s weaker than it looks:

Lists such as permissions.allow merge across files, so a developer’s own allow rules add to the team’s.² That’s why the key below matters.

Where the file goes

Four delivery mechanisms carry the same keys:¹

When more than one mechanism delivers a policy, Claude Code by default uses one and ignores the others, so pick one per fleet.¹

A starter policy for agent safety

The docs’ own minimal example blocks two file reads, turns off bypass mode and makes Claude Code ignore permission rules from user, project and local files:¹

Code Data in JSON, the format software uses to pass records and settings.

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./secrets/**)"
    ],
    "disableBypassPermissionsMode": "disable"
  },
  "allowManagedPermissionRulesOnly": true
}

What each line buys you:

• deny on Read keeps the built-in Read tool off secret files. It doesn’t cover every shell command; our post on agents reading .env files lists the gaps.
• disableBypassPermissionsMode removes the mode in which nothing asks.
• allowManagedPermissionRulesOnly stops developers’ own allow rules from widening access. Without it, a “Yes, and don’t ask again” click in any project writes an allow rule that applies alongside yours.²

Extending it for agent work, using keys the docs describe elsewhere:

• The sandbox (sandbox.enabled, denyRead for credential folders, a short allowedDomains list), so shell commands can’t write outside the project or reach arbitrary hosts. Our sandbox settings post has a full example.
• ask rules for remote and destructive commands, such as Bash(ssh *), so a person confirms each one. The ALTER TABLE over SSH report is the case for that.
• Managed MCP servers, deployed through managed-mcp.json or the managedMcpServers key, so the servers developers can connect are the ones you chose.¹

Write the file, then validate it: entries Claude Code can’t parse are reported, and claude doctor lists what it dropped.¹

Roll out in two steps

Turning on allowManagedPermissionRulesOnly on day one tends to break people’s work: every command they’d approved for themselves starts prompting again. A gentler path:

1. Week one: deny rules and bypass off only. These remove the dangerous options without touching anyone’s allow list. Ask developers to send you the commands they approve most often.
2. Week two: your allow list plus allowManagedPermissionRulesOnly. Put the common, safe commands (tests, linters, git status) in the managed allow list, then switch off personal allow rules.

The goal is fewer prompts for safe work and no way around the rules for unsafe work. Approval fatigue is how “always allow” spreads.

Confirm it applied

On one machine before rolling out:¹¹

1. Run /status. The Setting sources line names the managed source in use, such as Enterprise managed settings (file).
2. Run claude doctor to see entries it rejected.
3. Try something the policy blocks: ask Claude to read .env. It should be refused.
4. Try a developer override: add an allow rule to .claude/settings.local.json for something the policy denies. It shouldn’t take effect.

If /status names a different source than the one you deployed, a higher-priority managed source is present.

What developers can still change

The docs list what sits outside the rule that managed values win:¹

The last row is the important one for agent safety. If your team also uses Cursor, Codex or Gemini CLI, each needs its own policy, and none of these settings protects a production database from a script run outside any agent. Credentials are the control that covers every tool: an agent can’t misuse a production key it never had.

A rollout checklist

• One delivery mechanism chosen per fleet.
• Deny rules for secret files; disableBypassPermissionsMode.
• allowManagedPermissionRulesOnly: true once your own allow list covers daily work.
• Sandbox on, with credential folders in denyRead.
• Ask rules for SSH and destructive database commands.
• MCP servers managed centrally.
• Verified on one machine with /status, claude doctor and a blocked read.
• A PreToolUse hook deployed for checks rules can’t express.
• Equivalent policies for the other coding agents your team uses.

To see what an agent could do under your current settings, paste a config into the check page or run npx deedglass scan (how the grade works), which reads .claude/settings.json but not managed settings; to try tool-call rules in your browser, open the playground.

Written with AI assistance and checked against our claims register.