Claude Code admin controls: a complete guide for IT and DevOps teams (2026)

Why Claude Code needs admin controls in the first place

When you roll out a coding agent to an engineering org, the risk profile is different from deploying a chat tool. Claude Code can run shell commands, read files across an entire codebase, open pull requests, and - if given the right permissions - reach the internet or write to secrets files. Without controls, two failure modes show up: developers lock into cautious usage and confirm every action manually, or they grant blanket permissions and end up with an agent that can technically do anything.

Neither is what you want. What you actually want is something closer to Group Policy for AI: you define what the tool is allowed to do at the org level, developers get a productive environment within those bounds, and you have audit capability if anything goes wrong.

That's what Claude Code's admin controls are designed to be. Let's walk through each layer of the system.

The four-scope configuration hierarchy

Every Claude Code setting resolves through a precedence stack. From highest to lowest priority:

1. Managed - deployed by IT, highest priority, cannot be overridden by anything
2. CLI arguments - session-only overrides (--model sonnet, --permission-mode plan)
3. Local project (.claude/settings.local.json) - personal overrides for this repo, gitignored
4. Shared project (.claude/settings.json) - team-shared, committed to git
5. User (~/.claude/settings.json) - personal global defaults

The managed layer is the ceiling and user settings are the floor. Project settings are where teams standardize tooling. Array-valued settings like permissions.allow merge across scopes rather than replace each other - so an allow rule in user settings stacks with an allow rule in project settings. Scalar values follow winner-take-all from the highest scope that defines them.

One nuance worth knowing: auto mode is ignored when set in project or local settings as of v2.1.142. If you're setting defaultMode: "auto" in a project config and wondering why it has no effect, that's why - it has to come from user or managed settings.

Deploying managed settings

Four delivery mechanisms, all reading the same JSON format:

Server-managed (Teams/Enterprise): Push settings from the admin console in claude.ai. Requires a Claude for Teams or Enterprise plan. Use forceRemoteSettingsRefresh: true to block session startup until the push confirms - useful when your policy update needs to take effect before any developer can continue working.

macOS MDM (Jamf, Kandji, Mosyle): Deploy a configuration profile targeting the com.anthropic.claudecode plist domain. Top-level keys mirror the JSON field names; nested settings use plist dictionaries, arrays use plist arrays. Standard approach for orgs already managing Macs with MDM.

Windows Group Policy / Intune: Write JSON to HKLM\SOFTWARE\Policies\ClaudeCode with a Settings value of type REG_SZ. Deploy via Group Policy Object or an Intune configuration profile. For user-level policy only (when no admin-level source is present), use HKCU\SOFTWARE\Policies\ClaudeCode.

File-based: Drop managed-settings.json at:

• macOS: /Library/Application Support/ClaudeCode/
• Linux / WSL: /etc/claude-code/
• Windows: C:\Program Files\ClaudeCode\

File-based also supports a managed-settings.d/ drop-in directory in the same location. Files sort alphabetically and deep-merge - scalars from later files win, arrays concatenate and deduplicate. Useful if multiple security tools or teams need to contribute separate policy fragments without overwriting each other.

For dynamic policy derived from device posture or a remote compliance service, the policyHelper key points at an executable that computes settings JSON at startup. The binary writes a JSON envelope (with settings under a managedSettings key) to stdout, and Claude Code picks it up before the session starts. Available since v2.1.136.

To verify what's active, run /status inside Claude Code. The Status tab shows a Setting sources line listing every active layer, with the delivery channel in parentheses: Enterprise managed settings (remote), (plist), (HKLM), (file).

Permissions: allow, ask, and deny rules

The permissions system is how you express what Claude can do without asking and what it can't touch at all. Three rule types:

• Allow - Claude runs the tool automatically, no prompt
• Ask - Claude prompts the developer before running (default for most tools)
• Deny - Claude cannot use the tool at all

Rules follow the format Tool or Tool(specifier). A bare deny like "Bash" removes the entire tool from Claude's context so Claude never even tries to use it. A scoped deny like "Bash(rm *)" keeps the tool available but blocks matching calls at runtime.

Evaluation order is always deny first, then ask, then allow - and the first matching rule wins regardless of which scope it came from. A deny in user settings blocks a project-level allow. A managed deny cannot be unlocked by any lower scope.

A practical baseline in .claude/settings.json for a team environment:

This auto-approves common dev commands while blocking network tools and sensitive file reads.

Permission rule patterns to know

Wildcards match across arguments. Bash(npm run *) matches npm run test --watch - the * spans multiple arguments including spaces. Bash(git *) matches git log --oneline --all. A space before * enforces a word boundary: Bash(ls *) matches ls -la but not lsof.

URL-constrained curl is fragile. Bash(curl http://github.com/ *) breaks on curl -X GET http://github.com/... (options before URL), curl https://github.com/... (different protocol), or environment variables holding the URL. For reliable domain restriction, use WebFetch(domain:github.com) for allowed domains and deny Bash network tools entirely. The full explanation is in the permissions reference.

Compound commands split before matching. An allow rule for npm test does not cover npm test && curl evil.com. Claude Code splits on &&, ||, ;, | and checks each subcommand independently.

Read/Edit patterns follow gitignore syntax. Read(./.env) and Read(**/.env) are equivalent - both block any .env at or under the current directory. Use Read(//**/.env) to block .env files anywhere on the filesystem.

Permission modes

Six permission modes change how unmatched tool calls are handled:

Set defaultMode in settings to lock the starting mode. To prevent bypassPermissions mode from ever activating, add to your managed settings:

This closes the --dangerously-skip-permissions flag entirely - developers see an error if they try to use it. Same pattern for auto mode: "disableAutoMode": "disable".

Managed-only settings: the admin-only lockdown controls

Several settings only take effect when deployed via managed settings. Placing them in user or project files has no effect - they're genuinely admin-only:

The combination of allowManagedPermissionRulesOnly: true + allowManagedHooksOnly: true gives you a hard perimeter: no developer can expand what Claude is authorized to do beyond what your managed settings define. Everything runs through IT-approved rules and hooks, nothing more.

Sandbox: OS-level filesystem and network isolation

The sandbox is a separate security layer from permissions. Permissions govern what Claude tries to do. The sandbox enforces what Bash commands can actually reach at the OS level - using macOS's native process isolation (Seatbelt) and Linux seccomp/namespaces to enforce filesystem read/write boundaries and network access rules.

A baseline sandbox config for a developer machine:

With autoAllowBashIfSandboxed: true (the default), Bash commands that stay within sandbox boundaries run without prompting - the sandbox boundary substitutes for per-command confirmation dialogs. Developers get faster flow; you get enforcement.

Three managed-only sandbox flags are worth knowing for stricter environments:

• sandbox.network.allowManagedDomainsOnly: true - only domains in managed allowedDomains are reachable; project-level additions are ignored
• sandbox.filesystem.allowManagedReadPathsOnly: true - only managed filesystem.allowRead paths are honored
• sandbox.network.allowUnixSockets - required on macOS to allow Docker socket access (/var/run/docker.sock)

The sandbox applies only to Bash commands and their child processes. It does not restrict Claude's built-in Read/Write tools - those are governed by the permission rules above. Use both layers together for defense in depth: permission rules block Claude from attempting unauthorized access, and the sandbox prevents anything that slips through at the OS level.

For container, CI, and WSL environments, see Anthropic's sandboxing guide - the configuration differs in those environments.

Hooks for policy enforcement

Hooks are shell commands, HTTP endpoints, or LLM-evaluated prompts that fire at specific lifecycle points. For admin use, PreToolUse is the key event: it fires before any tool call and can block the call before it happens - even if an allow rule would otherwise permit it.

A shell-based security hook that blocks destructive commands:

The hook receives the full tool call as JSON on stdin. To block:

Exit code 0 with no output means "no decision" - normal permission flow continues. The hook can deny, but silence does not approve.

For HTTP-based centralized policy, use type: "http" to post tool call events to your security service and read the decision from the response. This lets a central team run policy evaluation without distributing shell scripts to every developer machine.

Two other events worth using for governance:

• ConfigChange - fires when a settings file changes mid-session. Use this to detect when developers modify their permission rules during a session, and post to your SIEM or Slack for visibility.
• SessionStart - fires at session open. Good for injecting audit metadata, checking version requirements, or confirming the user is on-network before allowing sensitive operations.

With allowManagedHooksOnly: true in managed settings, only hooks deployed via your managed channel run. Developer-authored hooks in project .claude/settings.json are silently ignored. See the full hooks reference for every available event.

Network and proxy configuration

For environments that route traffic through a corporate proxy, Claude Code reads standard proxy environment variables:

Set these in the env block of managed settings so they apply to every session without developer configuration:

For enterprise TLS inspection (CrowdStrike Falcon, Zscaler), Claude Code trusts both its bundled Mozilla CA set and the OS certificate store by default. If your proxy uses a custom CA not in the OS store:

For mutual TLS authentication:

Your firewall allowlist needs these URLs at minimum:

When deploying through Amazon Bedrock, Google Vertex AI, or Microsoft Foundry, model traffic goes to your cloud provider rather than api.anthropic.com. Set CLAUDE_CODE_USE_BEDROCK=1 (or the equivalent) in the env block and configure ANTHROPIC_BEDROCK_BASE_URL if routing through an LLM gateway. Full cloud provider setup is in Anthropic's third-party integrations guide.

MCP and plugin governance

MCP servers extend Claude with external tool integrations - Jira, Notion, GitHub, internal databases. From a governance standpoint, the risk is developers connecting to untrusted servers or installing unvetted marketplace plugins.

Controlling MCP access via managed settings:

With allowManagedMcpServersOnly: true, project .mcp.json files are ignored - only servers in the managed allowlist run. Denylist entries still merge from all scopes, so any scope can block a server even when the allowlist is in effect.

Controlling plugin marketplaces:

strictKnownMarketplaces with a specific list means developers can only add marketplaces on that list. An empty array [] blocks all new marketplace additions entirely. blockedMarketplaces is enforced before network or filesystem operations - blocked sources never touch the disk.

strictPluginOnlyCustomization goes further, requiring all skills, agents, hooks, and MCP servers to come from plugins rather than user or project files:

Pass true to lock all four surfaces (skills, agents, hooks, MCP) or an array naming just the ones you want locked. This ensures all Claude Code customization in your org flows through approved, distributed plugins rather than ad-hoc developer configuration. See the Claude Code plugin overview for context on what the plugin system enables.

CLAUDE.md as org-wide context

CLAUDE.md files are the instruction layer - they tell Claude what to prioritize, while settings files define what it's allowed to do. The claudeMd managed setting injects org-wide instructions into every session, regardless of project-level CLAUDE.md content:

Unlike a project-level CLAUDE.md that developers might override locally, managed claudeMd cannot be excluded or ignored. It's a reliable channel for org-wide coding standards, security requirements, and links to internal resources that should be in every session.

For project-specific context, commit CLAUDE.md to the repo root - every collaborator gets the same instructions, and the deploy Claude Code guide covers how to structure these for large monorepos. The claudeMdExcludes setting lets you skip CLAUDE.md files from vendor directories or third-party code that you don't want polluting Claude's context.

Monitoring Claude Code usage

Claude Code exports telemetry via OpenTelemetry, which integrates with any OTLP-compatible stack - Datadog, Honeycomb, Grafana:

Available metrics include session activity, tool usage counts by type, model usage, and error rates. For cloud sessions, all operations are logged for compliance automatically.

The ConfigChange hook (covered above) gives real-time signals when settings files change mid-session. Pairing it with your SIEM gives an audit trail of configuration modifications.

For usage reporting at the team level, the usage-analytics-claude-code blog has a full walkthrough of Claude Code usage analytics setup including the available OTLP metrics and what each one tells you.

Teams vs Enterprise: what each plan adds for admins

For deploying Claude Code to teams under roughly 50 people, Claude for Teams with file-based or MDM-deployed managed settings usually covers the essentials. Enterprise adds SSO, forceLoginOrgUUID to enforce org membership, and server-managed settings pushed from a central console - the right fit for orgs with Active Directory, Okta, or similar identity management, or with compliance requirements that need Anthropic Trust Center documentation (SOC 2 Type 2, ISO 27001 both certified as of 2026).

The full enterprise Claude Code guide covers procurement, user provisioning, and the SSO configuration steps.

A quick-start managed settings template

Here's a baseline managed-settings.json that covers the essentials for most security-conscious engineering orgs. Deploy it to /Library/Application Support/ClaudeCode/managed-settings.json (macOS), /etc/claude-code/managed-settings.json (Linux), or push it via MDM/Group Policy:

This template closes --dangerously-skip-permissions, blocks reads of SSH keys and AWS credentials, enables the sandbox with auto-approved sandboxed Bash, restricts outbound network to approved domains, injects a minimal security policy, and pins a minimum version.

Once you've run this for a week and audited what your developers actually need in the allow list, consider adding "allowManagedPermissionRulesOnly": true for the strictest possible lockdown. That setting is left off here intentionally - it should be added only after you're confident the allow list covers your team's real workflow.

The complete settings.json reference covers all ~80 available keys if you need to tune further, and the Claude Code best practices guide covers the developer-side setup that complements this admin layer.

Try eesel.ai

If you're thinking carefully about AI governance for your engineering org, you're probably fielding the same questions in support, ops, and other teams. eesel.ai deploys autonomous AI agents directly inside the tools those teams already use - Zendesk, Freshdesk, Slack, Jira, and 100+ others - with the same approach as Claude Code's permission system: agents operate within clear boundaries you configure, the team stays in control of what they can and can't do, and setup takes minutes from existing knowledge history. No new interface to adopt, no prompt engineering required.