> ## Documentation Index
> Fetch the complete documentation index at: https://platform.atlan.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Managed installation

> Deploy the Claude Code trace plugin across a fleet with Claude Code managed settings.

Claude Code managed settings are the supported administrator path for local
coding-agent tracing. This page is for whoever owns endpoint configuration.

<Note>
  **Preview.** macOS and Windows artifacts are not yet natively signed, so the
  preview channel is not approved for production rollout. Complete your
  organization's signing and disclosure review before a fleet deployment.
</Note>

## Before you start

* Administrator control of the managed-settings path on each platform.
* A fleet configuration system — Jamf, Intune, Group Policy, or equivalent.
* The immutable wrapper tag your organization has reviewed and approved.
* A decision on content capture. It currently defaults to **on**, so prompts
  and tool payloads are recorded. Get that approved before you deploy.

## 1. Prepare the settings file

Start from `examples/managed-settings/managed-settings.json` in the
`atlanai/claude-plugins` repository. The template pins an immutable preview
wrapper; replace the `ref` with the tag your organization approved.

```json theme={null}
{
  "strictKnownMarketplaces": [
    {
      "source": "github",
      "repo": "atlanai/claude-plugins",
      "ref": "claude-v0.1.1"
    }
  ],
  "extraKnownMarketplaces": {
    "atlanai": {
      "source": {
        "source": "github",
        "repo": "atlanai/claude-plugins",
        "ref": "claude-v0.1.1"
      }
    }
  },
  "enabledPlugins": {
    "atlanai@atlanai": true
  },
  "pluginTrustMessage": "atlanai captures coding-agent telemetry and content by default. Contact your administrator for the approved privacy policy."
}
```

<Warning>
  The `strictKnownMarketplaces` and `extraKnownMarketplaces` source objects must
  match **exactly**. A `ref` set in one and not the other is a misconfiguration,
  not a partial pin.
</Warning>

The file contains no user credential, OAuth token, GitHub credential, or
workspace ID. Each user signs in separately through the plugin's OAuth command,
and Agent Gateway resolves that user's default workspace.

## 2. Deploy it

Copy the JSON bytes to the managed-settings path with administrator ownership
and read-only permissions for ordinary users:

| Platform      | Managed settings path                                           |
| ------------- | --------------------------------------------------------------- |
| 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`             |

## 3. Verify on one machine first

Before the fleet, confirm on a single enrolled device:

1. Claude Code shows the `atlanai` plugin as enabled and sourced from the
   pinned marketplace.
2. `/login` completes the browser flow.
3. `/status` reports a healthy daemon and authentication.
4. One completed session appears in Agent Registry, in the workspace you
   expect for that user.

## What the template deliberately does not set

The base template force-enables only `atlanai@atlanai`. It does **not** set
`allowManagedHooksOnly` or `strictPluginOnlyCustomization`, because those keys
also disable unrelated user and project customizations that have nothing to do
with Atlan.

If your organization intends that broader lockdown, review and merge
`examples/managed-settings/optional-customization-lockdown.json` as an explicit
policy decision.

## How pinning interacts with updates

Two things update independently:

| What                     | Controlled by                                                                      |
| ------------------------ | ---------------------------------------------------------------------------------- |
| Dispatcher and bootstrap | the immutable `claude-v<version>` wrapper tag you pin                              |
| Runtime                  | the Ed25519-signed stable or preview channel declared inside that reviewed wrapper |

So pinning a wrapper tag does not freeze the runtime. To permit automatic
wrapper updates, remove `ref` from **both** marketplace source objects as a
deliberate policy choice.

`channels/stable` requires native Apple and Windows signatures plus the Linux
Sigstore policy. `channels/preview` may use manifest-only macOS and Windows
artifacts, and is never an implicit fallback from stable.

## Organization chat and Cowork

Claude's organization plugin page installs into Claude chat and Cowork. **That
is a separate surface and does not install the local Claude Code tracing
runtime.** Do not treat an organization-chat installation as fleet coverage for
session capture unless a recorded canary proves it also provisions Claude Code
hooks.

For that surface, begin with **Available** or **Installed by default**. Do not
use **Required** while content capture defaults to on, unless your organization
has approved the disclosure, support ownership, rollback, and native
platform-signing gates.

## Upgrade, rollback, and removal

* **Upgrade** by moving the managed template to a higher immutable
  `claude-v<version>` tag. Never reuse an existing wrapper tag.
* **Runtime rollback** is explicit. A channel may move forward to a newer
  signed manifest, but automatic downgrade is rejected; use the runtime
  rollback command on an already-installed machine.
* **Removal** stops future hook delivery. It does **not** delete OAuth
  credentials, installed runtime versions, the SQLite journal, cursor state,
  outbox records, or historical sessions. Purge is a separate, explicit
  operation by the user or an administrator.
* Direct settings-hook installation is offered again only after the marketplace
  heartbeat is no longer active. It is never silently restored.

## Related

<CardGroup cols={2}>
  <Card title="Claude Code trace plugin" icon="plug" href="/plugins/claude-code">
    What the plugin captures and how a user verifies it.
  </Card>

  <Card title="MDM deployment" icon="mobile" href="/admin/desktop-deployment/index">
    Deploying Atlan Desktop through device management.
  </Card>
</CardGroup>