Claude Code Enterprise Setup: Managed Settings and Policy

Claude Code reads settings from five levels. When the same key is set in several, the higher level wins:

1. Managed settings: from the claude.ai admin console, an MDM profile, or a managed-settings.json file. Set by your organisation. 2. Command line: claude --settings '<json or file>' for one session. 3. Local project: .claude/settings.local.json, personal and not committed. 4. Shared project: .claude/settings.json, committed to the repository. 5. User: ~/.claude/settings.json, across all of one person's projects.

Managed settings use the same JSON shape as settings.json, so anything you can put in a user file you can usually enforce centrally: permission rules, hooks, environment variables, model choice, sandbox options. A few keys only take effect from managed settings and are ignored anywhere else. They exist to stop lower levels from adding their own exceptions:

• allowManagedPermissionRulesOnly: ignore permission rules from user, project, and local files and from --allowedTools.
• allowManagedHooksOnly: run only hooks defined in managed settings.
• allowManagedMcpServersOnly with allowedMcpServers: limit MCP servers to an approved list.
• strictKnownMarketplaces: limit which plugin marketplaces users can add.

Server-managed settings are JSON you paste into the claude.ai admin console. Clients fetch them from api.anthropic.com when users sign in with an eligible credential, such as a Team or Enterprise login, and cache them at ~/.claude/remote-settings.json. You need no device-management tooling, which makes this the practical choice for unmanaged laptops and the only one that reaches cloud sessions.

Endpoint-managed settings live on the device:

• macOS: the com.anthropic.claudecode managed-preferences domain (a configuration profile), or /Library/Application Support/ClaudeCode/managed-settings.json.
• Windows: a Settings value (REG_SZ) under HKLM\SOFTWARE\Policies\ClaudeCode, or C:\Program Files\ClaudeCode\managed-settings.json.
• Linux and WSL: /etc/claude-code/managed-settings.json.

Next to the file you can add a managed-settings.d/ directory. Claude Code merges managed-settings.json first and then every *.json file in that directory in alphabetical order, so the security team can own 20-security.json while the platform team owns 10-telemetry.json.

If several managed sources exist, Claude Code by default uses the first one that delivers a policy key, checking server-managed settings first, then MDM, then files. It does not merge them, apart from a few documented exceptions such as env, which merges per variable. Setting managedSourcesBehavior: "merge" in the highest source opts into combining them.

Start small. This policy keeps secrets out of reads, removes bypass mode, makes the managed rules the only rules, and allows two model families:

1{2  "permissions": {3    "deny": [4      "Read(./.env)",5      "Read(./.env.*)",6      "Read(./secrets/**)",7      "Read(~/.aws/**)"8    ],9    "disableBypassPermissionsMode": "disable"10  },11  "allowManagedPermissionRulesOnly": true,12  "availableModels": ["sonnet", "haiku"]13}

• The deny rules use the normal Tool(specifier) syntax and apply in every permission mode.
• disableBypassPermissionsMode removes bypassPermissions mode and --dangerously-skip-permissions. permissions.disableAutoMode does the same for auto mode if you are not ready for the classifier.
• allowManagedPermissionRulesOnly stops users and repositories from adding their own allow rules. This is strict: every command developers want pre-approved must now be in the managed policy, or they will see more prompts.
• availableModels restricts model selection, covered in the next section.

Expect to add allow rules after a week of feedback, for example Bash(npm test *), Bash(pnpm *), or Bash(git diff *).

availableModels takes model families (sonnet), version prefixes (claude-sonnet-4-5), or full model IDs. It applies wherever a user can choose a model: /model, the --model flag, ANTHROPIC_MODEL, and the model setting. Lower settings levels cannot add to a managed list.

What happens to a blocked choice depends on where it was made. /model rejects the switch with an error. --model, ANTHROPIC_MODEL, or the model setting are replaced at startup with a warning, and the session starts on the default model.

Two details catch administrators out:

1. model is an initial choice, not enforcement. Users can open /model and pick Default, which resolves to the account's runtime default. 2. The Default option is outside availableModels unless you say otherwise. Set enforceAvailableModels: true (Claude Code v2.1.175 or later) to extend the allowlist to Default as well.

1{2  "model": "claude-sonnet-4-5",3  "availableModels": ["claude-sonnet-4-5", "haiku"],4  "enforceAvailableModels": true5}

On Claude Enterprise, admins can also disable models and set an organisation default in the claude.ai admin console. That control travels with the account's entitlements, separately from the availableModels list in settings.

Claude Code exports metrics and events over OpenTelemetry. Turn it on for everyone by putting the variables in the managed env block:

1{2  "env": {3    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",4    "OTEL_METRICS_EXPORTER": "otlp",5    "OTEL_LOGS_EXPORTER": "otlp",6    "OTEL_EXPORTER_OTLP_PROTOCOL": "grpc",7    "OTEL_EXPORTER_OTLP_ENDPOINT": "http://collector.internal:4317"8  }9}

Metrics include claude_code.session.count, claude_code.token.usage, claude_code.cost.usage (USD), claude_code.lines_of_code.count, claude_code.commit.count, claude_code.pull_request.count, and claude_code.active_time.total. Each carries attributes such as organization.id, user.account_uuid, user.email, and session.id, so you can group usage by person or team in your own backend. Events cover prompts, API requests and errors, tool decisions, and permission-mode changes.

Defaults favour privacy. Prompt text is redacted unless you set OTEL_LOG_USER_PROMPTS=1, and tool arguments are left out unless you set OTEL_LOG_TOOL_DETAILS=1. Decide with your legal and security teams before turning either on: prompts and tool arguments can contain source code, customer data, and secrets.

A saved policy is not a delivered policy. Check on a real machine, with a real user login, after every change:

1. Ask the user to restart Claude Code. If the policy has hooks or env values that need approval, they should see the security dialog. 2. Run claude doctor and read the Managed settings (remote) line (v2.1.248 or later). It says whether settings loaded, whether the organisation has none, whether the fetch failed and a cached policy applies, or why the fetch was skipped. 3. Run /permissions and confirm the managed deny rules are listed. 4. Try something the policy forbids: read .env, start with --dangerously-skip-permissions, or /model to a blocked model. Each should fail. 5. If delivery fails, run claude --debug-file /tmp/cc.log and search the log for Remote settings.

If a missing policy must stop work rather than allow it, set forceRemoteSettingsRefresh: true. Claude Code then blocks at startup until it has fetched fresh settings and exits if it cannot. That is fail-closed, and it means an outage of api.anthropic.com or a proxy misconfiguration stops every developer, so allow that endpoint through your network first.

Anthropic's documentation is direct about this: server-managed settings are a client-side control, not a security boundary. The common gaps:

• The fetch is skipped. If a user's shell exports CLAUDE_CODE_USE_BEDROCK, CLAUDE_CODE_USE_VERTEX, another provider variable, or a non-default ANTHROPIC_BASE_URL, Claude Code does not fetch server-managed settings. Keys from an apiKeyHelper script do not trigger the fetch either. Versions older than the feature never fetch.
• The wrong organisation. A session gets the policy of the organisation that owns its credential. A Claude Console API key belongs to a Console organisation, separate from your claude.ai Teams or Enterprise organisation, so a CI job using it does not receive your policy. Use claude setup-token for an OAuth token tied to your organisation, or deploy a managed settings file to the CI runner.
• Local tampering. A user who edits the cached settings file gets the edited version at startup until the next fetch restores it. A user running a modified client can bypass any client-side control.

The stronger options are endpoint-managed settings on MDM-enrolled devices, where the OS stops users from editing the file, and controls outside Claude Code itself: credentials scoped to what the developer may touch, network egress rules, and tenant restrictions that stop logins to personal accounts.

Before touching the whole organisation, test the policy where you can see everything.

1. On a test Linux VM or container, write the starter policy from this guide to /etc/claude-code/managed-settings.json. 2. Start claude as a normal user. Run /status and /permissions and confirm the managed source and rules. 3. Try to read .env, start with --dangerously-skip-permissions, and switch to a model outside availableModels. 4. Switch to Manual mode with Shift+Tab, add .claude/settings.json in a project with "allow": ["Bash(curl *)"], and ask Claude to run curl example.com. With allowManagedPermissionRulesOnly, the project rule is ignored and you still get a prompt. 5. Export CLAUDE_CODE_USE_BEDROCK=1 in the shell, run claude doctor, and read what it says about the server-managed fetch.

Pass criterion: every forbidden action in steps 3 and 4 fails or prompts, /permissions shows only managed rules, and you can explain the step 5 output to your security team.