One read of Claude Documentationclaude-docs-20261110T183708Z
14 pages moved out of 287 read.
Pages moved
14
significant first
Pages read
287
in this capture
Captured
18:37 UTC
Corpus hash
35c9423af80c
corpus-hash
What this read moved
1-14 of 14third-party/claude-desktop/configuration Changed · +5 / -3 lines
from line 1139
11391139>
11401140> Each entry is a model ID string or an object:
11411141>
1142> ```json theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}
1142> ```json theme={null} theme={null}
11431143> [
11441144> {"name": "claude-sonnet-5",
11451145> "supports1m": true},
from line 3985
39853985* `"ask"`: the user approves every call; no session-scoped or standing grants are offered.
39863986* `"blocked"`: the tool is removed from Claude's session; connector settings show it as blocked by your organization.
39873987
3988In Cowork's [**Automatically approve**](#automodeenabled), a safety classifier still reviews calls to a tool set to `"allow"`, and can block them. See [Run vetted connector tools without classifier review](https://claude.com/docs/third-party/claude-desktop/code.md#run-vetted-connector-tools-without-classifier-review).
3988In Cowork's [**Automatically approve**](#automodeenabled), a safety classifier still reviews calls to a tool set to `"allow"`, and can block them. See [Run vetted connector tools without classifier review](https://claude.com/docs/third-party/claude-desktop/code.md#run-vetted-connector-tools-without-classifier-review). In a task or scheduled run that Cowork has switched to **Manually approve**, for example because its model doesn't support Auto mode, `"allow"` still applies with no classifier review.
39893989
39903990Claude's calls to a tool with no policy entry stay under the user's control (built-in connectors apply default policies to some tools): outside [**Auto mode**](#automodeenabled) and bypass permissions mode, the user is prompted and can approve once, approve for the rest of the task (offered for tools that can modify data), or grant a standing approval unless [`mcpPersistentAlwaysAllowEnabled`](#mcppersistentalwaysallowenabled) is `false`. The app reads a `toolPolicy` value other than `"allow"`, `"ask"`, or `"blocked"`, such as `"ask-session"`, as `"blocked"` for that tool and reports a configuration error, so write `"ask"` in place of `"ask-session"`. Managed policies take precedence over user grants, and enforcement happens in the desktop host process, not only in the prompt UI. A deny-by-default posture, `"*": "blocked"` plus exact `"allow"` entries for approved tools, is supported, including in Code sessions. See the [`managedMcpServers` reference](#managedmcpservers) for wildcard matching, precedence rules, and built-in connector defaults.
39913991
from line 4009
40094009
40104010In Code sessions, an allow rule already in Claude Code's own settings files keeps allowing the tool even while `mcpPersistentAlwaysAllowEnabled` is `false`, until someone removes it.
40114011
4012`mcpScheduledTaskApprovalLifetimeDays` also limits a scheduled Cowork task's [approval to delete files in a folder](https://claude.com/docs/third-party/claude-desktop/scheduled-tasks.md#approvals-that-last-across-runs). It lasts the number of days you set, or 30 days while the key is unset. At `0`, or while the key is unset and `mcpPersistentAlwaysAllowEnabled` is `false`, the prompt doesn't offer it and stored approvals aren't used.
4013
40124014The time limit doesn't cover:
40134015
4014* **Folder, browser, and built-in tool approvals:** these approvals never expire.
4016* **Folder access, browser, and other built-in tool approvals:** these approvals never expire.
40154017* **Account-wide grants in Cowork:** the account-wide **Always allow** and **Allow for all tasks** grants never expire. Of the two keys, only `mcpPersistentAlwaysAllowEnabled` affects them.
40164018* **Claude Code allow rules in Code sessions:** an allow rule in Claude Code's own settings files, such as one saved when a user chose **Always allow** before the key was set, keeps allowing the tool, even with a value of `0`, until someone removes it. For a scheduled task, look in the project's `.claude/settings.local.json` file.
40174019
third-party/claude-desktop/data-storage Changed · +12 / -14 lines
from line 33
3333| Path | Contents |
3434| - | - |
3535| `ant-did` | The random device identifier described above. |
36| `configLibrary/` | Locally authored configuration (from the in-app configuration window). `_meta.json` records which saved configuration is applied; each is a `<id>.json` file alongside it. API keys in these files are encrypted (see [Credentials](#credentials)). Ignored when a managed profile is present. |
36| `configLibrary/` | Locally authored configuration (from the in-app configuration window). `_meta.json` records which saved configuration is applied; each is a `<id>.json` file alongside it. API keys in these files are encrypted where the app can use the device's secure storage (see [Credentials](#credentials)). Ignored when a managed profile is present. |
3737| `local-agent-mode-sessions/.../cowork_account_settings.json` | User-level preferences set in the app, such as locale, the memory toggle, and the text entered under **Instructions for Claude** and **Global instructions**. |
3838| `local-agent-mode-sessions/` | Cowork and Chat conversation history. One `local_<uuid>.json` file plus a working directory per session, scoped by the `ant-did` device identifier and the organization ID, not by who is signed in to the app. The working directory includes an `uploads/` subdirectory with copies of files attached to the conversation and an `outputs/` subdirectory for files Claude creates. |
3939| `local-agent-mode-sessions/.../memory/` | Cowork memory: a `CLAUDE.md` instructions file plus a `memory/` subdirectory of Markdown notes Claude writes about the user's preferences, projects, and feedback. See [Memory](#memory). |
from line 124
124124
125125Credentials are handled according to how they're delivered:
126126
127* **Managed configuration** (for example, `inferenceGatewayApiKey`, `inferenceBedrockBearerToken`): read from the OS preference store or registry at launch and held in memory. The app also writes resolved credentials to a small set of transient, owner-only files for its own session processes, described below.
128* **API keys saved in the in-app configuration window**: stored in the `configLibrary/` files, encrypted with the operating system's secure storage (Keychain on macOS, DPAPI on Windows, GNOME Keyring or KWallet on Linux). Requires Claude Desktop 4.4212.0 or later, which also encrypts a key that an earlier version saved, at the next launch where secure storage is available. See [Unreadable saved API keys](#unreadable-saved-api-keys).
127* **Managed configuration** (for example, `inferenceGatewayApiKey`, `inferenceBedrockBearerToken`): read from the OS preference store or registry at launch and held in memory.
128* **API keys saved in the in-app configuration window**: stored in the `configLibrary/` files, encrypted with the operating system's secure storage where the app can use it (Keychain on macOS, DPAPI on Windows, GNOME Keyring or KWallet on Linux). Requires Claude Desktop 4.4212.0 or later, which also encrypts a key that an earlier version saved, at the next launch where secure storage is available. See [Unreadable saved API keys](#unreadable-saved-api-keys).
129129* **OAuth tokens** (in-app Google sign-in, MCP servers with `oauth: true` in `managedMcpServers` or in an `org-plugins/` plugin): stored in the application-data directory, encrypted with the operating system's secure storage (Keychain on macOS, DPAPI on Windows).
130130* **[Sign-ins to plugin servers](https://claude.com/docs/third-party/claude-desktop/extensions.md#sign-in-to-a-plugin-server)**: the OAuth tokens from a sign-in outside **Code** are stored as follows, and any program that runs under the user's OS account can read them:
131131
from line 140
140140
141141### Transient credential files
142142
143Parts of each session run as separate processes: the sandbox VM for Cowork sessions, and the Claude Code runtime for Code sessions. Processes that cannot receive credentials through an in-memory channel read them from short-lived files that the app writes for them. All of these files are created with owner-only permissions and are cleaned up automatically:
143Processes that cannot receive credentials through an in-memory channel read them from short-lived files that the app writes for them. All of these files are created with owner-only permissions and are cleaned up automatically:
144144
145145| Path (within the application-data directory) | Contents | Lifecycle |
146146| - | - | - |
147| `host-creds-<random-id>.json` | The resolved inference credential (plus the endpoint), as environment values for background Claude Code worker processes. The app writes it for credentials that it renews, such as a sign-in token or credential-helper output. Before Claude Desktop 4.29.0, the app also wrote it for a static API key or bearer token. Written atomically with owner-only permissions (mode `0600` on macOS; per-user ACLs on Windows). | Rewritten on each credential refresh; deleted when the app quits; leftovers from a crash are removed at the next launch. The random path segment is regenerated when you sign out of the inference provider or its credentials are rotated, so a process holding the old path loses access. |
148| `ccd-session-secrets/<session-id>/` | File-based credentials for Code sessions: Google Cloud application default credentials for Google Cloud's Agent Platform, or AWS configuration files for Amazon Bedrock. The directory is created with owner-only permissions (mode `0700` on macOS; per-user ACLs on Windows). | Created when the session starts; removed when the session ends; the whole directory is swept before the next Code session starts and when you sign out of the inference provider. |
149| Per-session working directory | For Cowork sessions, the same file-based credentials (Google Cloud's Agent Platform and Amazon Bedrock) are written into the session's working directory. | Scoped to the session; removed with the session directory. |
147| `ccd-session-secrets/<session-id>/` | The short-lived AWS credentials files of a session on Amazon Bedrock with [in-app AWS sign-in](https://claude.com/docs/third-party/claude-desktop/bedrock.md#in-app-aws-sign-in). A session on Google Cloud's Agent Platform writes no file here. The directory is created with owner-only permissions (mode `0700` on macOS; per-user ACLs on Windows). | Created when the session starts; removed when the session ends; the whole directory is swept at each launch and when you sign out of the inference provider. |
150148
151Aside from these files, credentials delivered through managed configuration are held in memory only.
152
153149### Unreadable saved API keys
154150
155151An encrypted API key can be decrypted only through the secure storage of the OS user account that saved it, so a copy of the `configLibrary/` files alone can't be decrypted elsewhere. Where that account's secure storage moves with the user, for example in a Windows roaming profile that carries the user's DPAPI keys, the key also decrypts on the other device.
from line 154
158154
159155Have the user enter the key again in the in-app configuration window, then restart the app, after any of these:
160156
161* **The data moves without its secure storage**: the application-data directory is copied or restored to another device or another OS user account
157* **The data moves without its secure storage**: the application-data directory is copied or restored to another device or another OS user account, for example by a setup script, disk image, or profile template
162158* **A Windows profile changes**: the profile is rebuilt, roams without the user's DPAPI keys, or belongs to a local account whose password an administrator reset
163159* **The macOS login keychain is reset**
160* **The Claude Safe Storage item is removed from the macOS keychain**
164161* **The desktop environment changes on Linux**: a key saved under GNOME Keyring can't be decrypted in a KDE session, or the reverse
165162* **The app is rolled back**: versions earlier than Claude Desktop 4.29.0 send the encrypted text as the key, and the provider refuses it
166163
from line 168
171168* **A macOS keychain that the app can't access as it launches**: this happens, for example, when the user dismisses the keychain prompt. Have the user restart the app, and enter their password or click **Allow** if macOS asks. If the banner stays, have the user enter the key again.
172169* **A key entered again while secure storage isn't available**: the app saves the key unencrypted and uses it after a restart. At the next launch where secure storage is available, the app encrypts the key, so a later launch without secure storage shows the banner again.
173170* **Devices with no secure storage that the app can use**, such as Linux without GNOME Keyring or KWallet: the key stays unencrypted, and the configuration window shows **This key is saved unencrypted on this computer.** under the key
174* **Tools that read or write the `configLibrary/` files**: a tool that reads the key gets the encrypted value. A tool that writes an unencrypted key still works, and the app encrypts that key at the next launch where secure storage is available.
171* **Tools that read or write the `configLibrary/` files**: a tool that reads the key gets the encrypted value. Don't write that value into another device's files, a managed profile, or a bootstrap response. A tool that writes an unencrypted key still works, and the app encrypts that key at the next launch where secure storage is available.
175172
173An API key that managed configuration delivers is never stored in the `configLibrary/` files or encrypted by the app, so it can't become unreadable this way. For users who don't have the key, deliver it through [managed configuration](https://claude.com/docs/third-party/claude-desktop/mdm.md), or send them an exported **JSON config** file to [import](https://claude.com/docs/third-party/claude-desktop/in-app-configuration.md#set-up-a-device-without-mdm). Where users type a key in, keep it somewhere they can get it again.
174
176175## Automatic deletion of idle sessions
177176
178177By default, chats, Cowork tasks, and Code sessions stay on the device until the user deletes them. To delete them after a period without activity, set [`chatSessionRetentionDays`](https://claude.com/docs/third-party/claude-desktop/configuration#chatsessionretentiondays), [`coworkSessionRetentionDays`](https://claude.com/docs/third-party/claude-desktop/configuration#coworksessionretentiondays), or [`codeSessionRetentionDays`](https://claude.com/docs/third-party/claude-desktop/configuration#codesessionretentiondays) to a number of days from 1 to 3650. Each key covers one kind of session, and a kind you leave unset is kept until the user deletes it. Idle time counts from the session's last activity, and pinned sessions are not exempt.
from line 339
3403393. Copy these to the same paths. On Windows, use a copy tool that supports paths longer than 260 characters.
341340 * The application-data directory, except these files in it, which the app creates again when it needs them:
342341
343 * `host-creds-*.json`
344342 * `ccd-session-secrets/`
345343 * `spaces-present/*/*/link-key`
346344 * `ccd-environment-config.json`
347345 * `cowork-enabled-cli-ops.json`
348346
349 Also leave out `plugin-mcp-auth/` and `connectors/*/plugin-mcp/`, which on Windows and Linux hold the user's sign-ins to plugin servers. The user signs in to those servers again on the new device.
347 Also leave out `plugin-mcp-auth/` and `connectors/*/plugin-mcp/`, which on Windows and Linux hold the user's sign-ins to plugin servers. The user signs in to those servers again on the new device. Leave out any `host-creds-*.json` file too, which an earlier version of Claude Desktop can leave behind.
350348
351349 If you copied any of these files or folders, quit Claude Desktop on the new device, then delete them.
352350 * The user's Cowork files folder: `~/Claude/`, or `~/Documents/Claude/` on legacy installs. If the user changed it, note the folder shown under **Cowork files** in **Settings > Cowork** on the old device before step 1, and copy that folder instead.
from line 361
363361
364362## Removing data
365363
366To fully reset a device's Claude Desktop on 3P state, delete the application-data directory above and the `~/Claude/` user-files folder. Code session transcripts are in Claude Code's store at `~/.claude/projects/`, which Claude Code in the terminal also uses, so delete them there separately if you need to remove them. For [SSH remote sessions](https://claude.com/docs/third-party/claude-desktop/ssh-remote-sessions.md#host-requirements), transcripts are in `~/.claude/projects/` and attached files in `~/.claude/uploads/` in the SSH user's home directory on the remote host. Claude Desktop also copies those transcripts to the device, into folders in `~/.claude/projects/` whose names start with `ssh-`, so delete them in both places.
364To fully reset a device's Claude Desktop on 3P state, delete the application-data directory above and the `~/Claude/` user-files folder. Code session transcripts are in Claude Code's store at `~/.claude/projects/`, which Claude Code in the terminal also uses, so delete them there separately if you need to remove them. For [SSH remote sessions](https://claude.com/docs/third-party/claude-desktop/ssh-remote-sessions.md#host-requirements), transcripts are in `~/.claude/projects/` and attached files in `~/.claude/uploads/` in the SSH user's home directory on the remote host. Claude Desktop also copies those transcripts to the device, into folders in `~/.claude/projects/` whose names start with `ssh-`, so delete them in both places. Sign-ins to plugin servers made in **Code** and [secret plugin settings](#credentials) entered there stay too, in [Claude Code's own credential store](https://code.claude.com/docs/en/authentication#credential-management), which Claude Code in the terminal also uses.
367365
368366On a device that also runs standard Claude Desktop, `~/Claude/` and `~/.claude/` hold that mode's files too, so deleting them deletes those as well. See [Data shared with standard Claude Desktop](#data-shared-with-standard-claude-desktop).
369367
third-party/claude-desktop/extensions Changed · +21 / -2 lines
from line 264
264264}
265265```
266266
267Each plugin marked this way still needs a `sha256` on its archive. Claude Desktop re-fetches the manifest periodically and picks up a newly published version without a configuration change or an app relaunch. A plugin the user removes stays removed.
267Each plugin marked this way still needs a `sha256` on its archive. Claude Desktop picks up a newly published version without a configuration change or an app relaunch, as described in [Roll out marketplace updates](#roll-out-marketplace-updates). A plugin the user removes stays removed.
268268
269269Claude Desktop honors these per-plugin marks only when the manifest is served from your inference gateway's or bootstrap server's own origin, because those hosts already carry your deployment's configuration and credentials. On any other origin the marks are ignored, and the marketplace behaves as `"available"`. Entry-level `"auto_install"` and `"required"` continue to require the [admin-side content pin](#marketplace-installation-preferences) on every origin.
270270
from line 283
283283
284284### Roll out marketplace updates
285285
286For a git marketplace, commit the change to the repository, update the `ref` in `allowedPluginMarketplaces` to the new commit SHA, and distribute the updated managed configuration. For a `url` marketplace with a `manifestSha256` pin, publish the new archive, update its `url` and `sha256` in `marketplace.json`, and update `manifestSha256` in configuration to the new file's digest. For a `url` marketplace using [per-plugin auto-install from a trusted origin](#per-plugin-auto-install-from-a-trusted-origin), publish the new `marketplace.json` and no configuration change is needed. Devices sync to the new revision on the next app launch or periodic re-fetch. To remove a marketplace, delete its entry; Claude Desktop unregisters it and uninstalls its plugins on the next sync.
286Publish a new version in the way that matches the marketplace's entry in `allowedPluginMarketplaces`:
287
288* **Git marketplace pinned to a commit**: commit the change to the repository, update `ref` to the new commit SHA, and distribute the updated managed configuration
289* **Git marketplace on a branch or tag**: push the change to the branch, or move the tag, with no configuration change
290* **`url` marketplace with a `manifestSha256` pin**: publish the new archive, update its `url` and `sha256` in `marketplace.json`, and update `manifestSha256` in configuration to the new file's digest
291* **`url` marketplace with no `manifestSha256` pin**: publish the new archive, then the new `marketplace.json`, with no configuration change. A marketplace that uses [per-plugin auto-install from a trusted origin](#per-plugin-auto-install-from-a-trusted-origin) is of this kind
292
293Devices sync to the new revision on the next app launch or periodic re-fetch, about every 10 minutes. A pinned marketplace syncs when the device receives the new pin.
294
295Claude Desktop also checks a `url` marketplace with no `manifestSha256` pin when a user opens a new Chat, Cowork, or Code session, returns to the app with that new session still open, or sends the session's first message:
296
297* **What users see**: a new skill in a plugin the user has installed, or in a plugin marked for automatic installation, shows when the user types `/` in the message box, and Claude can use it in that session
298* **What counts as a change**: Claude Desktop compares the bytes of `marketplace.json` with the copy it installed, so a new zip at the same URL goes unseen until that file changes. When you replace a zip, update its `sha256` in `marketplace.json`, or the plugin's `version` if the archive lists no `sha256`. Otherwise serve the same bytes, with no timestamp or other value that differs between requests
299* **What your server gets**: each device requests `marketplace.json`, at most once every 10 seconds per marketplace. After any change to the file, each device downloads every archive that it lists
300* **If the server is slow or an update fails**: a session waits up to 5 seconds for the marketplace's answer and up to 30 seconds in all, then starts with the copy it has. After a check that fails or gets no answer, or a new version that doesn't install, new sessions don't ask that marketplace again for five minutes
301* **With `userGit` or `credentialHelper`**: opening or returning to a new session checks at most once every five minutes, so a new skill can be missing from the `/` list until the user sends the first message
302
303Earlier versions of Claude Desktop sync only at launch and at the periodic re-fetch.
304
305To remove a marketplace, delete its entry; Claude Desktop unregisters it and uninstalls its plugins on the next sync.
287306
288307### Move a marketplace to a new source
289308
third-party/claude-desktop/feature-matrix Changed · +3 / -2 lines
from line 32
3232> * Projects
3333> * Artifacts
3434> * [Memory](https://claude.com/docs/third-party/claude-desktop/data-storage.md#memory)
35> * [Scheduled tasks](https://claude.com/docs/third-party/claude-desktop/configuration.md#scheduledtasksenabled)
35> * [Scheduled tasks](https://claude.com/docs/third-party/claude-desktop/scheduled-tasks.md)
3636> * [Code execution for analysis](https://claude.com/docs/third-party/claude-desktop/chat.md#advanced-file-analysis)
3737> * [File access, upload, and export](https://claude.com/docs/third-party/claude-desktop/local-access.md)
3838> * Global languages
from line 65
6565> * [Skills, hooks, and plugins distribution](https://claude.com/docs/third-party/claude-desktop/extensions.md#organization-plugins-admin)
6666> * [Skill scanning](https://claude.com/docs/third-party/claude-desktop/extensions.md#skill-scanning)
6767> * [Status line](https://claude.com/docs/third-party/claude-desktop/status-line.md)
68> * [Organization announcement](https://claude.com/docs/third-party/claude-desktop/configuration.md#organizationannouncement)
6869> * [MCP server allowlist](https://claude.com/docs/third-party/claude-desktop/extensions.md#controlling-user-extensions)
6970> * [Feature toggles](https://claude.com/docs/third-party/claude-desktop/configuration.md#capabilities)
7071> * [Auto-updates](https://claude.com/docs/third-party/claude-desktop/installation.md#updates)
from line 85
8485>
8586> | Topic | What to know |
8687> | - | - |
87> | Sessions and scheduled tasks | Sessions are local, except [Code sessions over SSH](https://claude.com/docs/third-party/claude-desktop/ssh-remote-sessions.md), and the device must be awake to run long processes and scheduled tasks. |
88> | Sessions and scheduled tasks | Sessions are local, except [Code sessions over SSH](https://claude.com/docs/third-party/claude-desktop/ssh-remote-sessions.md), and the device must be awake to run long processes and scheduled tasks. If a [scheduled task](https://claude.com/docs/third-party/claude-desktop/scheduled-tasks.md) is missed because the device is asleep, it runs when the device wakes up. |
8889> | Memory | [Memory](https://claude.com/docs/third-party/claude-desktop/data-storage.md#memory) in Claude Desktop on 3P is stored on the device, not on Anthropic infrastructure. Chat-history search and nightly summary generation are not available in Chat on 3P. |
8990> | Web search | Amazon Bedrock deployments and gateways that do not forward Anthropic server tools need a [web search provider](https://claude.com/docs/third-party/claude-desktop/web-tools.md#web-search-options) configured first. |
9091> | Claude in Chrome | Claude in Chrome works with Claude Desktop on 3P only in organizations managed from the [Enterprise Admin Console](https://claude.com/docs/third-party/claude-desktop/admin-console.md). |
third-party/claude-desktop/in-app-configuration Changed · +9 / -1 lines
### Set up a device without MDM
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), 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 |
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 file that a user loads with **Import configuration…** on 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.
3737
3838When a managed profile is already present on the device, the window opens in read-only mode and shows the deployed values. Its **Export** menu offers **JSON config (redacted)**, 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). This option requires Claude Desktop 4.23118.0 or later. Author new configurations from a device without a managed profile.
39
40### Set up a device without MDM
41
42Export **JSON config** and send the file to the user. In the [configuration window](#open-the-configuration-window) on their device, the user opens the configuration picker at the top right, chooses **Import configuration…**, selects the file, clicks **Apply Changes**, and then clicks **Relaunch now**. The exported file holds your API key in plain text, so handle it as you handle the key.
43
44> [!WARNING]
45>
46> Don't set up another device or user account by copying files from the `configLibrary/` directory, for example in a setup script, a disk image, or a profile template. Where the app can use the device's secure storage, the API key in those files is encrypted for the OS user account that saved it. On another device or account, the app then shows the banner **Claude can’t read your saved key** and starts no sessions until the user enters the key and restarts the app. Before Claude Desktop 4.4212.0, the files held the key unencrypted. See [Unreadable saved API keys](https://claude.com/docs/third-party/claude-desktop/data-storage.md#unreadable-saved-api-keys).
3947
third-party/claude-desktop/installation Changed · +10 / -5 lines
### Claude keeps crashing after a new version is installed
from line 177
177177
178178To apply a Group Policy change on a device, run `gpupdate /force` in a Command Prompt or restart the device. When the changed policy has reached the device, run the [readiness check](#check-device-readiness) again and confirm that the **VM service logon right** line reads "SeServiceLogonRight granted". Then have the user restart Claude Desktop and start a Cowork task. If the banner still appears, generate the diagnostic report described under [Troubleshooting](#troubleshooting) and send it to your Anthropic representative.
179179
180### Claude keeps crashing after a new version is installed
181
182On macOS, Claude Desktop can show **Claude keeps crashing** after a new version is installed while the app is open. Have the user click **Restart Claude**, not **Reload**, and the app reopens on the new version. Try the reinstall or the **Disable Hardware Acceleration** step that the screen suggests only if the screen comes back after the restart. To avoid the screen, see [Restart open apps after you install a new version](#restart-open-apps-after-you-install-a-new-version).
183
180184## Endpoint security software
181185
182186Claude Desktop runs Chat conversations, Cowork tasks, and Code sessions through an agent helper, a signed binary that it keeps under its user-data directory (or, with the Windows [offline installer](#offline-installation), inside the installed app package) and launches when a user works in Chat, Cowork, or Code. If your organization runs binary-authorization or EDR software (such as [Santa](https://santa.dev), CrowdStrike Falcon, or Microsoft Defender ASR) with path-based deny rules, the agent helper may be blocked from launching. The symptom is that Claude Desktop opens normally and reads the managed configuration, but Chat conversations, Cowork tasks, and Code sessions fail to start.
from line 372
368372
369373### Restart open apps after you install a new version
370374
371When you set [`disableAutoUpdates`](https://claude.com/docs/third-party/claude-desktop/configuration#disableautoupdates) and install new versions with your own tools, an install can land while Claude Desktop is open. The open app finds the newer version on the device and shows **Relaunch to update** in the sidebar. Clicking **Relaunch to update** moves the person to the newer version.
375When you install new versions with your own tools, an install can land while Claude Desktop is open. If you set [`disableAutoUpdates`](https://claude.com/docs/third-party/claude-desktop/configuration#disableautoupdates), the open app finds the newer version on the device and shows **Relaunch to update** in the sidebar. Clicking **Relaunch to update** moves the person to the newer version.
372376
373On Windows, the app shows **Relaunch to update** for installs from the `.msix` package. Clicking it closes Claude Desktop, and Windows may then open the newer version. If Claude Desktop stays closed, open it again to get the newer version. Quitting and reopening Claude Desktop without the click can start the earlier version again, while signing out of Windows and back in moves the person to the newer version.
377* **macOS**: install while Claude Desktop isn't running. Otherwise have people quit and reopen Claude Desktop, or click **Relaunch to update** where it shows, soon after the install. Until they do, new windows and some features may fail even while the open window still works.
378* **Windows**: with `disableAutoUpdates` set, the app shows **Relaunch to update** for installs from the `.msix` package. Clicking it closes Claude Desktop, and Windows may then open the newer version. If Claude Desktop stays closed, open it again to get the newer version. Quitting and reopening Claude Desktop without the click can start the earlier version again, while signing out of Windows and back in moves the person to the newer version.
374379
375You can also have Claude Desktop restart itself when nobody clicks. Two keys control the restart:
380With `disableAutoUpdates` set, you can also have Claude Desktop restart itself when nobody clicks. Two keys control the restart:
376381
377382* [`installedUpdateEnforcementEnabled`](https://claude.com/docs/third-party/claude-desktop/configuration#installedupdateenforcementenabled): set it to `true` to turn on the restart, which is off by default
378383* [`installedUpdateEnforcementHours`](https://claude.com/docs/third-party/claude-desktop/configuration#installedupdateenforcementhours): how long the app waits after it finds the newer version. With a number from 1 to 72, the app restarts when those hours end, even while someone is using the computer. With the key unset, the app waits 72 hours and then until the computer has been idle for 10 minutes.
third-party/claude-desktop/mdm Changed · +6 / -4 lines
from line 39
3939| **Connectors** | Managed MCP servers pushed to all users Whether users can add their own local MCP servers Whether desktop extensions (`.mcpb`) are allowed Whether unsigned extensions are rejected |
4040| **Telemetry & updates** | Organization UUID OpenTelemetry collector endpoint Whether auto-updates are blocked The enforcement window for downloaded updates, or the restart for versions you install yourself The three Anthropic-bound telemetry toggles (essential, nonessential, nonessential services) |
4141| **Limits** | Per-device token cap and its window length Retention periods after which idle chats, Cowork tasks, and Code sessions are deleted |
42| **Appearance** | Persistent banner shown across the app window Deployment display name and subtitle Whether the signed-in user's identity is shown and exported (end-user attribution) Whether feature announcements are shown |
42| **Appearance** | Persistent banner shown across the app window Announcement from your organization that each user can close Deployment display name and subtitle Whether the signed-in user's identity is shown and exported (end-user attribution) Whether feature announcements are shown |
4343| **Plugins** | [Plugin marketplaces](https://claude.com/docs/third-party/claude-desktop/extensions.md#plugin-marketplaces-admin), added by GitHub repo, git URL, or hosted `marketplace.json` URL Shows the org-plugins folder path for your platform; plugin bundles are mounted to that folder via your MDM, not through this window |
4444| **Egress** | A read-only firewall allowlist derived from everything you've entered above, grouped by feature **Copy hostnames**, **Download .txt**, and **Test connectivity** actions |
4545| **Source** | The bootstrap keys, if you are using the [bootstrap server](https://claude.com/docs/third-party/claude-desktop/bootstrap.md) delivery model instead of a full MDM profile |
from line 75
7575* **New configuration** creates an empty configuration.
7676* **Duplicate** copies the current configuration as a starting point for a variant.
7777* **Rename** and **Delete** manage the list.
78* **Reveal in Finder** opens the on-disk location where saved configurations are stored.
78* **Reveal in Finder** (**Show in Explorer** on Windows, **Show in file manager** on Linux) opens the folder where saved configurations are stored. Don't set up another device or user account from a copy of these files (see [Unreadable saved API keys](https://claude.com/docs/third-party/claude-desktop/data-storage.md#unreadable-saved-api-keys)). To use a configuration on another device, click **Export**.
7979
8080Selecting a configuration in the picker loads it for editing; the **applied** badge marks the one currently active on your machine. **Apply Changes** and **Export** each act on whichever configuration is selected, so you can test each one locally and export them independently.
8181
from line 129
129129> >
130130> > In releases before v1.19367.0, the app read both hives and merged them key by key, with the `HKLM` value winning where a key appeared in both. Fleets that split keys across both hives must consolidate the full configuration into one hive before updating to v1.19367.0 or later.
131131
132When 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.
132When a managed source sets any key other than `organizationAnnouncement` and 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.
133133
134134### Restrict a device to one deployment mode
135135
from line 159
159159
160160When a managed source sets only keys from this group (any of them), the device keeps its locally authored configuration and the configuration window stays editable. The group is still enforced as a unit: every key in it is resolved from the managed source alone, so a locally set or bootstrap-served value for any of them is ignored even if the profile sets only one. A profile that sets the update keys but not `relaunchEnforcementHours` or `configRecheckIntervalMinutes` therefore runs their defaults (24 hours and 10 minutes) on those devices, so set them in the same profile when you want other values.
161161
162If the managed profile sets any other recognized key, the normal rule above applies and the whole configuration is managed. For a profile that also sets `bootstrapUrl`, see [Which configuration source applies on a device](https://claude.com/docs/third-party/claude-desktop/configuration-format.md#which-configuration-source-applies-on-a-device).
162A profile of only these keys leaves what the device connects to in the local configuration, which a user can edit. If that connection runs every session on a server and none on the device, that server answers the device's update checks, so the app installs only the updates that the server offers. Update, restart, and re-check timing then comes from that server or takes its default, and most of these keys stop applying, though `disableAutoUpdates` and the network proxy keys still apply. To prevent this, set the connection in the profile, or set [`deploymentMode`](#restrict-a-device-to-one-deployment-mode) to `1p` on a device that only signs in to claude.ai.
163
164If the managed profile sets any other recognized key except [`organizationAnnouncement`](https://claude.com/docs/third-party/claude-desktop/configuration#organizationannouncement), the normal rule above applies and the whole configuration is managed. For a profile that also sets `bootstrapUrl`, see [Which configuration source applies on a device](https://claude.com/docs/third-party/claude-desktop/configuration-format.md#which-configuration-source-applies-on-a-device).
163165
164166## 5. Distribute the app
165167
third-party/claude-desktop/scheduled-tasks New page · 52 lines, new page
# Scheduled tasks in Claude Desktop on 3P ## What a scheduled task needs to run ### Keep the device awake and the app open ## Approvals that last across runs ## Where users see what ran ## Configuration keys for scheduled tasks
A whole new page. There's nothing to diff it against, so here is what it says.
# Scheduled tasks in Claude Desktop on 3P > What scheduled tasks in Claude Desktop on 3P need in order to run, what users are told when a run is late or fails, and the keys that control them A scheduled task is a prompt that a user saves with a schedule, such as every weekday at 8:00 AM, on the **Scheduled** page in Cowork or the **Routines** page in Code. Claude Desktop on third-party (3P) runs the prompt in a new session at each scheduled time, even when the user is away. Scheduled tasks run locally, in Claude Desktop on the user's device, which must be awake with the app open. ## What a scheduled task needs to run A run needs each of the following: * **The device is awake and Claude Desktop is open**: a task that misses its time runs once after the device wakes or the app opens. If it missed several times, it runs for the latest one only, and the task's **History** shows the earlier ones as one **Skipped** entry. A recurring task's missed time more than seven days old doesn't run and isn't listed. * **The device can reach your inference provider**: while the device has no network connection, the run waits. If your provider or gateway doesn't answer, or returns a server error such as 500, 503, or 529, before Claude starts to respond, Claude Desktop starts the run again up to eight times over three to four hours, stopping at the task's next scheduled time. The user is notified of the first failure and of the final outcome. Claude Desktop doesn't retry a 401, 403, or 429 response, or a failure after Claude starts to respond. * **The user is signed in**: where users sign in to your gateway, inference provider, or bootstrap server, runs wait while the sign-in has expired. Claude Desktop notifies the user to sign in again, and the runs start after that. * **The task's connectors are signed in**: otherwise the run continues without the connector, and its notification reads **Reconnect** or **Couldn’t use**, followed by the connector's name * **Each step that asks for approval gets an answer**: otherwise the run waits at the prompt, and the user is notified. In Cowork, an unanswered prompt delays the task's next scheduled run by up to two hours. When a new run starts, Claude Desktop declines the prompt, and the earlier run goes on without that step and reports **Scheduled task skipped a step**. In Code, Claude Desktop denies a prompt that goes unanswered for about 48 minutes, and the run stops. ### Keep the device awake and the app open The user goes to **Settings > This computer > System** and turns on two toggles: * **Keep computer awake**: while Claude Desktop is open, the device doesn't go to sleep when idle. Closing a laptop's lid still puts it to sleep. * **Run on startup**: Claude Desktop opens when the user logs in to the device ## Approvals that last across runs Each run is a new session, so an approval for that run alone ends with it. For a task to finish unattended, the user answers each prompt once with the option that lasts: * **Connector tools**: the user chooses **Allow for all scheduled runs** in Cowork or **Always allow** in Code, or **Allow for 7 days**, for example, under your [time limit](https://claude.com/docs/third-party/claude-desktop/configuration.md#tool-approvals-on-scheduled-tasks). A tool that your [`toolPolicy`](https://claude.com/docs/third-party/claude-desktop/configuration#tool-permissions-for-managed-mcp-servers) sets to `"ask"` has no such option, so each run in which Claude calls the tool waits for the user. * **Built-in tools**: a lasting approval can also cover a shell command, a file path, or a website. It has no time limit. * **File deletion in Cowork**: the prompt that asks before Claude deletes files in a folder offers **Allow for 30 days**, or for the number of days in your time limit. The approval covers that folder and its subfolders until the date shown. It's offered only for a folder chosen on the task itself, and not when the task's permission mode is [**Automatically approve**](https://claude.com/docs/third-party/claude-desktop/configuration.md#automodeenabled). The task's page lists these approvals under **Always allowed**, where the user can remove them. ## Where users see what ran Users can see how each task's latest run went without opening the run: * **Sidebar**: each Cowork task that is turned on has its own row, marked when its latest run failed, is waiting for the user, is unread, or is running * **Scheduled and Routines pages, and each task's page**: the status of the latest run, such as **Last run failed, will try again**, **Needs input**, **Waiting for you to sign in**, or **Didn’t run** * **Notifications**: unless the user has turned them off, Claude Desktop sends a desktop notification when a run finishes, fails, waits for the user, or can't start For a support request, the [diagnostic report](https://claude.com/docs/third-party/claude-desktop/installation.md#troubleshooting) has a **Scheduled tasks** section. ## Configuration keys for scheduled tasks These keys control scheduled tasks for your organization: * [`scheduledTasksEnabled`](https://claude.com/docs/third-party/claude-desktop/configuration#scheduledtasksenabled): turns scheduled tasks on or off in Cowork and Code * [`keepAwakeEnabled`](https://claude.com/docs/third-party/claude-desktop/configuration#keepawakeenabled): allows keep-awake, or blocks it and hides its toggles * [`mcpScheduledTaskApprovalLifetimeDays`](https://claude.com/docs/third-party/claude-desktop/configuration#mcpscheduledtaskapprovallifetimedays): sets how many days a task's approvals of connector tools and file deletion hold, and `0` turns those off. While it's unset, [`mcpPersistentAlwaysAllowEnabled`](https://claude.com/docs/third-party/claude-desktop/configuration#mcppersistentalwaysallowenabled) decides whether prompts offer them. [Some approvals aren't covered](https://claude.com/docs/third-party/claude-desktop/configuration.md#tool-approvals-on-scheduled-tasks).
third-party/claude-desktop/status-line Changed · +36 / -7 lines
### Session cost in the status line input
from line 13
1313> These cases are covered on other pages:
1414>
1515> * **A notice across the top of the app window, with no program to install**: set the [`banner`](https://claude.com/docs/third-party/claude-desktop/configuration#banner) key
16> * **A message that each user can close, on the start screen or in a dialog**: set the [`organizationAnnouncement`](https://claude.com/docs/third-party/claude-desktop/configuration#organizationannouncement) key
1617> * **Your own message when your gateway blocks a user at a spend limit**: see [Block requests at a spend limit](https://claude.com/docs/third-party/claude-desktop/gateway.md#block-requests-at-a-spend-limit)
1718
1819## Turn on the status line
from line 24
2324
2425Put the program where users can't change it. Claude Desktop runs it only from a location that meets these rules:
2526
26* **macOS and Linux**: root owns the file and every parent folder, with no write access for group or others
27* **macOS and Linux**: root owns the file and every parent folder, with no write access for group or others, and the path isn't under `/home`, `/net`, or `/Volumes`
2728* **Windows**: the file is under `Program Files` or `Program Files (x86)` on the drive where Windows is installed
2829
2930To try the [macOS and Linux sample](#sample-status-line-programs) on a test device, save it as `status-line` and run these commands in your terminal:
from line 80
7980
8081Claude Desktop starts the status line program with no arguments and no window, as the user who runs Claude Desktop.
8182
82* **File type**: on macOS and Linux, an executable file, such as a compiled program or a script that starts with `#!`. On Windows, an `.exe` file or a `.ps1`, `.cmd`, or `.bat` script.
83* **File type**: on macOS and Linux, an executable file, such as a compiled program or a script that starts with `#!`. Claude Desktop doesn't check the interpreter that a `#!` line names, so install it where users can't change it too. Python also runs code from the user's folders unless you start it with `-I`, for example `#!/usr/bin/python3 -I`. On Windows, an `.exe` file or a `.ps1`, `.cmd`, or `.bat` script.
8384
84* **Input**: one line of JSON on standard input, with the session ID and the model. A field with no value is left out, so handle a missing `model`.
85* **Input**: one line of JSON on standard input, with the session ID, the model, and the [session cost](#session-cost-in-the-status-line-input). A field with no value is left out, so handle a missing `model` or `cost`. Later versions can add fields, so ignore any that the program doesn't use. Don't build a file path from these values.
8586
8687 ```json theme={null}
87 {"session_id":"local_1f0c2a9e-7b3d-4c58-9a16-5e2d8b40c7f3","model":{"id":"claude-sonnet-4-5","display_name":"Claude Sonnet 4.5"}}
88 {"session_id":"local_1f0c2a9e-7b3d-4c58-9a16-5e2d8b40c7f3","model":{"id":"claude-sonnet-4-5","display_name":"Claude Sonnet 4.5"},"cost":{"total_cost_usd":1.24}}
8889 ```
8990
9091* **Output**: the first non-empty line of standard output, read as UTF-8, up to 200 characters. Markup and links show as plain text. A line wider than the message box ends in "…" and shows in full on hover.
from line 98
9798
9899* **Time limit**: 10 seconds, after which Claude Desktop stops the program and anything it started.
99100
101### Session cost in the status line input
102
103`cost.total_cost_usd` is the session's estimated cost so far. Claude Desktop sends it only while [`inferenceModelPricingEnabled`](https://claude.com/docs/third-party/claude-desktop/configuration#inferencemodelpricingenabled) is on and the session has an estimate. The value is a number in US dollars with up to six decimal places and no exponent. It's for display only and can differ from your provider's bill.
104
105* **Source**: Claude Desktop's own sum for the session, added up on the user's device. It covers Cowork, Chat, and Code sessions, including [Code sessions over SSH](https://claude.com/docs/third-party/claude-desktop/ssh-remote-sessions.md). With no status line set, the built-in "Session cost (estimate)" line above the message box shows the same sum.
106* **Models with no price**: a model ID that can't be matched to a Claude model, such as an opaque gateway alias, adds nothing. After you give that ID a rate in [`inferenceModelPricing`](https://claude.com/docs/third-party/claude-desktop/configuration#inferencemodelpricing), only its later usage counts. The input doesn't show that the sum is partial.
107* **Missing `cost`**: don't show \$0. Check for each of these causes:
108 * `inferenceModelPricingEnabled` is off
109 * The session has no priced estimate yet, such as before Claude Desktop records its first turn's cost or when it has used only models with no price
110 * Claude Desktop [couldn't read its usage ledger](#troubleshoot-a-missing-status-line), the local record of these estimates
111* **Scripts written for Claude Code**: [Claude Code's status line](https://code.claude.com/docs/en/statusline) always sends `cost`, among many other fields. Claude Desktop sends only the fields in the [sample input](#write-the-status-line-program), so check a script that you carry over for other fields and for a fallback to 0. Claude Desktop's sum can also differ from Claude Code's total, for example after `/clear`.
112
113This macOS and Linux script prints the cost. While `cost` is missing it prints nothing, so no line shows:
114
115```sh theme={null}
116#!/bin/sh
117# Prints, for example: Session cost (estimate): $1.24
118LC_ALL=C
119export LC_ALL
120cost=$(sed -n 's/.*"total_cost_usd":\([0-9.]*\).*/\1/p')
121[ -n "$cost" ] || exit 0
122printf 'Session cost (estimate): $%.2f\n' "$cost"
123```
124
100125### Status line scripts on Windows
101126
102127A `.ps1` script runs in Windows PowerShell, not PowerShell 7.
from line 189
164189
165190* A session opens
166191* Claude finishes a turn
192* A turn's result arrives
167193* The user picks another model
168194* The app regains focus
169195
170196There's no timer, so new data shows the next time one of these happens.
171197
198A turn's result closes the turn, and Claude Desktop doesn't add the turn to the [session cost](#session-cost-in-the-status-line-input) until the result arrives. That can be seconds after Claude's answer ends, for example when a [Stop hook](https://code.claude.com/docs/en/hooks#stop) runs first. The program can then run twice for the turn, and the first run's `cost` may not include the turn yet.
199
172200If the program exits with a code other than 0, prints nothing, or takes longer than 10 seconds, the line disappears and the user sees no error. The next successful run brings the line back.
173201
174202## Troubleshoot a missing status line
from line 209
181209 * **macOS and Linux**: code 127 means that a command the script runs wasn't found, so call each tool by its full path
182210 * **Windows**: a `.ps1` script that an [execution policy](#status-line-scripts-on-windows) blocks ends with code 1
183211* **`was stopped after 10 seconds`**: the program hit the [time limit](#write-the-status-line-program). On Windows, a `.ps1` script can be slow to start for a few minutes after a user first opens Claude Desktop, and a `.cmd` or `.exe` file starts faster. If the line appears after a later turn ends or the app regains focus, nothing needs fixing.
212* **`runs without the session's cost`**: Claude Desktop couldn't read its usage ledger, the local record of cost estimates, so the program ran with no `cost` in its input. The entry gives the cause. If `cost` comes back after a later turn ends or the app regains focus, nothing needs fixing.
184213* **No entry**: the program printed nothing, which isn't logged, or the key hasn't reached the app. Restart Claude Desktop and check [which configuration source applies](https://claude.com/docs/third-party/claude-desktop/configuration-format.md#which-configuration-source-applies-on-a-device).
185214
186215To see the program's own error messages, run it in a new terminal window with Claude Desktop's working directory and `PATH`:
from line 218
189218>
190219> ```bash theme={null}
191220> cd /
192> echo '{"session_id":"test"}' | env -i HOME="$HOME" PATH=/usr/bin:/bin:/usr/sbin:/sbin /opt/example/bin/status-line
221> echo '{"session_id":"test","cost":{"total_cost_usd":1.24}}' | env -i HOME="$HOME" PATH=/usr/bin:/bin:/usr/sbin:/sbin /opt/example/bin/status-line
193222> echo "exit code: $?"
194223> ```
195224
from line 230
201230> Set-Location "$env:SystemRoot\System32"
202231> $env:PATH = "$env:SystemRoot\System32;$env:SystemRoot;$env:SystemRoot\System32\WindowsPowerShell\v1.0"
203232> $env:PSModulePath = "$env:SystemRoot\System32\WindowsPowerShell\v1.0\Modules;$env:SystemRoot\System32\WindowsPowerShell\v1.0\Modules"
204> '{"session_id":"test"}' | powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -File "C:\Program Files\Example\status-line.ps1"
233> '{"session_id":"test","cost":{"total_cost_usd":1.24}}' | powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -File "C:\Program Files\Example\status-line.ps1"
205234> "exit code: $LASTEXITCODE"
206235> ```
207236
third-party/claude-desktop/vertex Changed · +7 / -9 lines
from line 22
2222
2323## How the two sign-in flows compare
2424
25The [in-app Google sign-in](#in-app-google-sign-in) and [in-app Workforce Identity sign-in](#in-app-workforce-identity-sign-in) approaches both open the system browser for a one-time consent and then renew in the background (or, for Workforce Identity, re-prompt in the browser when your IdP does not issue a refresh token). They differ in which party issues the refresh token, whether Google's Security Token Service is involved, and whether an Application Default Credentials file is written. The diagrams below show each flow end to end, and the table that follows summarizes the differences.
25The [in-app Google sign-in](#in-app-google-sign-in) and [in-app Workforce Identity sign-in](#in-app-workforce-identity-sign-in) approaches both open the system browser for a one-time consent and then renew in the background (or, for Workforce Identity, re-prompt in the browser when your IdP does not issue a refresh token). They differ in which party issues the refresh token and whether Google's Security Token Service is involved. The diagrams below show each flow end to end, and the table that follows summarizes the differences.
2626
2727### Workforce Identity sign-in
2828
from line 69
6969
7070### Google sign-in (OAuth)
7171
72Claude Desktop runs authorization code with PKCE against **Google's** OAuth endpoints. Google issues the refresh token, and the app writes it to an `authorized_user` Application Default Credentials file that the Google Cloud client library consumes. Your corporate IdP may appear inside Google's sign-in page (if Cloud Identity is federated via SAML), but the app never talks to it directly.
72Claude Desktop runs authorization code with PKCE against **Google's** OAuth endpoints. Google issues the refresh token, and only the app holds it. The app exchanges it at Google for short-lived access tokens and gives each session an access token. Your corporate IdP may appear inside Google's sign-in page (if Cloud Identity is federated via SAML), but the app never talks to it directly.
7373
7474```mermaid theme={null}
7575sequenceDiagram
from line 96
9696 end
9797 App->>App: Store authorized_user ADC<br/>{client_id, client_secret, refresh_token}<br/>encrypted with the operating system's secure storage<br/>(Keychain on macOS, DPAPI on Windows)
9898
99 Note over App,Vertex: At each session start
99 Note over App,Vertex: When a session starts and the app holds no fresh access token
100100
101 App->>App: Write the ADC JSON to a per-session file,<br/>set GOOGLE_APPLICATION_CREDENTIALS
102 App->>Goog: google-auth-library reads ADC and<br/>POSTs oauth2.googleapis.com/token (grant_type=refresh_token)
101 App->>Goog: POST oauth2.googleapis.com/token<br/>(grant_type=refresh_token)
103102 Goog-->>App: Fresh access_token
104103 App->>Vertex: Vertex AI request (Authorization: Bearer access_token)
105104 Vertex-->>App: Model response
106105
107 Note over App,Vertex: Silent renewal: google-auth-library refreshes against Google using the ADC file.<br/>Your corporate IdP is not contacted on renewal.
106 Note over App,Vertex: No ADC file is written. Silent renewal: the app repeats the exchange before the access token expires.<br/>Your corporate IdP is not contacted on renewal.
108107```
109108
110109### Side by side
from line 114
115114| Where your corporate IdP appears | Directly (the app opens it) | Inside Google's sign-in page, via Cloud Identity SAML federation (optional) |
116115| Refresh token issued by | Your IdP (when the Refresh Token grant is enabled on the client) | Google |
117116| Google STS (`sts.googleapis.com`) involved | Yes, on every access-token renewal | No |
118| ADC file written | No | Yes (`authorized_user` JSON, pointed to by `GOOGLE_APPLICATION_CREDENTIALS`) |
119117| Registered on the Google side | Workforce pool and OIDC provider (IAM & Admin) | Desktop-app OAuth 2.0 client (APIs & Services → Credentials) |
120118| Per-user prerequisite | An account at your IdP | A Google Workspace or Cloud Identity account |
121119| Client registered at your IdP | Public (native) OAuth client, PKCE required, loopback redirect URI | None (your IdP is federated to Cloud Identity, not to the app) |
from line 168
170168
171169When `inferenceVertexOAuthClientId` and `inferenceVertexOAuthClientSecret` are both set, the app shows a **Sign in with Google Cloud** page at first launch. Clicking the button opens the system browser for a standard Google consent flow, and the app listens on a loopback address for the redirect. On success, the app stores the user's Google refresh token encrypted with the operating system's secure storage (Keychain on macOS, DPAPI on Windows) and returns to Cowork.
172170
173At the start of each Cowork session, the app writes an `authorized_user` Application Default Credentials file (the same format produced by `gcloud auth application-default login`) and points `GOOGLE_APPLICATION_CREDENTIALS` at it. The Google Cloud client library handles access-token minting and refresh automatically.
171The refresh token stays in the app. For each session, the app exchanges it at Google for a short-lived access token, gives the session that token, and renews it in the background. The app writes no credentials file and doesn't set `GOOGLE_APPLICATION_CREDENTIALS`. Hooks and MCP servers that run on the device, and commands in Code sessions, use the user's own `gcloud` credentials, if there are any, and not this sign-in. Before Claude Desktop 5.1231.0, the app wrote the refresh token to a `.gcp-credentials.json` file in each session's folder, and from that version on it deletes those files at launch.
174172
175173If the stored refresh token is revoked or expires, the app shows a **Sign in again** prompt; clicking it reopens the Google consent flow in the browser. If you deploy a new OAuth client ID, the app clears the stored token and shows the sign-in page on next launch.
176174
third-party/claude-desktop/code Changed · +1 / -1 lines
from line 101
101101* **On a macOS or Linux host over SSH**, from any device, Windows included: in the host's Claude Code `managed-settings.json` file or `managed-settings.d` folder, not in a configuration profile
102102* **On a Windows device itself, in WSL, and on a Windows host over SSH**: sessions start without a launcher
103103
104Code sessions still use the provider and endpoint in Claude Desktop's configuration, but Claude Desktop passes no inference credential and no [`inferenceCustomHeaders`](https://claude.com/docs/third-party/claude-desktop/configuration#inferencecustomheaders) to Claude Code when the launcher starts it. The launcher must set a credential in Claude Code's environment, such as `ANTHROPIC_AUTH_TOKEN` for a gateway or the variable that your provider's credential uses. With no credential, the session still starts, and each reply fails with a message that Claude Code has no working credentials. Cowork, the connection test, and session titles don't go through the launcher. They use the credential in Claude Desktop's configuration, so a passing connection test doesn't show that the launcher supplies one.
104Code sessions still use the provider and endpoint in Claude Desktop's configuration, but Claude Desktop passes no inference credential and no [`inferenceCustomHeaders`](https://claude.com/docs/third-party/claude-desktop/configuration#inferencecustomheaders) to Claude Code when the launcher starts it. The launcher must set a credential in Claude Code's environment, such as `ANTHROPIC_AUTH_TOKEN` for a gateway or the variable that your provider's credential uses. It must also pass on the `ANTHROPIC_BASE_URL` that it receives, or set your gateway's address in its place. With no credential, the session still starts, and each reply fails with a message that Claude Code has no working credentials. Cowork, the connection test, and session titles don't go through the launcher. They use the credential in Claude Desktop's configuration, so a passing connection test doesn't show that the launcher supplies one.
105105
106106A session doesn't start if Claude Desktop can't use the launcher you named: for example, if the file is missing or isn't executable, or the value doesn't follow Claude Code's [launcher value format](https://code.claude.com/docs/en/corporate-launcher#format-of-the-launcher-value).
107107
third-party/claude-desktop/configuration-format Changed · +1 / -1 lines
from line 38
3838| Windows | `HKLM\SOFTWARE\Policies\Claude` (machine), `HKCU\SOFTWARE\Policies\Claude` (user) | `%LOCALAPPDATA%\Claude-3p\configLibrary\` |
3939| Linux | `/etc/claude-desktop/managed-settings.json` | `~/.config/Claude-3p/configLibrary/` |
4040
41The local location is a directory: `_meta.json` records which saved configuration is applied, and each configuration is a `<id>.json` file alongside it. The in-app configuration window writes here.
41The local location is a directory: `_meta.json` records which saved configuration is applied, and each configuration is a `<id>.json` file alongside it. The in-app configuration window writes here. Where the app can use the device's secure storage, API keys in these files are encrypted for the OS user account that saved them (see [Unreadable saved API keys](https://claude.com/docs/third-party/claude-desktop/data-storage.md#unreadable-saved-api-keys)). The app doesn't read an exported **JSON config** file from this directory. Load that file with **Import configuration…** in the configuration window.
4242
4343### Which configuration source applies on a device
4444
third-party/claude-desktop/gateway Changed · +3 / -1 lines
from line 575
575575
576576In [**Auto mode**](https://claude.com/docs/third-party/claude-desktop/configuration.md#automodeenabled), which Cowork shows as **Automatically approve**, a safety classifier reviews Claude's actions and blocks the ones it judges risky. On a gateway deployment, these can do the review:
577577
578* **Claude Code's built-in safety check (the default)**: it sends its own requests through your gateway, and you pay for them like the rest of your usage.
578* **Claude Code's built-in safety check (the default)**: it sends its own requests through your gateway, and you pay for them like the rest of your usage. In Cowork, shell commands wait for this check too, which usually adds one request for each command. If every such request fails, each command is refused with no prompt, and the task shows the command as failed. For what your gateway must accept, and for when shell commands aren't checked, see [`autoModeEnabled`](https://claude.com/docs/third-party/claude-desktop/configuration#automodeenabled).
579579* **The model provider behind your gateway**: the session asks for the review in its normal request, and the provider returns its verdict with the response. The session sends no separate request for an action that gets a verdict.
580580
581581> [!NOTE]
from line 745
745745
746746* Set `inferenceGatewayAutoModeServerChecks` to `false`, as described in [Turn off server-side Auto mode checks](#turn-off-server-side-auto-mode-checks). The change takes effect once each user [relaunches Claude Desktop](https://claude.com/docs/third-party/claude-desktop/configuration-format.md#when-a-configuration-change-on-a-device-takes-effect).
747747* Have users start new sessions in **Manual** mode, which Cowork shows as **Manually approve**. If turns fail in those sessions too, the review isn't the cause.
748
749**`Automatically approve isn’t available for this task. Switched to Manually approve.` or `Couldn’t switch to Automatically approve.`** Claude Code can't run Auto mode for the Cowork task, for example because the task's model [doesn't support it](https://code.claude.com/docs/en/permission-modes#eliminate-prompts-with-auto-mode). Have the user pick a model that does, and then pick **Automatically approve**. A scheduled task keeps its stored mode, so each run on a model that doesn't support Auto mode switches again.
748750
749751**Model picker is empty or missing models.** Check your gateway's `GET /v1/models` response and your `inferenceModels` list (see [Models](#models)). When `/v1/models` is unreachable or returns an error, the picker falls back to the `inferenceModels` list; if that list is empty, so is the picker.
750752
third-party/claude-desktop/models Changed · +1 / -1 lines
from line 67
6767* **`model-selection.txt`**: the entry's `behavesAs` line says whether the picker uses the value. `(the picker offers that model's options)` means it does.
6868* **`managed-config.txt`**: `behavesAs dropped: not an accepted value` under `Parse errors` means the value isn't a model ID. Enter a full ID such as `claude-sonnet-5`, not a family name such as `sonnet`.
6969
70Without `behavesAs`, users can't change an unrecognized model's effort level. Its conversations and sessions never run above the `maxEffort` on its entry. When it's the default model, they run at [`defaultModelEffort`](https://claude.com/docs/third-party/claude-desktop/configuration#defaultmodeleffort), up to that cap. With only `maxEffort` set, they run at that cap.
70Without `behavesAs`, users can't change an unrecognized model's effort level. Its conversations and sessions never run above the `maxEffort` on its entry. When it's the default model, its new conversations and sessions start at [`defaultModelEffort`](https://claude.com/docs/third-party/claude-desktop/configuration#defaultmodeleffort), up to that cap. With only `maxEffort` set, they run at that cap.
7171
7272## Start every conversation on the default model
7373