From 83c93906302bf45cbd0d9b50bce8cd4e61483dd4 Mon Sep 17 00:00:00 2001 From: Guy Moses Date: Thu, 9 Jul 2026 15:43:38 +0300 Subject: [PATCH 1/2] docs: add organization rollout guide for Claude Code managed settings Document how Team/Enterprise admins distribute and configure the plugin org-wide: auto-install via the Organization plugins page, push non-secret config through server-managed settings (or MDM/on-disk managed-settings.json), and keep the auth token in the per-user OS keychain rather than inlining it in plaintext policy. Co-Authored-By: Claude Opus 4.8 (1M context) --- .claude-plugin/README.md | 41 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) diff --git a/.claude-plugin/README.md b/.claude-plugin/README.md index e0350ca..6f0d8c8 100644 --- a/.claude-plugin/README.md +++ b/.claude-plugin/README.md @@ -61,6 +61,47 @@ Both `enabledPlugins` and `pluginConfigs` are committed to git. Each developer t > **Worktree / multi-clone caveat:** Project-scoped installs are keyed to the repository's absolute path. If you use git worktrees or multiple clones, the plugin fails to load in the second checkout. Use `--scope user` instead (`claude plugin install dash0@claude-plugins-official --scope user`). +## Organization rollout (Team / Enterprise admins) + +Admins can install and configure the plugin for every member with no per-developer steps, using [Claude Code managed settings](https://code.claude.com/docs/en/server-managed-settings). There are two parts, configured in different places: + +**1. Auto-install.** In the claude.ai **Organization plugins** admin page, set the plugin to **Required** (auto-installed, can't be removed) or **Installed by default**. This is what downloads the plugin onto members' machines; it takes effect on their next session. Enabling the plugin in managed settings alone does not install it. + +**2. Push configuration.** In claude.ai → **Admin Settings → Claude Code → Managed settings** (`https://claude.ai/admin-settings/claude-code`), add the config. Managed settings take top precedence and can't be overridden by user or project settings: + +```json +{ + "enabledPlugins": { "dash0@claude-plugins-official": true }, + "pluginConfigs": { + "dash0@claude-plugins-official": { + "options": { + "OTLP_URL": "https://ingress..aws.dash0.com", + "DATASET": "default", + "TEAM_NAME": "platform" + } + } + } +} +``` + +Clients fetch these at startup and re-poll hourly; the payload is cached at `~/.claude/remote-settings.json` and applied in-memory (not written to an on-disk `managed-settings.json`). Requires Claude for Teams/Enterprise and the Owner or Primary Owner role. Server-managed settings are not delivered on Amazon Bedrock, Google Vertex, or Microsoft Foundry. + +**The auth token.** Push only the non-secret keys via managed settings, and have each developer add the token once via `/plugin → Configure`. `AUTH_TOKEN` is declared `sensitive`, so Claude Code stores it encrypted in the OS keychain — never in `settings.json`. + +Do **not** inline the token into managed `pluginConfigs.options` or the top-level `env` block: those are stored in plaintext (in the admin console and cached at `~/.claude/remote-settings.json` on every machine), and Claude Code has no secret-reference mechanism to avoid it. Even for an ingest-only token, prefer the keychain. + +**MDM / on-disk alternative.** If you manage devices with MDM (Jamf, Intune, Kandji) or prefer a file on disk, deploy the same JSON as `managed-settings.json` instead of using the console: + +| OS | Path | +|---|---| +| macOS | `/Library/Application Support/ClaudeCode/managed-settings.json` | +| Linux / WSL | `/etc/claude-code/managed-settings.json` | +| Windows | `C:\Program Files\ClaudeCode\managed-settings.json` | + +> Server-managed (console) and endpoint-managed (file) settings do **not** merge — if the console delivers any keys, the on-disk file is ignored. Pick one channel per org. + +**Verify.** A developer runs `/status` → **Setting sources** shows `Enterprise managed settings`; the session banner reads `dash0: connected`; and the session appears in Dash0 under the configured dataset. + ## Configuration After installing, you'll need: From 15ad4020a5788fb617a2d4af2931cdeee3b509ef Mon Sep 17 00:00:00 2001 From: Guy Moses Date: Thu, 9 Jul 2026 15:46:55 +0300 Subject: [PATCH 2/2] docs: trim auth-token caution to one line Co-Authored-By: Claude Opus 4.8 (1M context) --- .claude-plugin/README.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/.claude-plugin/README.md b/.claude-plugin/README.md index 6f0d8c8..b029498 100644 --- a/.claude-plugin/README.md +++ b/.claude-plugin/README.md @@ -86,9 +86,7 @@ Admins can install and configure the plugin for every member with no per-develop Clients fetch these at startup and re-poll hourly; the payload is cached at `~/.claude/remote-settings.json` and applied in-memory (not written to an on-disk `managed-settings.json`). Requires Claude for Teams/Enterprise and the Owner or Primary Owner role. Server-managed settings are not delivered on Amazon Bedrock, Google Vertex, or Microsoft Foundry. -**The auth token.** Push only the non-secret keys via managed settings, and have each developer add the token once via `/plugin → Configure`. `AUTH_TOKEN` is declared `sensitive`, so Claude Code stores it encrypted in the OS keychain — never in `settings.json`. - -Do **not** inline the token into managed `pluginConfigs.options` or the top-level `env` block: those are stored in plaintext (in the admin console and cached at `~/.claude/remote-settings.json` on every machine), and Claude Code has no secret-reference mechanism to avoid it. Even for an ingest-only token, prefer the keychain. +**The auth token.** Push only the non-secret keys via managed settings, and have each developer add the token once via `/plugin → Configure`. `AUTH_TOKEN` is declared `sensitive`, so Claude Code stores it encrypted in the OS keychain — never in `settings.json`. Avoid inlining it into managed `pluginConfigs.options` or the `env` block, which are stored in plaintext. **MDM / on-disk alternative.** If you manage devices with MDM (Jamf, Intune, Kandji) or prefer a file on disk, deploy the same JSON as `managed-settings.json` instead of using the console: