Deploy managed settings - Claude Code Docs
Documentation Index Fetch the complete documentation index at: /docs/llms.txt Use this file to discover all available pages before exploring further. Skip to main content Assistant Responses are generated using AI and may contain mistakes. Managed settings are the settings your organization deploys to every developer’s machine. Claude Code applies them above every other level, so no user, project, local, or --settings value overrides them, apart from a few security-sensitive exceptions where a stricter value from a lower level still counts.
This page is for the administrator who deploys managed settings or debugs why one isn’t applying. To decide what to enforce, start with the Decide what to enforce table. For the claude.ai console path, see Server-managed settings . For which file a developer’s own values go in, see Settings . Deploy a managed settings file This 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 first.
1 Write managed-settings.json 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 table lists the keys behind each control, and each entry in the 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 : managed-settings.json { "permissions" : { "deny" : [ "Read(./.env)" , "Read(./secrets/**)" ], "disableBypassPermissionsMode" : "disable" }, "allowManagedPermissionRulesOnly" : true } 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 .
2 Place the file on each machine Save the file as managed-settings.json in the system directory for the operating system, using whatever tooling already places files on your fleet: 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 3 Confirm the policy applied 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 covers what to look at when the line is missing. Choose a delivery mechanism The 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 applies to all of them.
A few keys are tied to particular sources, and each entry’s Scope line says which: Delivery controls : policyHelper , wslInheritsWindowsSettings , and managedSourcesBehavior Gateway login keys : forceLoginGatewayUrl , gatewayInternalNetworks , and the "gateway" value of forceLoginMethod With a managed settings file or an MDM profile, everyone it reaches gets one policy. To give one group of developers a different policy, deploy a different file or profile to that group.
On an Enterprise plan, you can also give each group its own configuration in server-managed settings. A self-hosted Claude apps gateway delivers managed settings per IdP group. When more than one mechanism delivers a policy to the same machine, Claude Code by default uses one and ignores the others. How Claude Code combines managed sources gives the order and the opt-in that applies every source. The MDM and file rows are together called endpoint-managed settings, because the policy is stored on the developer’s device, as opposed to the server-managed row, where Claude Code fetches it.
Pick a mechanism by how you already manage devices, using the table below. Mechanism How you deliver it When Claude Code reads it Use it when Server-managed settings In the claude.ai admin console, or on a self-hosted Claude apps gateway Fetched at startup and polled hourly; see changes that need approval You want one place to change policy for a claude.ai organization without touching each machine MDM or OS-level policy As a macOS configuration profile or a Windows HKLM registry value, through Jamf, Intune, Group Policy, or a similar tool; see where each mechanism stores the policy Read at startup and checked for changes every 30 minutes You already manage devices with MDM or Group Policy File-based As managed-settings.json in a system directory on each machine; see where each mechanism stores the policy Read at startup and reloaded when a file changes Machines without MDM, Linux hosts, or images you build yourself HKCU registry, Windows and WSL As a Windows HKCU registry value; see where each mechanism stores the policy Read at startup and checked for changes every 30 minutes; Claude Code uses it only when no admin document is present above it and no host-supplied parent settings supply a restrictive key You can’t write the machine-level HKLM key Starter templates for Jamf, Iru, Intune, and Group Policy are in the MDM examples repository .
If your organization has the HIPAA configuration applied, see settings-hipaa.json and README-hipaa.md in the settings examples repository for a fuller managed-settings.json with sandboxing, a network allowlist, credential protections, and local data retention. For managed MCP servers, which you deploy alongside any of these through managed-mcp.json or provide through the managedMcpServers key, see Managed MCP configuration .
Where and when a policy applies A deployed policy reaches the developer’s sessions as follows: Surfaces : on the developer’s machine, the terminal, the VS Code and JetBrains extensions, the desktop app’s Code tab, and Agent SDK sessions read all of these sources. Agent SDK sessions load managed settings even when settingSources excludes the user, project, and local files. Cloud sessions : a session in an Anthropic-hosted environment doesn’t read a device’s MDM profile or file, so policy for it has to come from server-managed settings.
A session in a self-hosted environment also reads the managed settings file in its runner image, by default only when server-managed settings deliver no policy key, apart from the keys Claude Code reads from every admin source . How Claude Code combines managed sources covers the opt-in that applies both. Claude Tag sessions : Claude Tag sessions run in cloud environments but don’t receive server-managed settings. In a self-hosted environment , they still read the managed settings file in the runner image.
Configure Claude Tag itself in the Claude Tag admin settings . Cowork sessions : Cowork in the Claude Desktop app runs its sessions on Claude Code. In a Cowork session, Claude Code never fetches server-managed settings from the claude.ai admin console, even when the user signs in with a Team or Enterprise account, so which policy applies depends on where the session runs: On the user’s machine : by default, Claude Code in a Cowork session reads the MDM or OS-level policy and the managed settings file on that device, so deploy policy there.
In a full VM sandbox : when your Claude Desktop managed configuration sets requireCoworkFullVmSandbox , Claude Code runs inside a virtual machine where the device’s MDM policy and managed settings file aren’t present. Remote Cowork sessions : these run on Anthropic-managed VMs, where Claude Code has no device policy to read. Wherever the session runs, claude.ai applies the admin console’s strictKnownMarketplaces and blockedMarketplaces lists itself when anyone adds a marketplace from a git repository on claude.ai or from Customize in Cowork.
How restrictions work describes that check. The surface coverage table compares Cowork with the other surfaces. Running sessions : most c
The rest of this page is on the live site.