One read of Claude Documentationclaude-docs-20261103T180705Z
5 pages moved out of 281 read.
Pages moved
5
significant first
Pages read
281
in this capture
Captured
18:07 UTC
Corpus hash
7c50030c66b2
corpus-hash
What this read moved
1-5 of 5third-party/claude-desktop/admin-console Changed · +29 / -12 lines
### Limit Claude Desktop to your organization
from line 71
7171
7272### Start from an existing configuration file
7373
74If you already deploy Claude Desktop with an MDM profile, a bootstrap server, or a configuration built in the app, upload that configuration instead of entering each setting again. On the **Connection** page, click **Import configuration…**, then choose a `.json` file or paste the JSON. The console reads JSON in any of these forms:
74If you already deploy Claude Desktop with an MDM profile, a bootstrap server, or a configuration built in the app, upload that configuration instead of entering each setting again. On the **Connection** page, click **Import configuration…**, then choose a `.json` file or paste the JSON. Get the JSON from the place where your configuration is today:
7575
76* The file that Claude Desktop saves from **Developer → Configure Third-Party Inference… → Export → JSON config**, on macOS or Windows. Export it on the workstation where you built the configuration. On a device whose MDM profile or registry policy sets the Claude Desktop configuration, that window is read-only and doesn't offer this export.
77* The JSON that your bootstrap server returns.
78* A macOS `.mobileconfig` profile converted to JSON with `plutil -convert json -o config.json YourProfile.mobileconfig`.
79* A Linux `/etc/claude-desktop/managed-settings.json` file.
76* **Configuration built in Claude Desktop**: on the macOS or Windows workstation where you built it, go to **Developer → Configure Third-Party Inference… → Export → JSON config**. If an MDM profile or registry policy sets the Claude Desktop configuration on a device, the configuration window is read-only and its **Export** menu doesn't offer **JSON config**. Get the JSON from the policy or profile instead.
77* **Windows registry policy**: the console doesn't read `.reg` files. On a device that has the policy, run this command in PowerShell, in a folder that doesn't sync to a cloud drive:
8078
81For a Windows fleet, use the JSON config export, because the console doesn't read `.reg` files or registry policy.
79 ```powershell PowerShell wrap theme={null}
80 Get-ItemProperty 'HKLM:\SOFTWARE\Policies\Claude' | Select-Object * -ExcludeProperty PS* | ConvertTo-Json | Set-Content -Encoding UTF8 claude-policy.json
81 ```
8282
83 The command writes the policy's values to `claude-policy.json` in the current folder. If PowerShell can't find the path, or writes no file, replace `HKLM:` with `HKCU:` in the command to read user policy. The file holds every value in plain text, including any credential that the policy sets, so delete it after the upload.
84* **macOS `.mobileconfig` profile**: in Terminal on a Mac, run `plutil -convert json -o config.json YourProfile.mobileconfig` to convert the profile to JSON. For a signed profile, first run `security cms -D -i SignedProfile.mobileconfig -o YourProfile.mobileconfig` to remove the signature.
85* **Bootstrap server**: use the JSON that your server returns
86* **Linux device**: use the `/etc/claude-desktop/managed-settings.json` file
87* **Another source**: write the JSON yourself. Put the keys at the top level, with names exactly as in the [configuration reference](https://claude.com/docs/third-party/claude-desktop/configuration.md).
88
8389The console fills in the matching settings and lists anything in the file that it can't store, such as credentials, bootstrap keys, and values that are set automatically from your organization, like the display name. It then shows every change against the saved configuration, and replaces the configuration when you click **Replace configuration**. If the connection in the file can't be stored, for example because it relies on an API key or token in the file, the console keeps your saved connection instead.
8490
85If the file was exported from Claude Desktop, check the **Automatically import earlier third-party sessions** switch on the **Capabilities** page after the upload. The exported file can mark this switch as off even if nobody turned it off, and the console keeps the value from the file.
91If the configuration was built in Claude Desktop, check the **Automatically import earlier third-party sessions** switch on the **Capabilities** page after the upload. A configuration built there can mark this switch as off even if nobody turned it off, and the console keeps the value from the file.
8692
8793To move the devices and users of an existing fleet to this configuration, see [Migrate an existing fleet to the admin console](#migrate-an-existing-fleet-to-the-admin-console).
8894
from line 281
275281* You have saved a configuration that includes the inference provider, as described under [Configure Claude Desktop](#configure-claude-desktop)
276282* Single sign-on is connected, if you use it, and the users you want on this deployment are invited or provisioned, as described under [Connect your identity provider](#connect-your-identity-provider)
277283* Devices run the latest Claude Desktop release, installed as described in [Installation and setup](https://claude.com/docs/third-party/claude-desktop/installation.md)
278* Devices carry no MDM-delivered Claude Desktop configuration other than the [app-behavior keys](https://claude.com/docs/third-party/claude-desktop/mdm.md#update-keys-and-managed-precedence) (the update, configuration re-check, relaunch window, and network proxy keys). For a device that keeps a managed profile or registry policy with any other key, see [Devices with a managed profile](#devices-with-a-managed-profile).
284* Devices carry no MDM-delivered Claude Desktop configuration other than the [app-behavior keys](https://claude.com/docs/third-party/claude-desktop/mdm.md#update-keys-and-managed-precedence) (the update, configuration re-check, relaunch window, and network proxy keys) and [`forceLoginOrgUUID`](#keep-a-device-on-its-managed-profile). For a device that keeps a managed profile or registry policy with any other key, see [Devices with a managed profile](#devices-with-a-managed-profile).
279285* Devices can reach `api.anthropic.com` at every launch and while the app runs, and `claude.ai`, `hcaptcha.com`, and `*.hcaptcha.com` when users sign in, in addition to the hosts on [Telemetry and egress](https://claude.com/docs/third-party/claude-desktop/telemetry.md)
286* You have added the device, network, and provider controls that you want, as described under [Limit Claude Desktop to your organization](#limit-claude-desktop-to-your-organization)
280287
281288A device picks up the configuration from the admin console the first time the user signs in to Claude in the app. Walk through it on a test device first.
282289
from line 307
300307
301308Give each user their own computer login. Claude Desktop keeps conversation history for each computer login and organization, not for each Claude account, and **Sign out** doesn't delete it. Members of your organization who share a computer login see each other's conversations. If people must share a login, ask each person to choose **Sign out** from the account menu when they finish, so that the next person signs in with their own Claude account.
302309
310### Limit Claude Desktop to your organization
311
312The admin console alone doesn't keep a device on your organization's settings. The console delivers your settings to members who sign in to Claude Desktop. The app applies the settings on the device and stores the sign-in in the user's own [application data directory](https://claude.com/docs/third-party/claude-desktop/data-storage.md#where-data-lives). A user can stop using your settings, for example by signing out, deleting the app data, or setting up their own inference provider in the app.
313
314These controls still apply when a user stops using your settings:
315
316* **Device management**: deploy `forceLoginOrgUUID` with your Claude organization's ID in a machine-level managed profile, as described under [Keep a device on its managed profile](#keep-a-device-on-its-managed-profile). The app then ignores an inference provider that a user sets up in the app and limits standard Claude Desktop sign-in to your organization. You continue to manage settings in the console.
317* **Network**: at your firewall or secure web gateway, block inference endpoints other than your provider's. The app needs `api.anthropic.com` and `claude.ai`, so limit those hosts to your Claude organizations, including your admin console organization, with [tenant restrictions](https://support.claude.com/en/articles/13198485-enforce-network-level-access-control-with-tenant-restrictions).
318* **Inference provider**: in your provider's access policies, set who can send model requests to your provider from any app or configuration.
319
303320### Users in more than one Claude organization
304321
305322A user's Claude account can belong to your deployment's organization and to other Claude organizations, and the user can move between them in Claude Desktop. When such a user signs in, the app opens in their other organization and asks whether to switch to yours, with **Switch and restart** and **Not now** buttons. A user who chooses **Not now** isn't asked again on that device and can switch later by choosing your organization from the account menu. Each move into or out of your organization restarts the app, because third-party mode runs as a separate app configuration. To go back, the user chooses **Sign out** and signs in to Claude again after the restart. From Claude Desktop 1.49585.0, they can instead pick their other organization from the account menu, which also restarts the app and asks them to sign in.
from line 396
379396
380397**4. Remove the managed profile**
381398
382Remove the Claude Desktop configuration profile or registry policy, including one that carries only bootstrap keys. You can keep a profile that sets only the [app-behavior keys](https://claude.com/docs/third-party/claude-desktop/mdm.md#update-keys-and-managed-precedence).
399Remove the Claude Desktop configuration profile or registry policy, including one that carries only bootstrap keys. You can keep a profile that sets only the [app-behavior keys](https://claude.com/docs/third-party/claude-desktop/mdm.md#update-keys-and-managed-precedence) and [`forceLoginOrgUUID`](#keep-a-device-on-its-managed-profile).
383400
384401* **Devices that keep a profile with any other key**: see [Devices with a managed profile](#devices-with-a-managed-profile)
385402* **Devices configured in the app**: the user signs out and chooses the Anthropic sign-in option, as described under [Single-machine setup](https://claude.com/docs/third-party/claude-desktop/installation.md#single-machine-setup)
from line 438
421438
422439## Devices with a managed profile
423440
424A managed profile is a macOS configuration profile, a Windows registry policy, or the Linux `/etc/claude-desktop/managed-settings.json` file, from [MDM](https://claude.com/docs/third-party/claude-desktop/mdm.md) or [bootstrap](https://claude.com/docs/third-party/claude-desktop/bootstrap.md) delivery. A device whose profile sets any key other than the [app-behavior keys](https://claude.com/docs/third-party/claude-desktop/mdm.md#update-keys-and-managed-precedence) uses the profile's configuration until its user moves the device to the admin console's configuration. Where you can, remove such a profile before users sign in, as described under [Migrate an existing fleet to the admin console](#migrate-an-existing-fleet-to-the-admin-console).
441A managed profile is a macOS configuration profile, a Windows registry policy, or the Linux `/etc/claude-desktop/managed-settings.json` file, from [MDM](https://claude.com/docs/third-party/claude-desktop/mdm.md) or [bootstrap](https://claude.com/docs/third-party/claude-desktop/bootstrap.md) delivery. A device whose profile sets any key other than the [app-behavior keys](https://claude.com/docs/third-party/claude-desktop/mdm.md#update-keys-and-managed-precedence) uses the profile's configuration until its user moves the device to the admin console's configuration. Where you can, remove every such key other than `forceLoginOrgUUID` before users sign in, as described under [Migrate an existing fleet to the admin console](#migrate-an-existing-fleet-to-the-admin-console).
425442
426443To prevent the move, or to allow it only for your organization, see [Keep a device on its managed profile](#keep-a-device-on-its-managed-profile). Before Claude Desktop 2.37337.0, the device uses the profile and ignores the admin console.
427444
third-party/claude-desktop/data-storage Changed · +8 / -2 lines
from line 144
144144
145145With [Unified Claude](https://claude.com/docs/third-party/claude-desktop/unified-claude.md) on, a conversation started from the home screen on a device that can run Cowork is a Cowork session. `coworkSessionRetentionDays` covers it along with users' other Cowork tasks, and `chatSessionRetentionDays` still covers Chat conversations. While `coworkSessionRetentionDays` is unset, neither key deletes a home-screen conversation that is a Cowork session, even if `chatSessionRetentionDays` is set. If you use `chatSessionRetentionDays`, keep it and set `coworkSessionRetentionDays` as well.
146146
147The app deletes whole sessions in the background. A chat or Cowork task is deleted with its attached files and outputs, and a Code session with its conversation. Projects, memory, and the files in a Code session's working folder stay, and Code sessions on an SSH host aren't affected. A session that is running or open on screen is skipped until a later pass. On a device that gets its configuration from a server, the app stops deleting idle sessions shortly after it loses contact with that server.
147The app deletes whole sessions in the background:
148148
149* **Chats**: the app deletes a chat, its copies of attached files, its outputs, and the live artifacts (interactive pages) that Claude created in the chat. The live artifacts of chats deleted before Claude Desktop 4.16336.0 stay on the device.
150* **Cowork tasks**: the app deletes a task, its copies of attached files, and its outputs. The task's live artifacts stay. A home-screen conversation that is a Cowork session is deleted the same way, and its live artifacts stay.
151* **Code sessions**: the app deletes a session and its conversation. It also removes the session's [Git worktree](https://code.claude.com/docs/en/worktrees), except in some cases, such as when the worktree has uncommitted changes or the session is pinned. Other files in the session's working folder stay, and Code sessions on an SSH host or in WSL aren't affected.
152
153Projects and memory stay. A session that is running or open on screen is skipped until a later pass. On a device that gets its configuration from a server, the app stops deleting idle sessions shortly after it loses contact with that server.
154
149155### Keep sessions for some users
150156
151157> [!WARNING]
from line 183
177183
178184In the window, users can clean up their own inactive sessions on the device, except pinned ones:
179185
180* **Chats and Cowork tasks**: the app deletes them, including runs of scheduled tasks. It also deletes their outputs and their copies of attached files in the [application-data directory](#where-data-lives). Files outside that directory stay, such as files in `~/Claude/` or in folders that the user connected.
186* **Chats and Cowork tasks**: the app deletes them, including runs of scheduled tasks. It also deletes their outputs and their copies of attached files in the [application-data directory](#where-data-lives). For a chat, the app also deletes the live artifacts (interactive pages) that Claude created in the chat. Other files stay, such as the live artifacts of a Cowork task or of a [home-screen conversation that is a Cowork session](https://claude.com/docs/third-party/claude-desktop/unified-claude.md), the rest of `~/Claude/`, and files in folders that the user connected. The live artifacts of chats deleted before Claude Desktop 4.16336.0 stay too.
181187* **Code sessions**: the app removes their [Git worktrees](https://code.claude.com/docs/en/worktrees) and, if the user chooses, deletes the sessions with their conversations
182188
183189Users can't undo these deletions.
third-party/claude-desktop/extensions Changed · +4 / -3 lines
from line 439
439439
440440When a hook blocks tool calls on such a device, check for each of these causes:
441441
442* **The hook fails or times out**: on a Windows device without Git for Windows, a [`PreToolUse`](https://code.claude.com/docs/en/hooks#pretooluse) or [`PermissionRequest`](https://code.claude.com/docs/en/hooks#permissionrequest) command hook that has no `args` and no `onFailure` field blocks the tool call when it fails or times out, whatever `shell` it sets. A hook written for Bash that was given `"shell": "powershell"` can block every tool call that it matches. Under Windows PowerShell 5.1, which Claude Code uses when PowerShell 7 isn't installed, a program that writes to stderr under a redirect in the command, such as `2>&1`, can make the hook count as failed although the program exits with 0. The hook error that Claude receives includes `blocking because Git Bash wasn't found`.
442* **The hook fails or times out**: a [`PreToolUse`](https://code.claude.com/docs/en/hooks#pretooluse) or [`PermissionRequest`](https://code.claude.com/docs/en/hooks#permissionrequest) command hook that has no `args` and no `onFailure` field blocks the tool call when it fails or times out, whatever `shell` it sets. A hook written for Bash that was given `"shell": "powershell"` can block every tool call that it matches. Under Windows PowerShell 5.1, which Claude Code uses when PowerShell 7 isn't installed, a program that writes to stderr under a redirect in the command, such as `2>&1`, can make the hook count as failed although the program exits with 0. The hook error that Claude receives includes `blocking because Git Bash wasn't found`.
443* **The command is only a quoted path**: a `PreToolUse` or `PermissionRequest` hook that sets none of `shell`, `args`, and `"onFailure": "continue"` blocks the tool call when its command is only a quoted path, as in `"command": "\"C:\\path\\guard.exe\""`. Bash runs that program, but PowerShell only prints the path. Adding `"onFailure": "continue"` or `"shell": "powershell"` stops the blocking, but the program still doesn't start, so the hook checks nothing.
443444* **The hook ends with exit code 2**: a `PreToolUse` hook that ends with exit code 2 blocks the tool call whatever `onFailure` says, and the error that Claude then receives is the hook's own error output. In PowerShell a `PreToolUse` hook ends with 2 when its command ends with a program that exits with 2. That reaches a hook written for Bash such as `python $CLAUDE_PROJECT_DIR/check.py`, even with `"onFailure": "continue"`. A bare `$CLAUDE_PROJECT_DIR` is empty in PowerShell, so Python can't open its script and exits with 2.
444445
445446If your Windows devices have hooks, in a plugin or in Claude Code [managed settings](https://claude.com/docs/third-party/claude-desktop/code.md#interaction-with-claude-code%E2%80%99s-own-managed-settings), make one of these changes:
446447
447448* **Keep a hook written for Bash**: install Git for Windows in its default location (`C:\Program Files\Git`) on each device, remove `"shell": "powershell"` from the hook if it has it, then quit and reopen Claude Desktop
448* **Run the hook without a shell**: write the hook in [exec form](https://code.claude.com/docs/en/hooks#exec-form-and-shell-form), with an executable such as an `.exe` (not a `.cmd` or `.bat` file) in `command` and its arguments in `args` (`"args": []` if it has none). Write the project folder as `${CLAUDE_PROJECT_DIR}`, braces included, since no shell expands `$CLAUDE_PROJECT_DIR` there. A Bash script can't run this way without Git.
449* **Keep a hook written for PowerShell**: set `"shell": "powershell"` and `"onFailure": "block"` on it, and start its program with the call operator, as in `& "C:\path\guard.exe"`, since a quoted path alone starts nothing. Make the program the last thing that the command runs, and in a `PreToolUse` hook have it exit with 0 to let the tool call go on and with 2 to block it. A `.ps1` script does so through its own `exit 0` or `exit 2`. A script whose last line runs a program ends with 0 even when that program exits with 2, so start the program from the command and not from inside a script. Don't redirect the program's stderr in the command, and don't end the command with `exit $LASTEXITCODE`. If the program can't start, `exit $LASTEXITCODE` exits with 0 and the tool call goes ahead, even with `"onFailure": "block"`.
449* **Run the hook without a shell**: write the hook in [exec form](https://code.claude.com/docs/en/hooks#exec-form-and-shell-form), with an executable such as an `.exe` (not a `.cmd` or `.bat` file) in `command` and its arguments in `args` (`"args": []` if it has none). Write the path without quotes of its own, even when it has spaces, as in `"command": "C:\\Program Files\\Guard\\guard.exe"`. Write the project folder as `${CLAUDE_PROJECT_DIR}`, braces included, since no shell expands `$CLAUDE_PROJECT_DIR` there. A Bash script can't run this way without Git.
450* **Keep a hook written for PowerShell**: set `"shell": "powershell"` and `"onFailure": "block"` on it, and start its program with the call operator, as in `"command": "& \"C:\\path\\guard.exe\""`. Make the program the last thing that the command runs, and in a `PreToolUse` hook have it exit with 0 to let the tool call go on and with 2 to block it. A `.ps1` script does so through its own `exit 0` or `exit 2`. A script whose last line runs a program ends with 0 even when that program exits with 2, so start the program from the command and not from inside a script. Don't redirect the program's stderr in the command, and don't end the command with `exit $LASTEXITCODE`. If the program can't start, `exit $LASTEXITCODE` exits with 0 and the tool call goes ahead, even with `"onFailure": "block"`.
450451
451452After either of the first two changes, a hook that fails or times out lets the tool call go ahead. To stop the tool call instead, add [`"onFailure": "block"`](https://code.claude.com/docs/en/hooks#block-the-action-when-a-hook-fails) to the hook.
452453
third-party/claude-desktop/in-app-configuration Changed · +1 / -1 lines
from line 30
3030| `.reg` policy file | Intune, Group Policy, or any Windows MDM |
3131| ADMX template (`.zip`) | Intune or Group Policy; a schema-only template, you enter values in the management console |
3232| Profile Manifest (`.plist`) | Jamf, ProfileCreator, or similar macOS tools; a schema-only template, you enter values in your tool |
33| JSON config | The response body for a [bootstrap server](https://claude.com/docs/third-party/claude-desktop/bootstrap.md), or a configuration file for a device without MDM |
33| JSON config | The response body for a [bootstrap server](https://claude.com/docs/third-party/claude-desktop/bootstrap.md), a file to import into the [Enterprise Admin Console](https://claude.com/docs/third-party/claude-desktop/admin-console.md#start-from-an-existing-configuration-file), or a configuration file for a device without MDM |
3434| Firewall allowlist (`.txt`) | Your firewall or network team |
3535
3636See [Deploy with MDM](https://claude.com/docs/third-party/claude-desktop/mdm.md) or [Deploy with a bootstrap server](https://claude.com/docs/third-party/claude-desktop/bootstrap.md) to distribute what you exported.
third-party/claude-desktop/mdm Changed · +1 / -1 lines
from line 129
129129
130130When a managed source sets any key other than the [app-behavior keys](#update-keys-and-managed-precedence) listed below, the managed configuration takes effect, the in-app configuration window becomes read-only, and locally authored values in `configLibrary/` are ignored.
131131
132A user who signs in to any organization that uses the [Enterprise Admin Console](https://claude.com/docs/third-party/claude-desktop/admin-console.md) can move the device to that organization's configuration. To prevent that, set [`disableDeploymentModeChooser`](https://claude.com/docs/third-party/claude-desktop/configuration#disabledeploymentmodechooser) to `true`, as described under [Keep a device on its managed profile](https://claude.com/docs/third-party/claude-desktop/admin-console.md#keep-a-device-on-its-managed-profile).
132A user who signs in to any organization that uses the [Enterprise Admin Console](https://claude.com/docs/third-party/claude-desktop/admin-console.md) can move the device to that organization's configuration. To prevent that, set [`disableDeploymentModeChooser`](https://claude.com/docs/third-party/claude-desktop/configuration#disabledeploymentmodechooser) to `true`, as described under [Keep a device on its managed profile](https://claude.com/docs/third-party/claude-desktop/admin-console.md#keep-a-device-on-its-managed-profile). To allow the move only to your organization, set [`forceLoginOrgUUID`](https://claude.com/docs/third-party/claude-desktop/admin-console#keep-a-device-on-its-managed-profile) instead.
133133
134134### Update keys and managed precedence
135135