SpyBara
Go Premium

admin-setup.md 2026-10-21 23:02 UTC to 2026-10-22 22:58 UTC

This page contains 59 additions and 59 deletions.

2026
Thu 1 23:59 Fri 2 22:59 Sun 4 23:58 Mon 5 23:58 Tue 6 23:59 Wed 7 23:59 Tue 20 23:00 Wed 21 23:02 Thu 22 22:58 Fri 23 22:59 Mon 26 22:57 Tue 27 22:59

Set up Claude Code for your organization

A decision map for administrators deploying Claude Code, covering API providers, managed settings, policy enforcement, usage monitoring, and data handling.

Claude Code enforces organization policy through managed settings that take precedence over local developer configuration. You deliver those settings from the Claude admin console, your mobile device management (MDM) system, or a file on disk. The settings control which tools, commands, servers, and network destinations Claude can reach.

This page walks through the deployment decisions in order. Each row links to the section below and to the reference page for that area.

[!NOTE]

SSO, SCIM provisioning, and seat assignment are configured at the Claude account level. See the Claude Enterprise Administrator Guide and seat assignment for those steps.

Decision What you're choosing Reference
Choose your API provider Where Claude Code authenticates and how it's billed Authentication, Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry
Decide how settings reach devices How managed policy reaches developer machines Server-managed settings, Delivery mechanisms
Decide what to enforce Which tools, commands, and integrations are allowed Permissions, Sandboxing
Set up usage visibility How you track spend and adoption Analytics, Monitoring, Costs
Review data handling Data retention and compliance posture Data usage, Security

Choose your API provider

Claude Code connects to Claude through one of several API providers. Your choice affects billing, authentication, which compliance posture you inherit, and which Claude Code features your developers can use.

Provider Choose this when
Claude for Teams / Enterprise You want Claude Code and claude.ai under one per-seat subscription with no infrastructure to run. This is the default recommendation.
Claude Console You're API-first or want pay-as-you-go billing
Amazon Bedrock You want to inherit existing AWS compliance controls and billing
Google Cloud's Agent Platform You want to inherit existing GCP compliance controls and billing
Microsoft Foundry You want to inherit existing Azure compliance controls and billing

Some Claude Code features require a claude.ai account. Cloud sessions, cloud scheduled tasks, Code Review, Remote Control, and the Chrome extension aren't available through Console API keys or cloud-provider credentials alone. If you deploy through Amazon Bedrock, Google Cloud's Agent Platform, or Microsoft Foundry, plan whether developers also need Claude for Teams or Enterprise seats. Each feature page lists its plan requirements.

For the full provider comparison covering authentication, regions, and feature parity, see the enterprise deployment overview. Each provider's auth setup is in Authentication.

Proxy and firewall requirements in Network configuration apply regardless of provider. If you want a single endpoint in front of multiple providers or centralized request logging, see LLM gateway.

Decide how settings reach devices

Managed settings define organization policy. Claude Code checks the four sources in the table below in priority order. How Claude Code combines managed sources says which of them apply, what a policy helper changes, and how to compose every source. The table is the decision map.

Mechanism Delivery Priority Platforms
Server-managed claude.ai admin console, or a self-hosted Claude apps gateway for gateway sign-ins Highest All
plist / registry policy macOS: com.anthropic.claudecode plist Windows: HKLM\SOFTWARE\Policies\ClaudeCode High macOS, Windows
File-based managed 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 Medium All
Windows user registry HKCU\SOFTWARE\Policies\ClaudeCode Lowest Windows only

Claude Code fetches server-managed settings at startup and refreshes them hourly during the session, with no endpoint infrastructure to deploy. Delivery through the claude.ai admin console requires a Claude for Teams or Enterprise plan. Deployments on Amazon Bedrock, Google Cloud's Agent Platform, or Microsoft Foundry can get the same remote delivery by running a Claude apps gateway, or use one of the file-based or OS-level mechanisms instead.

If your organization mixes providers, configure server-managed settings for claude.ai users plus a file-based or plist/registry fallback so other users still receive managed policy.

The plist and HKLM registry locations work with any provider and resist tampering because they require admin privileges to write. The Windows user registry at HKCU is writable without elevation, so treat it as a convenience default rather than an enforcement channel.

By default, WSL reads only the Linux file path at /etc/claude-code. To extend your Windows registry and C:\Program Files\ClaudeCode policy to WSL on the same machine, set wslInheritsWindowsSettings: true in either of those admin-only Windows sources.

Whichever mechanism you choose, managed values take precedence over user and project settings, apart from a few security-sensitive exceptions. Array settings such as permissions.allow and permissions.deny merge entries from all sources, so developers can extend managed lists but not remove from them. For fallbackModel, availableModels, and modelPicker, the managed value replaces lower layers rather than merging.

WSL sessions in Claude Code Desktop

On Windows, Claude Code Desktop can run Code sessions inside a WSL 2 distribution. The session's Claude Code process runs inside the distribution, so it resolves managed settings through the WSL discovery path above: Windows-only sources don't reach it unless wslInheritsWindowsSettings: true is deployed.

Claude Desktop turns off WSL sessions by default on devices it detects as organization-managed, for example when C:\Program Files\ClaudeCode\managed-settings.json exists. To turn them on, deploy a Windows registry policy, which requires Claude Desktop v1.19367.0 or later:

  • Create a value named disableWslSessions under HKLM\SOFTWARE\Policies\Claude and set it to the REG_SZ string false or the REG_DWORD 0. This value sits under the Claude Desktop policy key, separate from the ClaudeCode key that carries managed settings. Deploy the value under HKLM, which requires administrator privileges to write. A value under HKCU doesn't enable WSL sessions.
  • Leave C:\Program Files\ClaudeCode\managed-settings.json in place if you deploy it. Once disableWslSessions is false under HKLM, Desktop allows WSL sessions even though that file is present.

Desktop reads the policy each time a WSL session starts, so you don't need to restart the app after deploying it.

If a device still refuses WSL sessions, open Help > Troubleshooting > Show Logs in File Explorer in Claude Desktop on that device, which saves a copy of its log folder to Downloads. Search main.log in that copy for [wslPolicyGate] denying WSL session. The reason for the denial follows in parentheses, such as (cli-file-present).

After WSL sessions are enabled, extend your managed settings to them:

  • Deploy wslInheritsWindowsSettings: true through the HKLM registry or the C:\Program Files\ClaudeCode file so WSL sessions inherit the same policy as host sessions.
  • Verify by running /status inside a WSL session and reading the Setting sources line. To interpret what it lists, see Read the source in /status.

Processes inside the WSL 2 utility VM aren't visible to Windows-side endpoint detection sensors. To observe in-distro process and file activity, check your endpoint detection vendor's WSL guidance for a Linux sensor you can run inside the distribution and the exclusions it needs. Claude Code's OpenTelemetry tool-execution telemetry is emitted identically for WSL and native sessions.

Decide what to enforce

Managed settings can lock down tools, sandbox execution, restrict MCP servers and plugin sources, and control which hooks run. Each row is a control surface with the setting keys that drive it.

Control What it does Key settings
Permission rules Allow, ask, or deny specific tools and commands permissions.allow, permissions.deny
Permission lockdown Make managed settings the only settings source of permission rules. Disable --dangerously-skip-permissions allowManagedPermissionRulesOnly, permissions.disableBypassPermissionsMode
Starting permission mode Choose the permission mode your developers' terminal sessions start in instead of the built-in starting permission mode, or remove auto mode. Switch permission modes lists when the VS Code extension reads a defaultMode you set permissions.defaultMode, permissions.disableAutoMode
Sandboxing OS-level filesystem and network isolation with domain allowlists sandbox.enabled, sandbox.network.allowedDomains
Managed policy CLAUDE.md Organization-wide behavioral guidance for Claude rather than a client-enforced rule File at the managed policy path
MCP server control Restrict which MCP servers users can add or connect to, deploy a fixed set, or provide remote servers to every user alongside their own allowedMcpServers, deniedMcpServers, allowManagedMcpServersOnly, managedMcpServers, or a deployed managed-mcp.json file
Plugin marketplace control Restrict which marketplace sources users can add and install from, reject the CLI flags that sideload plugins, agents, and MCP servers for a single run, block command plugin sources, and allowlist which marketplaces' plugins can be suggested strictKnownMarketplaces, blockedMarketplaces, disableSideloadFlags, disableCommandPluginSources, pluginSuggestionMarketplaces
Customization lockdown Block skills, agents, hooks, and MCP servers from user and project sources, so they can only come from plugins or managed settings. Locking skills also stops the skills your developers enable on claude.ai from syncing strictPluginOnlyCustomization
Disable claude.ai sync Stop Claude Code from loading the skills and plugins your developers enable on claude.ai. If you turn off Skills for your organization on claude.ai, Claude Code stops syncing both, and on v2.1.273 or later it also removes the ones it already synced. To stop either one without turning Skills off, set its key to false in managed settings syncClaudeAiSkills, syncClaudeAiPlugins
Hook restrictions Restrict which hooks run and restrict HTTP hook URLs; see what runs under allowManagedHooksOnly for the full effect list allowManagedHooksOnly, allowedHttpHookUrls
Login enforcement Restrict login to a specific method or Anthropic organization. The method restriction applies across the VS Code extension, Agent SDK, claude setup-token, and /install-github-app, and the terminal's interactive login screen, reached by /login or first-run onboarding, pre-selects the method without enforcing it; Claude Code verifies the organization for claude.ai account logins in the terminal, VS Code extension, and Agent SDK, and doesn't check it for Claude Console logins or for gateway sign-in. Before v2.1.212, only terminal logins applied either key. When set, sessions authenticated by ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, or apiKeyHelper are blocked at startup; cloud provider sessions aren't affected unless one of those credentials, or an API key saved by an earlier Claude Console login, is also present forceLoginMethod, forceLoginOrgUUID
Provider restrictions Limit which API providers a machine may use. A session on a provider that isn't listed is refused at startup, at login, and when it next contacts the API. Requires Claude Code v2.1.285 or later allowedProviders
Disable agent view Turn off claude agents, --bg, /background, and the on-demand supervisor disableAgentView
Configure the corporate launcher Prefix the background-agent supervisor, its workers, and the other covered background processes with a required corporate launcher instead of turning agent view off processWrapper
Model restrictions availableModels filters which models appear in the picker. Adding enforceAvailableModels also constrains the auto-selected default model. See surface coverage for how this setting reaches the CLI, web, and IDE availableModels, enforceAvailableModels
Effort cap Cap the effort level for every model or per model, on every provider maxEffortLevel
Version floor Prevent auto-update from installing below an org-wide minimum minimumVersion
Required version range Refuse to start at all when the running version is outside an org-approved range. Stronger than minimumVersion, which only blocks downgrades requiredMinimumVersion, requiredMaximumVersion
Telemetry opt-out Turn off Anthropic-bound usage metrics, error reports, and surveys on every device env with CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC set to 1; the linked section lists the per-category variables

If your members sign in through claude.ai or the Anthropic API and you're on a Claude Enterprise plan, you can also govern models from your organization's admin settings without deploying anything:

None of these controls reach sessions on Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, or Claude Platform on AWS. On those providers, use managed settings instead: availableModels for restrictions, model for a default, and maxEffortLevel for an effort cap.

Cloud sessions have their own admin surfaces on claude.ai:

Permission rules and sandboxing cover different layers. Denying WebFetch blocks Claude's fetch tool, but if Bash is allowed, curl and wget can still reach any URL. Sandboxing closes that gap with a network domain allowlist enforced at the OS level.

For the threat model these controls defend against, see Security.

Connected GitHub accounts

On Team and Enterprise plans, the GitHub section of Organization settings > Git providers lists the GitHub organizations and personal accounts linked to your Claude organization through the Claude GitHub App. Claude Code, Claude Tag, and Claude Security share the list. Opening the page requires an admin role in your Claude organization.

An admin or a member can link an account:

  • Admin connection: an admin clicks Connect in that section, or Add organization once an account is connected, and installs the Claude GitHub App on a GitHub organization. Linking an organization this way requires someone who is both an owner of the GitHub organization and an admin of your Claude organization.
  • Member connection: when a member connects their GitHub account to Claude, for example while setting up cloud sessions, Claude links the GitHub accounts that member owns where the Claude GitHub App is already installed. That can include their personal account and GitHub organizations they own.

A row marked Not linked comes from your own GitHub sign-in. It's an account you can see on GitHub where the Claude GitHub App is installed.

To unlink an account from your Claude organization, open its row's menu and select Unlink from this workspace. Unlinking leaves the Claude GitHub App installed on GitHub, and the account is linked again the next time one of its owners connects GitHub to Claude. To keep it from being linked again, uninstall the Claude GitHub App from that account on GitHub.

On Enterprise plans, the Compliance API activity types for linking and unlinking are github_app_installation_linked and github_app_installation_unlinked.

Set up usage visibility

Choose monitoring based on what you need to report on. The dashboards, APIs, and spend controls differ between Claude for Teams or Enterprise plans and Claude Console organizations, so check the Availability column before you plan your reporting around a capability.

Capability What you get Availability Where to start
Usage monitoring OpenTelemetry export of sessions, tools, and tokens All providers Monitoring usage
Analytics dashboard Adoption and contribution metrics with a leaderboard on Teams / Enterprise; per-user usage and spend metrics on Console Teams / Enterprise at claude.ai/analytics, Console at platform.claude.com/claude-code Analytics
Programmatic reporting Per-user usage and cost data over an API Enterprise Analytics API for Enterprise, Claude Code Analytics API for Console Costs
Spend controls Spend limits and rate limits Organization settings for Teams / Enterprise, workspace limits for Console; on third-party clouds, cloud budget controls or a Claude apps gateway with per-user spend limits Costs

On Teams and Enterprise, per-user usage and spend numbers come from the spend report in your organization's analytics settings, not the analytics dashboard. Cloud providers expose spend through AWS Cost Explorer, GCP Billing, or Azure Cost Management. For planning enterprise budgets across Claude chat, Claude Code, and Cowork, see the Claude Enterprise consumption guide.

Review data handling

On Team, Enterprise, Claude API, and cloud provider plans, Anthropic doesn't train models on your code or prompts. Your API provider determines retention and compliance posture.

Topic What to know Where to start
Data usage policy What Anthropic collects, how long it's retained, what's never used for training Data usage
Zero Data Retention (ZDR) Nothing stored after the request completes. Available to qualified accounts on Claude for Enterprise Zero data retention
HIPAA configuration For Claude for Enterprise organizations that have HIPAA enabled. Some Claude Code (local mode) features are turned off and others are off by default Set up Claude Code (local mode) for a HIPAA-ready organization
Security architecture Network model, encryption, authentication, audit trail Security

If you need request-level audit logging or to route traffic by data sensitivity, we recommend you place a gateway between developers and your provider: a self-hosted Claude apps gateway records a per-request audit log with IdP identity, or you can use another LLM gateway. Sessions that go through a gateway aren't eligible for the HIPAA configuration. Check how developers sign in and connect lists which sign-in and connection methods are. For regulatory requirements and certifications, see Legal and compliance.

Verify and onboard

After configuring managed settings, have a developer run /status inside Claude Code. On the Status tab, the Setting sources line shows Enterprise managed settings followed by the source that won in parentheses; Verify enforcement lists the labels.

Share these resources to help developers get started:

For login issues, point developers to authentication troubleshooting. The most common fixes are:

  • Run /logout then /login to switch accounts
  • Run claude update if the enterprise auth option is missing
  • Restart the terminal after updating

If a developer sees "You haven't been added to your organization yet," their seat doesn't include Claude Code access and needs to be updated in the admin console.

Next steps

With provider and delivery mechanism chosen, move on to detailed configuration: