How to onboard 1,000 developers to Claude Code without manual setup

Onboard a large group by delivering one managed policy from a central source and checking each machine after it starts. Claude Code applies managed settings above every user, project, local and command-line value, so developers never edit settings files. Verify each machine with /status.

Checked against the Claude Code settings, managed settings, admin setup and server-managed settings docs as of 2026-11-01. The steps assume a Claude for Teams or Enterprise account. Where a step needs a newer CLI, the post says so.

Choose a delivery mechanism for each group

Claude Code reads managed policy from four sources. The docs say that by default it uses the highest-ranked source that delivers at least one policy key and ignores the rest, so pick one primary channel for each group of machines. The table below lists what each one needs.

Mechanism	How you deliver it	When Claude Code reads it	Use it when
Server-managed	claude.ai admin console	At startup, then polled hourly	You want one place to change policy for a Teams or Enterprise organization
MDM or OS policy	macOS profile in `com.anthropic.claudecode`, or Windows `HKLM\SOFTWARE\Policies\ClaudeCode`	At startup, then checked every 30 minutes	Your devices are already enrolled in Jamf, Intune or Group Policy
File-based	`managed-settings.json` in a system directory	At startup, and reloaded when the file changes	Linux hosts, or machine images you build yourself
HKCU registry	`HKCU\SOFTWARE\Policies\ClaudeCode` on Windows	At startup, then every 30 minutes	Only as a fallback where `HKLM` cannot be written. The developer can edit or delete these values, so it is not enforcement

Sources: https://code.claude.com/docs/en/managed-settings (fetched 2026-11-01), https://code.claude.com/docs/en/admin-setup (fetched 2026-11-01), https://code.claude.com/docs/en/server-managed-settings (fetched 2026-11-01).

Keep the policy small and layered

Put rules that must hold for everyone in the managed layer, and leave preferences such as theme or editor mode in user settings. The file format, the OS paths and a worked deny-rule example are in the managed settings guide. This post covers the rollout around that policy.

The Bash(curl *) style of deny rule matches the command text Claude writes. It is not a network boundary, so use a sandbox network allowlist when you need enforcement that does not depend on the command text.

Source: https://code.claude.com/docs/en/managed-settings (fetched 2026-11-01), https://code.claude.com/docs/en/server-managed-settings (fetched 2026-11-01).

Split the policy by owning team

When security, platform and the cost team each own part of the policy, do not edit one shared file. Use the managed-settings.d/ directory next to managed-settings.json. Claude Code merges the main file first, then every *.json file in alphabetical order, so numeric prefixes set the order.

Create managed-settings.d/ in the system directory for the operating system. Use /etc/claude-code/ on Linux and WSL.
Name each file by owner and order, for example 10-telemetry.json and 20-security.json.
Expect single values to take the later file’s value, and lists such as permissions.deny to combine with duplicates removed.
Ignore hidden files and any file that does not end in .json. Claude Code skips them.

The merge rules apply to files in the same managed source. They do not change the precedence between a managed source and a developer’s own files.

Source: https://code.claude.com/docs/en/managed-settings (fetched 2026-11-01).

Know what reaches each developer

Several conditions decide whether a policy arrives. Check these before you widen a rollout, because a missing fetch leaves a developer on whatever policy the machine already has.

Plan and sign-in. Server-managed settings need a Claude for Teams or Enterprise plan and an eligible credential that talks to api.anthropic.com directly.
Console keys. A session that authenticates with a Console API key receives the settings of the Console organization that created the key, not your claude.ai policy.
Shell overrides. If a developer exports CLAUDE_CODE_USE_BEDROCK or a non-default ANTHROPIC_BASE_URL, Claude Code skips the server fetch for that session.
Cloud sessions. A cloud session does not read a device’s MDM profile or managed file. Use server-managed settings for those sessions.
Hooks. Hook definitions trigger a security approval dialog in interactive sessions. A developer who rejects it makes Claude Code exit.

Sources: https://code.claude.com/docs/en/server-managed-settings (fetched 2026-11-01), https://code.claude.com/docs/en/managed-settings (fetched 2026-11-01).

Route gateway traffic through managed policy

Developers who send requests through a gateway need a policy that does not depend on their shell. Exporting ANTHROPIC_BASE_URL in each terminal works for a test, but it skips the server fetch, so those machines get no server-managed policy. For a fleet, deliver the policy through MDM or a managed file, and set the gateway base URL in the same source. The gateway post covers the variables and the credential.

Source: https://code.claude.com/docs/en/server-managed-settings (fetched 2026-11-01), https://code.claude.com/docs/en/settings (fetched 2026-11-01).

Make the rollout fail closed

By default, a failed fetch at startup falls back to the last cached settings. On a machine that has never fetched them, Claude Code continues without server-managed settings. To stop a machine from starting without the policy, set forceRemoteSettingsRefresh to true in a managed source.

Add "forceRemoteSettingsRefresh": true to the managed settings file or the MDM profile.
Confirm that every machine can reach api.anthropic.com.
Accept the trade-off. If the endpoint is unreachable, the CLI exits at startup and developers cannot start Claude Code.

The claude auth subcommands are exempt, so a developer can sign in again when expired credentials cause the fetch to fail.

Source: https://code.claude.com/docs/en/server-managed-settings (fetched 2026-11-01).

Verify each machine before you widen the group

Verification is per machine, so build it into the pilot. Two checks cover most failures.

Run /status in Claude Code. The Setting sources line should show Enterprise managed settings with the source in parentheses: (plist), (HKLM), (file), (drop-ins), (file + drop-ins) or (remote …).
If the line names a different source, either a higher-priority source is present or the intended source did not load. The Skipped sources entry names sources that were found and ignored, but it does not show whether a fetch failed, so check the delivery path as well (step 3).
Run claude doctor on machines that show no managed source. The Managed settings (remote) line reports the fetch outcome. It requires Claude Code v2.1.248 or later.
Run /permissions to see the effective rules after a managed change.

Source: https://code.claude.com/docs/en/managed-settings (fetched 2026-11-01), https://code.claude.com/docs/en/server-managed-settings (fetched 2026-11-01), https://code.claude.com/docs/en/settings (fetched 2026-11-01).

Watch what does not reload on its own

Most changes apply to a running session. The exceptions decide how long a change takes to reach a developer.

Change	When it reaches a session
Server-managed settings	On the next startup, or on the hourly poll
MDM profile or registry value	On the 30-minute check
`model`	Next launch
`permissions`, `hooks` and credential helpers	Running session, after the file reloads

Two more gaps matter at scale. ConfigChange hooks do not run when server-managed settings arrive, or when an MDM profile or registry policy changes. Server-managed settings also cannot deliver managed-mcp.json. Deliver MCP allowlists through the allowedMcpServers and deniedMcpServers keys, or through a file on the machine.

Sources: https://code.claude.com/docs/en/server-managed-settings (fetched 2026-11-01), https://code.claude.com/docs/en/settings (fetched 2026-11-01).

Enforcing this with AIControls

AIControls covers the controls this rollout needs on the coding-agent side. Claude Code can run through the AIControls gateway for the CLI and VS Code, with per-user tokens and per-user and per-session cost and budget limits. Use it alongside the managed policy above, and see the coding agents page and the download page for setup. Read the managed settings guide before you choose a delivery channel.

Frequently asked questions

Do developers have to edit settings files to get the company policy?

No. Managed settings sit above user, project, local and --settings values, so a policy you deliver through the claude.ai console, MDM or a managed-settings.json file applies without the developer doing anything. A developer can still add their own rules, but the managed keys win. Check each machine with /status, which names the managed source in the Setting sources line.

Why do server-managed settings not reach some developers?

The fetch needs a Team or Enterprise login or another eligible credential that talks to api.anthropic.com directly. A Console API key from a different organization gets none of your claude.ai settings. Exporting a non-default ANTHROPIC_BASE_URL or a CLAUDE_CODE_USE_* variable in the shell also skips the fetch. Deliver policy for those machines through MDM or a file instead.

Can a developer remove a managed deny rule?

Managed settings sit above user, project, local and command-line values, so a developer cannot remove a managed deny rule from their own files. Their own rules still apply in their own files, but they cannot change a managed key. Only a developer with local administrator rights can edit the managed file on disk, so have MDM redeploy it on a schedule.

How do I roll out a new policy without breaking sessions?

Pilot it on a small group first, then run claude doctor on a test machine to check the delivered settings. Server-managed settings reach running sessions on the next startup or hourly poll, and some keys, including model, apply only at the next launch. Widen the group after /status shows the new source on the pilot machines.