Home Docs Claude Code CLI 22 Oct 2026

One change · claude-code

Manage Claude Code plugins for your organization changedplugins/org

Nearest release: v2.1.307, published 3 hours before upstream edited the page. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.

Upstream edited this page at 22 Oct 2026 00:13 UTC, give or take a minute or two: the time comes from Anthropic’s own sitemap rather than from a commit. This site recorded the change at 22 Oct 2026 18:07 UTC.

Upstream edited 22 Oct 2026 00:13 UTC

Recorded here 22 Oct 2026 18:07 UTC

Lines+54added

Lines−54removed

From line 2 where the diff opens

First seen 25 Sep 2026 this site's first read of the page

Recorded edits11to this page, all time

The whole hunk

from line 2, old and new numbered

lines

from line 2

33> Control which plugins Claude Code installs and allows across your organization through managed settings.

5Managed settings let you decide which plugins Claude Code installs and allows on every machine in your organization. Users can't override them. You deliver them either as [server-managed settings](/docs/en/server-managed-settings) from the claude.ai admin console or as endpoint-managed settings through MDM or a `managed-settings.json` file. Most controls on this page take effect only from managed settings.

5Managed settings let you decide which plugins Claude Code installs and allows on every machine in your organization. Users can't override them. You deliver them either as [server-managed settings](/docs/en/server-managed-settings.md) from the claude.ai admin console or as endpoint-managed settings through MDM or a `managed-settings.json` file. Most controls on this page take effect only from managed settings.

77This page is for administrators, and the settings here govern Claude Code.

from line 10

1010>

1111> These cases are covered on other pages:

1212>

13> * **Installing plugins for yourself**: start at [Install plugins](/docs/en/plugins/install)

13> * **Installing plugins for yourself**: start at [Install plugins](/docs/en/plugins/install.md)

1414> * **Controlling which plugins members can use in claude.ai and Cowork**: see [Manage plugins for your organization](https://claude.com/docs/plugins/admin) on claude.com

1515> * **Rolling one plugin out to claude.ai, Cowork, and Claude Code together**: see [Choose a rollout route](https://claude.com/docs/plugins/org-rollout#choose-a-rollout-route) on claude.com

16> * **The plugins page in claude.ai's admin settings**: [**Organization settings > Plugins & skills**](https://claude.ai/admin-settings/skills?tab=inventory) turns plugins on for members' claude.ai accounts, and those reach Claude Code as [synced plugins](/docs/en/plugins/loading#synced-plugins). It doesn't set any of the keys on this page

16> * **The plugins page in claude.ai's admin settings**: [**Organization settings > Plugins & skills**](https://claude.ai/admin-settings/skills?tab=inventory) turns plugins on for members' claude.ai accounts, and those reach Claude Code as [synced plugins](/docs/en/plugins/loading.md#synced-plugins). It doesn't set any of the keys on this page

1717

1818The sections follow the order most rollouts take: [require plugins](#pre-install-and-require-plugins) for everyone or per repository, [seed containers and CI](#seed-containers-and-ci), [restrict](#restrict-what-users-can-install) what users can add on their own, [set update policy](#set-update-policy), then [audit](#audit-and-review) what's installed. To review every policy key in one place, see the [control matrix](#control-matrix).

1919

from line 21

2121

2222A marketplace is a catalog of plugins that Claude Code fetches from a git repository, a URL, or a local path. Once you register a marketplace on a machine, Claude Code can install plugins from it.

2323

24To install plugins for a fleet, set two keys together in [managed settings](/docs/en/managed-settings), the policy file or server-delivered policy that every machine in your organization reads: `extraKnownMarketplaces` registers a marketplace on each machine, and `enabledPlugins` names the plugins to install and enable from it. [Choose a delivery mechanism](#choose-a-delivery-mechanism) covers how managed settings reach each machine.

24To install plugins for a fleet, set two keys together in [managed settings](/docs/en/managed-settings.md), the policy file or server-delivered policy that every machine in your organization reads: `extraKnownMarketplaces` registers a marketplace on each machine, and `enabledPlugins` names the plugins to install and enable from it. [Choose a delivery mechanism](#choose-a-delivery-mechanism) covers how managed settings reach each machine.

2525

2626### Choose a delivery mechanism

2727

2828Managed settings reach a machine through one of three delivery mechanisms:

2929

30* **Server-managed settings**: set the plugin keys as JSON at [**Organization settings > Claude Code > Managed settings**](https://claude.ai/admin-settings/claude-code). Requires an [Owner role](/docs/en/server-managed-settings#access-control) in your Claude organization. A cloud session fetches these settings before it installs plugins.

31* **MDM policies**: on macOS, deliver a plist whose top-level keys are the settings keys. On Windows, store the whole JSON document as a string in a registry value. The plist domain and the registry key are in [Where each mechanism stores the policy](/docs/en/managed-settings#where-each-mechanism-stores-the-policy).

32* **Managed settings file**: place a `managed-settings.json` at the platform's system path. You can also add files to the `managed-settings.d/` drop-in directory beside it. The file paths per platform are in [Where each mechanism stores the policy](/docs/en/managed-settings#where-each-mechanism-stores-the-policy), and the drop-in merge rules are in [Split a file-based policy across teams](/docs/en/managed-settings#split-a-file-based-policy-across-teams).

30* **Server-managed settings**: set the plugin keys as JSON at [**Organization settings > Claude Code > Managed settings**](https://claude.ai/admin-settings/claude-code). Requires an [Owner role](/docs/en/server-managed-settings.md#access-control) in your Claude organization. A cloud session fetches these settings before it installs plugins.

32* **Managed settings file**: place a `managed-settings.json` at the platform's system path. You can also add files to the `managed-settings.d/` drop-in directory beside it. The file paths per platform are in [Where each mechanism stores the policy](/docs/en/managed-settings.md#where-each-mechanism-stores-the-policy), and the drop-in merge rules are in [Split a file-based policy across teams](/docs/en/managed-settings.md#split-a-file-based-policy-across-teams).

3333

34Use server-managed settings if you have a Claude for Teams or Enterprise organization on claude.ai and your devices aren't all under MDM. Otherwise use an MDM policy or the managed settings file. For the trade-off, see [Choose between server-managed and endpoint-managed settings](/docs/en/server-managed-settings#choose-between-server-managed-and-endpoint-managed-settings).

34Use server-managed settings if you have a Claude for Teams or Enterprise organization on claude.ai and your devices aren't all under MDM. Otherwise use an MDM policy or the managed settings file. For the trade-off, see [Choose between server-managed and endpoint-managed settings](/docs/en/server-managed-settings.md#choose-between-server-managed-and-endpoint-managed-settings).

3535

3636#### Which managed source applies on a machine

3737

38By default, only one of these three sources applies on a machine. Claude Code uses the first that delivers a policy key, checking server-managed settings first, then MDM policies, then the managed settings file. If server-managed settings deliver even one unrelated policy key, Claude Code ignores the plugin keys in an MDM policy or managed settings file on that machine, apart from the [keys it reads from every source](/docs/en/managed-settings#keys-read-from-every-admin-source).

3939

4040To apply every source instead, set [`managedSourcesBehavior`](/docs/en/managed-settings#compose-every-managed-source) to `"merge"`.

4141

42[How Claude Code combines managed sources](/docs/en/managed-settings#how-claude-code-combines-managed-sources) also lists the keys Claude Code reads from every source in both modes.

42[How Claude Code combines managed sources](/docs/en/managed-settings.md#how-claude-code-combines-managed-sources) also lists the keys Claude Code reads from every source in both modes.

4343

4444### Require a marketplace and its plugins

4545

from line 67

6767Adjust the `autoUpdate` and `source` fields for your marketplace:

6868

6969* **`autoUpdate`**: `true` keeps the marketplace and its plugins refreshing in the background, and `false` turns that off. See [Set update policy](#set-update-policy).

70* **`source`**: `github` is one of several source types. A `git` source takes a `url` for GitLab or an internal host, and a `url` source takes the address of a hosted `marketplace.json`. Every source shape is in the [marketplace reference](/docs/en/plugins/marketplace-reference).

7171

7272If the marketplace is a private git repository, each user needs read access to it. The clone of a git-based marketplace runs with git on the user's machine, using stored credentials and no prompts. For users without git-host accounts, use a [seed](#seed-containers-and-ci) instead.

7373

from line 74

7474A managed entry also overrides a same-name marketplace entry or `--plugin-dir` copy from another source:

7575

7676* **Marketplaces**: a managed marketplace entry replaces a lower-precedence entry with the same name, and the two entries' fields don't merge.

77* **`--plugin-dir` copies**: `--plugin-dir` loads a plugin from a local directory for one session. For what happens when that copy's name matches a plugin your managed `enabledPlugins` names, see [Name conflicts](/docs/en/plugins/loading#name-conflicts).

7878

7979Anthropic's official marketplace `claude-plugins-official` needs no `extraKnownMarketplaces` entry when `enabledPlugins` sets one of its plugins to `true`. That `name@claude-plugins-official` entry declares the marketplace by itself, wherever these keys apply. If you enable none of its plugins and still want it registered on every machine, give it an explicit entry, as [Allow the official marketplace and your own](#allow-the-official-marketplace-and-your-own) does.

8080

from line 82

8282

8383To cover one repository's contributors instead of your whole fleet, set `extraKnownMarketplaces` and `enabledPlugins` in that repository's `.claude/settings.json`. The `extraKnownMarketplaces` entries apply only in a folder the contributor has trusted, and in an untrusted folder Claude Code ignores them without a message:

8484

85* **Interactive sessions**: Claude Code registers the marketplace only after the contributor accepts the [workspace trust dialog](/docs/en/permissions#what-runs-before-you-trust-a-folder) for that folder.

85* **Interactive sessions**: Claude Code registers the marketplace only after the contributor accepts the [workspace trust dialog](/docs/en/permissions.md#what-runs-before-you-trust-a-folder) for that folder.

8686* **[Non-interactive `-p` runs](/docs/en/headless)**: the entries apply only in a folder whose trust the user already accepted interactively, or whose `hasTrustDialogAccepted` flag you set in `~/.claude.json`.

8787

88A plugin that the marketplace lists by a relative path loads from the marketplace copy once the repository's `extraKnownMarketplaces` entries apply. A plugin whose marketplace entry points at an external source instead, such as the plugin's own GitHub repository, doesn't install from the repository's settings alone. Each contributor sees `Plugin "<name>" is enabled in project settings but isn't installed` until they run `claude plugin install <name>@<marketplace> --scope project`, as [Install plugins](/docs/en/plugins/install) describes.

8989

9090If you use a local `directory` or `file` source with a relative path, the path resolves against your repository's main checkout. When you run Claude Code from a git worktree, the path still points at the main checkout, so all worktrees share the same marketplace location.

9191

92To roll out a bundle of plugins with dependencies, put the bundle plugin in `enabledPlugins`, as [Plugin dependencies](/docs/en/plugins/dependencies) describes.

92To roll out a bundle of plugins with dependencies, put the bundle plugin in `enabledPlugins`, as [Plugin dependencies](/docs/en/plugins/dependencies.md) describes.

9393

9494### When each surface applies the plugin keys

9595

96The table shows when each kind of Claude Code session applies `extraKnownMarketplaces` and `enabledPlugins`, from managed settings and from a repository's `.claude/settings.json`. For the Desktop app and the IDE extensions, see [Install a plugin](/docs/en/plugins/install#install-a-plugin).

9797

9898| Surface | Managed `extraKnownMarketplaces` and `enabledPlugins` | Repository `.claude/settings.json` |

9999| :- | :- | :- |

100100| Terminal, interactive | Applied at session start on every machine that receives the settings | `extraKnownMarketplaces` applied after trust; `enabledPlugins` applied at session start |

101101| `-p` and CI | Applied at session start, with installs running in the background | `extraKnownMarketplaces` in trusted folders only; `enabledPlugins` applied |

102| Cloud sessions | In an Anthropic-hosted environment, only server-managed settings reach the session, which waits for them before it installs plugins. MDM policies and managed settings files stay on the user's machine. For a self-hosted environment, see [Where and when a policy applies](/docs/en/managed-settings#where-and-when-a-policy-applies) | See the **Cloud session** tab under [Install a plugin](/docs/en/plugins/install#install-a-plugin) |

102| Cloud sessions | In an Anthropic-hosted environment, only server-managed settings reach the session, which waits for them before it installs plugins. MDM policies and managed settings files stay on the user's machine. For a self-hosted environment, see [Where and when a policy applies](/docs/en/managed-settings.md#where-and-when-a-policy-applies) | See the **Cloud session** tab under [Install a plugin](/docs/en/plugins/install.md#install-a-plugin) |

103103

104104In a `-p` or CI run, marketplaces and plugins install in the background, so a plugin can be missing from the first turn. Set `CLAUDE_CODE_SYNC_PLUGIN_INSTALL=1` to make the run wait for the install before its first query.

105105

from line 148

148148* **Update and remove fail**: `claude plugin marketplace update <name>` and `remove` without `--scope` on a seed marketplace fail with a message that names the seed directory.

149149* **Policy still applies**: the [allowlist and blocklist](#restrict-what-users-can-install) check a seed marketplace's recorded source too. Allow the source you built the seed from.

150150

151For fleets with no outbound git access, combine a seed with `directory` or `file` marketplace sources on a shared mount. Set `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1` as well, which also turns off [plugin auto-update](/docs/en/plugins/loading#when-auto-update-runs). If a proxy is available, see [Proxy configuration](/docs/en/network-config#proxy-configuration) for the variables to set.

151For fleets with no outbound git access, combine a seed with `directory` or `file` marketplace sources on a shared mount. Set `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1` as well, which also turns off [plugin auto-update](/docs/en/plugins/loading.md#when-auto-update-runs). If a proxy is available, see [Proxy configuration](/docs/en/network-config.md#proxy-configuration) for the variables to set.

152152

153153## Restrict what users can install

154154

from line 163

163163

164164Where the two lists are enforced depends on where you set them:

165165

166* **The claude.ai admin console**: Claude Code enforces both lists in the sessions that [read server-managed settings](/docs/en/managed-settings#where-and-when-a-policy-applies). claude.ai also checks them when anyone in your organization adds a new marketplace from a git repository on claude.ai, or from **Customize** in the Claude Desktop app outside its Code tab. That covers a marketplace a member adds for their own account and one added for the whole organization under [**Organization settings > Plugins**](https://claude.ai/admin-settings/plugins). claude.ai refuses a repository that the allowlist doesn't admit or that the blocklist names. It doesn't re-check a marketplace that was added in either place before you set the lists, and it doesn't check uploaded plugins.

166* **The claude.ai admin console**: Claude Code enforces both lists in the sessions that [read server-managed settings](/docs/en/managed-settings.md#where-and-when-a-policy-applies). claude.ai also checks them when anyone in your organization adds a new marketplace from a git repository on claude.ai, or from **Customize** in the Claude Desktop app outside its Code tab. That covers a marketplace a member adds for their own account and one added for the whole organization under [**Organization settings > Plugins**](https://claude.ai/admin-settings/plugins). claude.ai refuses a repository that the allowlist doesn't admit or that the blocklist names. It doesn't re-check a marketplace that was added in either place before you set the lists, and it doesn't check uploaded plugins.

167167* **A managed settings file, OS-level policy, or other managed source**: Claude Code enforces both lists where it reads that source. claude.ai doesn't read it.

168168

169169While any allowlist is set, or a blocklist names any source other than [`skills-dir`](#blocklist-with-blockedmarketplaces), a plugin whose marketplace Claude Code can't find doesn't load. `/plugin` shows the policy error for it rather than a not-found error. The common case is a stale `enabledPlugins` entry for a marketplace nobody registered.

from line 176

176176| :- | :- | :- |

177177| `strictKnownMarketplaces` | Allowlist of marketplace sources. `[]` blocks every source, including the official marketplace. Alias: `allowedMarketplaces` | Doesn't register a marketplace, restrict entries inside an allowed marketplace, or block `--plugin-dir` |

178178| `blockedMarketplaces` | Blocklist of marketplace sources, checked before the allowlist | Doesn't block a marketplace already registered from a source it doesn't match |

179| `syncClaudeAiPlugins` | Set `false` to stop Claude Code downloading and loading the plugins [synced from claude.ai](/docs/en/plugins/loading#synced-plugins) for each user's account. Requires Claude Code v2.1.273 or later | Doesn't turn off one synced plugin. For that, set `"<name>@synced": false` in [`enabledPlugins`](/docs/en/settings-reference#enabledplugins) |

179| `syncClaudeAiPlugins` | Set `false` to stop Claude Code downloading and loading the plugins [synced from claude.ai](/docs/en/plugins/loading.md#synced-plugins) for each user's account. Requires Claude Code v2.1.273 or later | Doesn't turn off one synced plugin. For that, set `"<name>@synced": false` in [`enabledPlugins`](/docs/en/settings-reference#enabledplugins) |

180180| `enabledPlugins` | `true` force-enables, `false` blocks at every scope and hides the plugin | Doesn't install a plugin whose marketplace isn't registered or allowed |

181181| `disableSideloadFlags` | Rejects `--plugin-dir`, `--plugin-url`, `--agents`, the Agent SDK `plugins` option, and non-SDK `--mcp-config` at startup, and rejects folders named in the [`CLAUDE_CODE_PLUGIN_DIRS`](/docs/en/env-vars#variables) variable the same way | Doesn't restrict `.mcp.json`, `claude mcp add`, or SDK-provided servers. Pair it with [`allowedMcpServers`](/docs/en/managed-mcp) |

182182| `disableCommandPluginSources` | Blocks plugins with a `command` source from installing, updating, or loading. A `command` source is one whose plugin directory is produced by running a command on the machine. When unset, it takes the value of `allowManagedHooksOnly` | Doesn't affect other source types |

from line 184

184184| `strictPluginOnlyCustomization` | Blocks skills, agents, hooks, and MCP servers that don't come from a plugin, managed settings, or Claude Code's built-ins. It also stops [skills-directory plugins](#keep-skills-directory-plugins-loading) loading. Set `true` to cover all four types, or an array of `skills`, `agents`, `hooks`, and `mcp` values such as `["skills", "hooks"]` to cover some | Doesn't restrict which plugins users install. Pair it with `strictKnownMarketplaces` |

185185| `pluginSuggestionMarketplaces` | Marketplaces whose plugins may appear as install suggestions. See [Recommend plugins](#recommend-plugins) | Doesn't affect the built-in tips |

186186| `pluginTrustMessage` | Appends your text to the trust warning that `/plugin` shows before a plugin installs | Doesn't change the warning's own text |

187| `allowedChannelPlugins` | Replaces the default list of plugins allowed to push channel messages. Requires `channelsEnabled: true` | See [Restrict which channel plugins can run](/docs/en/channels#restrict-which-channel-plugins-can-run) |

188188| [`CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL=1`](/docs/en/env-vars) | Stops interactive terminal sessions from auto-registering the official marketplace | Doesn't remove a marketplace already registered. The allowlist and blocklist gate the same auto-registration without it. A machine that started once with it set doesn't resume auto-registration after you unset it |

189| [`allowManagedModsOnly`](/docs/en/plugins/mods/admin#stop-user-installed-mods-from-loading) | Stops every installed [mod](/docs/en/plugins/mods/overview) that doesn't [count as your organization's](/docs/en/plugins/mods/admin#install-your-organizations-mods) from running its hooks | Doesn't stop a plugin that contains a mod from installing. For that, use the marketplace keys in this table |

189| [`allowManagedModsOnly`](/docs/en/plugins/mods/admin#stop-user-installed-mods-from-loading) | Stops every installed [mod](/docs/en/plugins/mods/overview.md) that doesn't [count as your organization's](/docs/en/plugins/mods/admin.md#install-your-organizations-mods) from running its hooks | Doesn't stop a plugin that contains a mod from installing. For that, use the marketplace keys in this table |

190190

191191Every key in the table is a managed setting, apart from `enabledPlugins`, `syncClaudeAiPlugins`, `CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL`, and `allowManagedModsOnly`:

192192

193193* **`enabledPlugins`**: you can set it in any scope, and managed settings lock it.

194* **`syncClaudeAiPlugins`**: each user can also set it in their own user or local settings. See its [scope in the settings reference](/docs/en/settings-reference#syncclaudeaiplugins).

194* **`syncClaudeAiPlugins`**: each user can also set it in their own user or local settings. See its [scope in the settings reference](/docs/en/settings-reference.md#syncclaudeaiplugins).

195195* **`CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL`**: this is an environment variable that you deliver through the managed `env` block shown under [Turn updates off for the whole fleet](#turn-updates-off-for-the-whole-fleet).

196* **`allowManagedModsOnly`**: this is an option on a built-in plugin, which you set under `pluginConfigs` in managed settings. See [Stop user-installed mods from loading](/docs/en/plugins/mods/admin#stop-user-installed-mods-from-loading).

197197

198Each settings key here has an entry in the [settings reference](/docs/en/settings-reference).

198Each settings key here has an entry in the [settings reference](/docs/en/settings-reference.md).

199199

200200#### Aliases for the marketplace keys

201201

from line 213

213213* **`git`**: `{ "source": "git", "url": "https://gitlab.example.com/tools/plugins.git" }`, with optional `ref` and `path`.

214214* **`url`**: `{ "source": "url", "url": "https://plugins.example.com/marketplace.json" }`, with optional `headers`.

215215* **`file` and `directory`**: `{ "source": "file", "path": "/opt/marketplace/marketplace.json" }` or `{ "source": "directory", "path": "/opt/marketplace/plugins" }`, with absolute paths.

216* **`hostPattern`**: `{ "source": "hostPattern", "hostPattern": "^github\\.example\\.com$" }`, matched against the host of `github`, `git`, and `url` sources. The pattern matches anywhere in the hostname, so anchor it with `^` and `$` as shown to match the whole host. A `github` source always counts as `github.com`. Use a `hostPattern` entry for a GitHub Enterprise Server or GitLab host where developers create their own marketplaces. The [GHES page](/docs/en/github-enterprise-server#allowlist-ghes-marketplaces-in-managed-settings) has the worked example.

216* **`hostPattern`**: `{ "source": "hostPattern", "hostPattern": "^github\\.example\\.com$" }`, matched against the host of `github`, `git`, and `url` sources. The pattern matches anywhere in the hostname, so anchor it with `^` and `$` as shown to match the whole host. A `github` source always counts as `github.com`. Use a `hostPattern` entry for a GitHub Enterprise Server or GitLab host where developers create their own marketplaces. The [GHES page](/docs/en/github-enterprise-server.md#allowlist-ghes-marketplaces-in-managed-settings) has the worked example.

217217* **`pathPattern`**: `{ "source": "pathPattern", "pathPattern": "^/opt/approved/" }`, matched against the `path` of `file` and `directory` sources. The pattern matches anywhere in the path, so start it with `^` to pin a directory prefix. `".*"` allows every local path.

218218* **`skills-dir`**: `{ "source": "skills-dir" }` matches no marketplace. For what it does, see [Keep skills-directory plugins loading](#keep-skills-directory-plugins-loading).

219219

from line 229

229229

230230#### Keep skills-directory plugins loading

231231

232Skills-directory plugins are the plugins users keep under `~/.claude/skills/` or a project's `.claude/skills/` in folders that carry a `.claude-plugin/plugin.json`. If you set any allowlist without a `{ "source": "skills-dir" }` entry, they stop loading. If you lock any customization type with [`strictPluginOnlyCustomization`](/docs/en/settings-reference#strictpluginonlycustomization), they stop loading whether or not the entry is present. The allowlist doesn't apply to plain [skills](/docs/en/skills), meaning a `SKILL.md` without that manifest.

233233

234234#### Marketplaces hosted on claude.ai

235235

236The allowlist and blocklist match a [marketplace hosted on claude.ai](/docs/en/plugins/install#add-from-claude-ai) by its host. To allow or block one, add a `hostPattern` entry that matches `claude.ai` to `strictKnownMarketplaces` or `blockedMarketplaces`. On the allowlist, such an entry admits your organization's claude.ai marketplaces and the claude.ai default marketplaces, but not a marketplace made of a member's own claude.ai uploads or one whose scope claude.ai didn't state. Requires Claude Code v2.1.273 or later.

236The allowlist and blocklist match a [marketplace hosted on claude.ai](/docs/en/plugins/install.md#add-from-claude-ai) by its host. To allow or block one, add a `hostPattern` entry that matches `claude.ai` to `strictKnownMarketplaces` or `blockedMarketplaces`. On the allowlist, such an entry admits your organization's claude.ai marketplaces and the claude.ai default marketplaces, but not a marketplace made of a member's own claude.ai uploads or one whose scope claude.ai didn't state. Requires Claude Code v2.1.273 or later.

237237

238238#### Lock every source out

239239

240240An empty allowlist, `[]`, locks every marketplace source out, including the official marketplace.

241241

242This lockdown doesn't cover the plugins [synced from claude.ai](/docs/en/plugins/loading#synced-plugins), which Claude Code downloads from each user's account rather than from a marketplace. To stop those as well, set [`syncClaudeAiPlugins`](/docs/en/settings-reference#syncclaudeaiplugins) to `false` in managed settings, or turn off Skills for your organization on claude.ai.

242This lockdown doesn't cover the plugins [synced from claude.ai](/docs/en/plugins/loading.md#synced-plugins), which Claude Code downloads from each user's account rather than from a marketplace. To stop those as well, set [`syncClaudeAiPlugins`](/docs/en/settings-reference#syncclaudeaiplugins) to `false` in managed settings, or turn off Skills for your organization on claude.ai.

243243

244244### Blocklist with `blockedMarketplaces`

245245

from line 260

260260}

261261```

262262

263The `url` entries in `blockedMarketplaces` also apply when a user adds an `https://` repository URL that Claude Code [clones rather than fetches](/docs/en/plugins/cli-reference#plugin-marketplace-add), such as a bare `github.com` or `gitlab.com` repository URL. The user can't add that URL if an entry names it. The match ignores the `.git` suffix and any ref the user appends after `#`. Requires Claude Code v2.1.232 or later.

263The `url` entries in `blockedMarketplaces` also apply when a user adds an `https://` repository URL that Claude Code [clones rather than fetches](/docs/en/plugins/cli-reference.md#plugin-marketplace-add), such as a bare `github.com` or `gitlab.com` repository URL. The user can't add that URL if an entry names it. The match ignores the `.git` suffix and any ref the user appends after `#`. Requires Claude Code v2.1.232 or later.

264264

265265A `{ "source": "skills-dir" }` entry here stops [skills-directory plugins](#keep-skills-directory-plugins-loading) from loading, from both `~/.claude/skills/` and a project's `.claude/skills/`.

266266

from line 309

309309

310310### Turn auto-update on or off per marketplace

311311

312Plugin auto-update runs in the background after startup for marketplaces that have it turned on. For which marketplaces have it on by default, see [When auto-update runs](/docs/en/plugins/loading#when-auto-update-runs). To decide for the fleet, set `"autoUpdate": true` or `false` on a managed `extraKnownMarketplaces` entry:

312Plugin auto-update runs in the background after startup for marketplaces that have it turned on. For which marketplaces have it on by default, see [When auto-update runs](/docs/en/plugins/loading.md#when-auto-update-runs). To decide for the fleet, set `"autoUpdate": true` or `false` on a managed `extraKnownMarketplaces` entry:

313313

314314* If the managed entry sets the field, Claude Code refuses the user's `/plugin` toggle with an error that starts `Auto-update for '<name>' is set by`.

315315* If the managed entry leaves the field unset, the user's toggle persists.

from line 326

326326}

327327```

328328

329To stop Claude Code's own updates but keep plugin auto-update, add `"FORCE_AUTOUPDATE_PLUGINS": "1"` to the same block. The other [environment variables that stop plugin auto-update](/docs/en/plugins/loading#when-auto-update-runs) work the same way.

330330

331`DISABLE_AUTOUPDATER` doesn't cover plugins with a [`command` source](/docs/en/plugins/marketplace-reference#command-plugin-source). Claude Code re-runs each enabled one's command every session and installs the output when it changed. For what stops those runs, see [When a command source re-runs](/docs/en/plugins/loading#when-a-command-source-re-runs).

332332

333333### Assign release channels to user groups

334334

335To run stable and early-access channels, host two marketplaces that point at different refs of the same plugins. Then give each user group its own marketplace through either separate endpoint-managed settings or a gateway policy. Server-managed settings from the admin console [apply to every user in your organization](/docs/en/server-managed-settings#current-limitations), so they can't assign different settings to different groups.

335To run stable and early-access channels, host two marketplaces that point at different refs of the same plugins. Then give each user group its own marketplace through either separate endpoint-managed settings or a gateway policy. Server-managed settings from the admin console [apply to every user in your organization](/docs/en/server-managed-settings.md#current-limitations), so they can't assign different settings to different groups.

336336

337* Deploy separate [endpoint-managed settings](/docs/en/managed-settings#delivery-mechanisms), such as a managed settings file or an MDM profile, to each group's devices. To check whether the per-group file or profile applies on a device that also has an organization-wide source, see [How Claude Code combines managed sources](/docs/en/managed-settings#precedence-within-the-managed-tier).

338* Define one [Claude apps gateway policy](/docs/en/claude-apps-gateway-config#managed) per group. The gateway applies the first policy whose match rule fits a user, so order the policies so that each user reaches their group's policy. That policy's `extraKnownMarketplaces` map doesn't merge with any other policy's, so list every marketplace the group needs in it, not only its channel marketplace.

337* Deploy separate [endpoint-managed settings](/docs/en/managed-settings.md#delivery-mechanisms), such as a managed settings file or an MDM profile, to each group's devices. To check whether the per-group file or profile applies on a device that also has an organization-wide source, see [How Claude Code combines managed sources](/docs/en/managed-settings.md#precedence-within-the-managed-tier).

338* Define one [Claude apps gateway policy](/docs/en/claude-apps-gateway-config.md#managed) per group. The gateway applies the first policy whose match rule fits a user, so order the policies so that each user reaches their group's policy. That policy's `extraKnownMarketplaces` map doesn't merge with any other policy's, so list every marketplace the group needs in it, not only its channel marketplace.

339339

340340With either mechanism, the stable group receives this configuration:

341341

from line 349

349349}

350350```

351351

352The early-access group receives `latest-tools` instead. To set up the two marketplaces, see [Run release channels](/docs/en/plugins/host-marketplace#run-release-channels).

352The early-access group receives `latest-tools` instead. To set up the two marketplaces, see [Run release channels](/docs/en/plugins/host-marketplace.md#run-release-channels).

353353

354354## Recommend plugins

355355

356356Marketplace owners can attach `relevance` signals to entries so Claude Code suggests the plugin when a project matches.

357357

358Suggestions from a marketplace appear only when it's registered on the user's machine, you list its name in `pluginSuggestionMarketplaces` in managed settings, and you declare its source in the same policy. Declare the source either as the marketplace's `extraKnownMarketplaces` entry or as an allowlist entry. The official marketplace needs only the name. See [Enable suggestions in managed settings](/docs/en/plugins/relevance#enable-suggestions-in-managed-settings).

359359

360360## Audit and review

361361

362362OpenTelemetry events and the Analytics API tell you what your fleet installs and runs.

363363

364For what a plugin can run on a machine and what each trust tier permits, read [Plugin security](/docs/en/plugins/security) before you approve a marketplace.

364For what a plugin can run on a machine and what each trust tier permits, read [Plugin security](/docs/en/plugins/security.md) before you approve a marketplace.

365365

366366### OpenTelemetry events

367367

368`claude_code.plugin_installed` records each install, and `claude_code.plugin_loaded` records each enabled plugin at session start. Both events redact or omit third-party plugin and marketplace names unless you set `OTEL_LOG_TOOL_DETAILS=1`, as [Redacted plugin names in your backend](/docs/en/plugins/measure#redacted-plugin-names-in-your-backend) shows. Field lists are under [Plugin installed event](/docs/en/monitoring-usage#plugin-installed-event) and [Plugin loaded event](/docs/en/monitoring-usage#plugin-loaded-event).

368`claude_code.plugin_installed` records each install, and `claude_code.plugin_loaded` records each enabled plugin at session start. Both events redact or omit third-party plugin and marketplace names unless you set `OTEL_LOG_TOOL_DETAILS=1`, as [Redacted plugin names in your backend](/docs/en/plugins/measure.md#redacted-plugin-names-in-your-backend) shows. Field lists are under [Plugin installed event](/docs/en/monitoring-usage.md#plugin-installed-event) and [Plugin loaded event](/docs/en/monitoring-usage.md#plugin-loaded-event).

369369

370370### Analytics API

371371

372On the Enterprise plan, `GET /v1/organizations/analytics/plugins` returns per-plugin, per-day install and invocation counts across Claude Code and Cowork. You can group the counts by user or RBAC group. Plugin activity that reaches Anthropic without a plugin name appears in one aggregate `third-party` row. See the [endpoint reference](https://platform.claude.com/docs/en/api/admin/analytics/plugins/list) and [Access data programmatically](/docs/en/analytics#access-data-programmatically) for the key it needs.

372On the Enterprise plan, `GET /v1/organizations/analytics/plugins` returns per-plugin, per-day install and invocation counts across Claude Code and Cowork. You can group the counts by user or RBAC group. Plugin activity that reaches Anthropic without a plugin name appears in one aggregate `third-party` row. See the [endpoint reference](https://platform.claude.com/docs/en/api/admin/analytics/plugins/list) and [Access data programmatically](/docs/en/analytics.md#access-data-programmatically) for the key it needs.

373373

374374## Plan for what managed settings can't enforce

375375

from line 379

379379* **Restricting entries inside an allowed marketplace**: the allowlist matches marketplace sources. To block one plugin from an allowed marketplace, set it to `false` in managed `enabledPlugins`.

380380* **Hiding `/plugin`**: no key disables the command. The nearest equivalent combines an allowlist naming only your marketplace, managed `enabledPlugins` entries for the plugins you supply, and `disableSideloadFlags`.

381381* **Gating `--plugin-dir` through the allowlist**: the allowlist doesn't cover `--plugin-dir`. `disableSideloadFlags` does.

382* **Enforcing the claude.ai plugin toggles through these keys**: [**Organization settings > Plugins & skills**](https://claude.ai/admin-settings/skills?tab=inventory) doesn't set the keys on this page. What members and your organization turn on there reaches the CLI as [synced plugins](/docs/en/plugins/loading#synced-plugins), which have their own controls.

383383

384384## Troubleshoot policy

385385

386386If plugin policy doesn't behave as expected on a machine, check for these symptoms first:

387387

388* **The managed file didn't parse**: when a `managed-settings.json` isn't valid JSON, Claude Code refuses to start and prints [an error naming the file](/docs/en/errors#managed-settings-document-could-not-be-parsed). A file that parses but has one invalid entry keeps the rest of its policy. See [Invalid entries in managed settings](/docs/en/managed-settings#invalid-entries-in-managed-settings).

388* **The managed file didn't parse**: when a `managed-settings.json` isn't valid JSON, Claude Code refuses to start and prints [an error naming the file](/docs/en/errors.md#managed-settings-document-could-not-be-parsed). A file that parses but has one invalid entry keeps the rest of its policy. See [Invalid entries in managed settings](/docs/en/managed-settings.md#invalid-entries-in-managed-settings).

389389* **The managed source didn't load**: run `/status` and look for `Enterprise managed settings` in the `Setting sources` line. If it's missing, the source didn't load.

390* **A user reports `blocked by enterprise policy`**: the message names the marketplace or its source. For an allowlist, it also lists the allowed sources. The user-facing entries are on [Troubleshoot plugins](/docs/en/plugins/troubleshooting).

391391* **A plugin the user disabled in `~/.claude/settings.json` still loads**: another settings source re-enabled it, such as a managed `enabledPlugins` entry that force-enables it. `/plugin` and `claude plugin list` show `Disabled in ~/.claude/settings.json but still loads` with that settings source.

392392

393393## Next steps

394394

395* [Marketplace reference](/docs/en/plugins/marketplace-reference#marketplace-sources): the `source` values `extraKnownMarketplaces`, `strictKnownMarketplaces`, and `blockedMarketplaces` accept

396* [Host and maintain a marketplace](/docs/en/plugins/host-marketplace): run the marketplace your policy points at

397* [Plugin security and trust](/docs/en/plugins/security): what a plugin can do on a machine and how to review one before installing

398* [Manage mods for your organization](/docs/en/plugins/mods/admin): turn off or limit mods, the plugins that run JavaScript inside Claude Code

399* [Server-managed settings](/docs/en/server-managed-settings): deliver these keys from the claude.ai admin console

400* [Troubleshoot plugins](/docs/en/plugins/troubleshooting#blocked-by-your-organization): the messages users see when policy blocks them

395* [Marketplace reference](/docs/en/plugins/marketplace-reference.md#marketplace-sources): the `source` values `extraKnownMarketplaces`, `strictKnownMarketplaces`, and `blockedMarketplaces` accept

396* [Host and maintain a marketplace](/docs/en/plugins/host-marketplace.md): run the marketplace your policy points at

397* [Plugin security and trust](/docs/en/plugins/security.md): what a plugin can do on a machine and how to review one before installing

398* [Manage mods for your organization](/docs/en/plugins/mods/admin.md): turn off or limit mods, the plugins that run JavaScript inside Claude Code

399* [Server-managed settings](/docs/en/server-managed-settings.md): deliver these keys from the claude.ai admin console

400* [Troubleshoot plugins](/docs/en/plugins/troubleshooting.md#blocked-by-your-organization): the messages users see when policy blocks them

401401

This page’s history 11 edits

26 Oct 2026 +5 −1
26 Oct 2026 +1 −1
22 Oct 2026 +62 −62
22 Oct 2026 +54 −54 · this one
22 Oct 2026 +4 −4
8 Oct 2026 +30 −32

The page’s own history →

Where it came from

The captureclaude-code
Upstream pagecode.claude.com

Around it

Every changethe ledger
That day22 Oct 2026