Rolling Out Claude Code to a Team: Managed Settings and Policy

So far you have used Claude Code on your own. This lesson is about using it with other people. When a whole team or company adopts it, you need shared setup that every developer gets, rules nobody can override, and a way to see usage. After it you will know how a rollout is structured, how to deliver settings to everyone's computers, what is worth enforcing, and how to get developers started. It is written for team leads and administrators, and it is also useful if you are a developer wondering why some of your settings are locked.

Three layers of team setup

Almost everything in this course fits into one of three layers.

Managed by the organization. Settings an administrator delivers to every computer. Developers cannot override them. Use them for rules that must hold everywhere.

Shared in the repository. Files committed to Git so every teammate who clones the project gets the same setup: CLAUDE.md (lesson 12), .claude/settings.json (lesson 14), .claude/rules/ (lesson 13), skills (lesson 16), subagents (lesson 17), hooks (lesson 18), and .mcp.json (lesson 19). Use these for the project's conventions and tools.

Personal to each developer. Their own ~/.claude/ files and .claude/settings.local.json, which stays out of Git. Use these for personal preferences.

Managed settings win over everything. Between the other two, a developer's local file can override the team's shared file. List settings such as permission rules combine, so a developer can add rules to a managed list but not remove from it.

Start with the shared project setup

Even with no administrator at all, a team gets a lot from committing a good project setup. A checklist:

• A short CLAUDE.md with the commands to build, test and lint, and the conventions that are not obvious from the code.
• A .claude/settings.json with shared permission rules, such as allowing npm test and denying reads of .env, plus any hooks the team agrees on.
• Rules, skills and subagents for the repeatable jobs your team does.
• A .mcp.json with project servers, using ${VAR} for secrets (lesson 19).
• A rule in .gitignore for .claude/settings.local.json.

Remember from lesson 14 that some shared settings wait for each person to trust the folder. Allow rules, extra directories and most environment variables apply only after a teammate trusts it, while deny and ask rules apply right away.

Plan the rollout: five decisions

The official administrator guide lays out five decisions, in order:

1. Choose your API provider. Where Claude Code signs in and how it is billed.
2. Decide how settings reach devices. How managed policy gets onto developer computers.
3. Decide what to enforce. Which tools, commands and integrations are allowed.
4. Set up usage visibility. How you track spend and adoption.
5. Review data handling. Retention and compliance.

A sensible way to roll out is to start small. The documentation recommends a pilot group to establish a baseline of usage before a wider rollout. After the pilot, apply a managed baseline, widen to more teams, and review the numbers.

1. Choose an API provider

One catch to plan for: some features need a claude.ai account. Cloud sessions, cloud scheduled tasks, Code Review, Remote Control and the Chrome extension are not available through Console API keys or cloud-provider credentials alone. If you deploy through a cloud provider, decide whether developers also need Teams or Enterprise seats. Single sign-on, user provisioning and seat assignment are set up at the Claude account level, in the administrator guide.

2. Deliver managed settings

Managed settings are the settings your organization deploys to every developer's computer. Claude Code applies them above every other level. They use the same JSON shape as settings.json (lesson 14). Developers cannot override them, apart from a few security-sensitive keys where a stricter lower-level value still counts.

You have four delivery options, listed by priority:

When more than one mechanism delivers a policy to the same computer, Claude Code by default uses one and ignores the others. If your members use a mix of sign-in methods, configure server-managed settings for claude.ai users plus a file or operating-system fallback for everyone else.

Deploy a managed file

The quickest route is a file. Write a managed-settings.json with the keys you want. This example blocks two file reads, turns off bypass mode, and makes Claude Code ignore permission rules from user, project and local files:

1{
2  "permissions": {
3    "deny": [
4      "Read(./.env)",
5      "Read(./secrets/**)"
6    ],
7    "disableBypassPermissionsMode": "disable"
8  },
9  "allowManagedPermissionRulesOnly": true
10}

Place it in the system folder for each operating system:

• 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

If several teams own parts of one policy, put each part in its own file in a managed-settings.d/ folder next to the main file. Claude Code reads managed-settings.json first, then every .json file in that folder in alphabetical order, so name them with number prefixes, such as 10-telemetry.json and 20-security.json. When two files set the same key:

• A single value such as "model": "opus": the later file wins.
• A list such as permissions.deny: the lists combine, with duplicates removed.
• A nested block such as env or sandbox: the blocks merge key by key.

Hidden files and files that do not end in .json are ignored.

When several managed sources reach one computer

A computer can receive policy from more than one place. Claude Code ranks the sources, highest first:

1. Remote settings, delivered from claude.ai as server-managed settings.
2. MDM or operating-system policy: the macOS profile or the Windows HKLM registry.
3. Managed settings files: managed-settings.d/*.json and managed-settings.json, merged together.
4. The Windows HKCU registry, which a user can write, so it is only a fallback.

By default, the key managedSourcesBehavior is "first-wins". Claude Code uses the highest-ranked source that supplies at least one policy key and ignores the others rather than merging them. Set it to "merge" in managed settings and Claude Code combines every admin source: for most keys the higher-ranked value applies, lists are joined, and locks take the strictest value. Merge needs Claude Code 2.1.242 or later. A few keys, such as the sandbox locks, are always read from every admin source.

What a developer can still change

A developer's own settings files, --settings flag and project files never override a managed value. Some things sit outside that rule:

• The model for one session. A managed model is a default, not a lock. --model and ANTHROPIC_MODEL still choose a model, so use availableModels to restrict the choice.
• Local administrators. A developer who is an administrator on the machine can edit the managed file itself. That is why teams redeploy it on a schedule with their MDM tool.
• Other tools. Managed settings bind Claude Code only. Someone calling the API from another tool is not covered.

Check that it worked

On one computer, run /status inside Claude Code and read the Setting sources line. It names the managed source in use:

When Claude Code found a managed source and did not use it, a Skipped sources line names it. That line tells you whether a policy never reached the computer, or reached it and a higher-ranked source overrode it. If the Setting sources line is missing, no managed source with a policy key was found, so check the file path and that the file holds a policy key. For a server-managed policy, claude doctor reports the fetch result.

Check one machine before you roll out to the fleet. A session left open for weeks can lag a rollout, so a newer policy may need a restart to apply.

What happens with a bad file

• If a managed file, MDM profile or registry value cannot be read as a JSON object, Claude Code refuses to start and names the source in an error. Test your file before you push it.
• If a value is the wrong type, Claude Code repairs or drops the single bad entry and warns about it. Interactive sessions show a dialog at startup. claude doctor lists each invalid entry with its source and field.
• Some security keys fail closed. If allowManagedPermissionRulesOnly or disableAutoMode holds a value Claude Code cannot read, it is treated as the restrictive value until you fix it.

3. Decide what to enforce

Each control is a setting key in the managed file. These are the ones to know:

Some of these keys can be set only in managed settings. Putting them in a user or project file has no effect. They are mostly locks, which tell Claude Code to honor only the managed value:

• allowManagedPermissionRulesOnly, allowManagedHooksOnly and allowManagedMcpServersOnly
• strictKnownMarketplaces, blockedMarketplaces and strictPluginOnlyCustomization
• forceRemoteSettingsRefresh, which blocks startup until fresh remote settings arrive
• sandbox.network.allowManagedDomainsOnly and sandbox.filesystem.allowManagedReadPathsOnly

A note about telemetry: turning it off also stops the usage data that feeds your organization's analytics dashboard for the developers the policy reaches, so decide with the dashboard in mind.

Many of these appeared earlier in the course. Permission rules and the bypass setting came in lesson 8, the sandbox in lesson 27, MCP servers in lesson 19, plugin marketplaces in lesson 20, hooks in lesson 18, and effort in lesson 5.

One point about layers: permission rules and the sandbox cover different things. Denying the web fetch tool blocks Claude's own fetch tool, but if shell commands are allowed, curl and wget can still reach any address. The sandbox closes that gap with a network allowlist enforced by the operating system. For a serious policy, use both. For the complete picture of the threat model, see lesson 24.

4. Set up usage visibility

Choose monitoring by what you need to report on:

Lesson 26 covered the cost side in more detail, including rate-limit recommendations by team size and what each limit message means.

5. Review data handling

On Team, Enterprise, Claude API and cloud provider plans, Anthropic does not train models on your code or prompts. Your provider determines retention and compliance. Qualified Enterprise accounts can get zero data retention, and there is a HIPAA configuration for organizations that need it, which turns some features off. If you need request-level audit logs or want to route traffic by data sensitivity, put a gateway between developers and your provider.

Onboard your developers

Give people the same path you followed:

• The quickstart and common workflows pages in the documentation.
• Claude Academy courses such as Claude Code 101 and Claude Code in Action.
• This course, starting with lessons 1 to 5.

For sign-in problems, the common fixes are to run /logout then /login to switch accounts, run claude update if the enterprise sign-in option is missing, and restart the terminal after updating. If someone sees "You haven't been added to your organization yet", their seat does not include Claude Code access, and an admin needs to update it in the admin console.

Mistakes teams make

1. Skipping the pilot. Start small, get a baseline, then expand.
2. Putting rules that must never be broken in CLAUDE.md. Use deny rules or managed settings.
3. Relying on the Windows user registry for enforcement. It is writable without admin rights.
4. Forgetting that developers need a claude.ai seat for some features. Check before you promise them.
5. Not testing the managed file. A file that cannot be read stops Claude Code from starting.
6. Locking everything down on day one. Start with the rules that matter, and add more as you learn.

Quick recap

• Team setup has three layers: managed by the organization, shared in the repository, and personal to each developer.
• Plan a rollout in five decisions: provider, delivery, enforcement, usage visibility and data handling. Start with a pilot.
• Deliver managed settings by the admin console, MDM, a file, or the Windows user registry, and check with /status.
• Enforce what matters with permission rules, lockdown, the sandbox and allowlists, and use CLAUDE.md for guidance only.
• Track usage with OpenTelemetry and the dashboards, and onboard developers with the quickstart and courses.

Try it yourself

If you are the owner of a project, do the shared checklist: write a short CLAUDE.md, commit a .claude/settings.json that denies reads of .env, and add .claude/settings.local.json to .gitignore. Then, on your own computer, create a managed settings file with one deny rule at the path for your system, start Claude Code, and run /status to find Enterprise managed settings (file) in the sources. Remove the file again when you are done. If you manage a team, draft your answers to the five decisions in a short document.

Next lesson: troubleshooting Claude Code.