claude-docs-20261030T173706Z / documentation capture

third-party/claude-desktop/admin-console Changed · +3 / -3 lines

from line 116

116116

118118| - | - | - | - |

119| [LLM gateway](https://claude.com/docs/third-party/claude-desktop/gateway.md#single-sign-on-with-your-identity-provider) | **Interactive sign-in** with your identity provider | **Gateway SSO IdP (OIDC)** with your identity provider's issuer URL and the client ID of the application you registered for Claude Desktop | The app shows a **Sign in to your organization** button that opens your identity provider's sign-in page in the browser. After sign-in, the app sends that user's token to your gateway on every request, and your gateway validates it. |

119| [LLM gateway](https://claude.com/docs/third-party/claude-desktop/gateway.md#single-sign-on-with-your-identity-provider) | **Interactive sign-in** with your identity provider | **Gateway SSO IdP (OIDC)** with your identity provider's issuer URL and the client ID of the application you registered for Claude Desktop | The app shows a **Sign in with your organization** button that opens your identity provider's sign-in page in the browser. After sign-in, the app sends that user's token to your gateway on every request, and your gateway validates it. |

120120| [Amazon Bedrock](https://claude.com/docs/third-party/claude-desktop/bedrock.md#in-app-aws-sign-in) | **Interactive sign-in** through IAM Identity Center | **AWS SSO start URL**, **AWS SSO region**, **AWS SSO account ID**, and **AWS SSO role name** | The app shows a **Sign in with AWS** page and the user approves in the browser. No AWS CLI is needed. |

121| [Google Cloud's Agent Platform](https://claude.com/docs/third-party/claude-desktop/vertex.md#in-app-google-sign-in), users with Google accounts | **Interactive sign-in** with Google | **Vertex OAuth client ID** and **Vertex OAuth client secret** from a Desktop-app OAuth client in your own Google Cloud project. Google doesn't treat a Desktop-app client secret as confidential, so the console accepts it. | The app shows a **Sign in with Google** page and the user approves Google's consent screen in the browser |

122| [Google Cloud's Agent Platform](https://claude.com/docs/third-party/claude-desktop/vertex.md#in-app-workforce-identity-sign-in), users who sign in with another identity provider | **Workforce Identity** | **Workforce Identity audience** and **Workforce Identity IdP (OIDC)** with your identity provider's issuer URL and client ID | The app shows a **Sign in** page and the user signs in to your identity provider in the browser. No Google identity is needed. |

121| [Google Cloud's Agent Platform](https://claude.com/docs/third-party/claude-desktop/vertex.md#in-app-google-sign-in), users with Google accounts | **Interactive sign-in** with Google | **Vertex OAuth client ID** and **Vertex OAuth client secret** from a Desktop-app OAuth client in your own Google Cloud project. Google doesn't treat a Desktop-app client secret as confidential, so the console accepts it. | The app shows a **Sign in with Google Cloud** page and the user approves Google's consent screen in the browser |

122| [Google Cloud's Agent Platform](https://claude.com/docs/third-party/claude-desktop/vertex.md#in-app-workforce-identity-sign-in), users who sign in with another identity provider | **Workforce Identity** | **Workforce Identity audience** and **Workforce Identity IdP (OIDC)** with your identity provider's issuer URL and client ID | The app shows a **Sign in with Google Cloud** page and the user signs in to your identity provider in the browser. No Google identity is needed. |

123123| [Microsoft Foundry](https://claude.com/docs/third-party/claude-desktop/foundry.md#in-app-entra-id-sign-in) | **Interactive sign-in** with Microsoft Entra ID | **Entra ID tenant ID** and **Entra ID client ID**, and optionally **Entra ID sign-in flow** | The app shows a **Sign in with Microsoft** page and the user signs in with a device code, in the browser, or through the operating system's account picker |

124124| [Bedrock Mantle](https://claude.com/docs/third-party/claude-desktop/mantle.md) | **Helper script**, because Mantle has no interactive sign-in | **Helper script** with the absolute path of a script that prints the bearer token | The app shows no sign-in page and runs the script whenever it needs a token |

125125

third-party/claude-desktop/data-storage Changed · +11 / -3 lines

### Project memory

from line 51

5151

5252During Cowork sessions, Claude writes short Markdown files recording what it has learned about the user — working preferences, project context, and corrections — and reads them at the start of subsequent sessions. These files live under `local-agent-mode-sessions/.../memory/memory/` and never leave the device.

5353

54Users can review and delete individual entries, or pause memory for new sessions and conversations (existing files are kept but not read or updated), under **Settings → Cowork → Memory**. The same page exposes a **Global instructions** editor for the `CLAUDE.md` file that is included in every session.

54Where sessions run on the device, users find the memory controls in these places:

5555

56Each [project](https://claude.com/docs/cowork/guide/projects.md) also keeps its own memory under `local-agent-mode-sessions/.../spaces/<projectId>/memory/`. Cowork sessions inside a project read and update the project's memory rather than the files under `local-agent-mode-sessions/.../memory/memory/`. A Chat conversation inside a project can also read and update the project's memory, as described under [Chat conversations](#chat-conversations).

56* **Pause memory**: users go to **Settings > General** and turn off the **Use memory in sessions** toggle to pause memory for new sessions and conversations (existing files are kept but not read or updated)

57* **Review and delete notes**: where your configuration allows Cowork and the device can run it, users go to **Settings > General** and scroll to the **Memory** heading. Users can review and delete individual notes there.

58* **Edit global instructions**: where your configuration allows Cowork, users go to **Settings > Cowork** and click **Edit** next to **Global instructions** to change the `CLAUDE.md` file that is included in every session

59

60### Project memory

61

62Each [project](https://claude.com/docs/cowork/guide/projects.md) keeps its own memory under `local-agent-mode-sessions/.../spaces/<projectId>/memory/`. Cowork sessions inside a project read and update the project's memory rather than the files under `local-agent-mode-sessions/.../memory/memory/`. A Chat conversation inside a project can also read and update the project's memory, as described under [Chat conversations](#chat-conversations).

63

64To review a project's memory files, users go to **Projects**, open the project, and look under the **Memory** heading. Users click a file to read it, or right-click it and select **Copy path** to get its location on the device.

5765

5866## Chat conversations

5967

third-party/claude-desktop/extensions Changed · +5 / -1 lines

from line 162

162162

163163Put plugin content directly in the marketplace repository with a relative `source` path. When Claude Desktop syncs the marketplace, it doesn't fetch or auto-install a plugin whose `source` points at a different repository, and that plugin doesn't appear in the [**Organization** tab](#plugin-marketplaces-admin). Git submodules aren't fetched either, so a plugin folder added as a submodule is empty on users' devices.

164164

165The marketplace `name` must match `^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$` and must not be one of the reserved values `unknown`, `org`, or `org-provisioned`.

165The marketplace `name` must match `^[A-Za-z0-9]([A-Za-z0-9._-]{0,126}[A-Za-z0-9_-])?$` and must not be one of the reserved values `unknown`, `org`, or `org-provisioned`.

166166

167167### Host the marketplace over HTTPS instead of git

168168

from line 461

461461End users cannot add remote MCP servers from the app's settings or install desktop extension files (`.mcpb`) themselves. Remote servers come from admin-provisioned `managedMcpServers`, from organization plugins, and from other plugins that bundle them, including plugins users install. If a marketplace plugin or a user-added plugin bundles a remote MCP server that requires OAuth sign-in, Claude can't use that server in Cowork sessions or Chat conversations. To make it available there, add a `managedMcpServers` entry with the same `url`, as described under [Remote MCP servers in plugins](#remote-mcp-servers-in-plugins). A Code session can also load the servers a user defines in Claude Code's own configuration (`~/.claude.json`, a project's `.mcp.json`, or `claude mcp add`). To limit plugin-bundled servers, see [Controlling user extensions](#controlling-user-extensions). To limit the servers a Code session loads, see [Applied as managed policy](https://claude.com/docs/third-party/claude-desktop/code.md#applied-as-managed-policy).

462462

463463User-added extensions are stored in the user's [local data directory](https://claude.com/docs/third-party/claude-desktop/data-storage.md) and apply only to that device.

464

465> [!NOTE]

466>

467> If a user adds a marketplace themselves and the **Add marketplace** dialog shows "This marketplace could not be accessed. Private repositories are only supported using the GitHub owner/repo format.", the marketplace's host refused access. To give users the plugins of a private marketplace, add it to [`allowedPluginMarketplaces`](#configure-the-marketplace) with a [marketplace credential](#marketplace-credentials).

464468

465469Claude Desktop keeps its own record of the skills each user creates or uploads, and it removes a skill folder that the record doesn't list. To deliver skills to users, use [organization plugins](#organization-plugins-admin) or a [plugin marketplace](#plugin-marketplaces-admin).

466470

third-party/claude-desktop/gateway Changed · +12 / -2 lines

from line 92

9292

9393Then click **Export** to produce a `.mobileconfig` (macOS) or `.reg` (Windows) file for your MDM. See [Deploy with MDM](https://claude.com/docs/third-party/claude-desktop/mdm.md) for the export and deployment workflow.

9494

95When a user next opens Claude Desktop, they see a **Sign in to your organization** button. Clicking it opens their browser to your Entra sign-in page; once they approve, they return to the app and can start working. The app keeps them signed in and refreshes the token in the background. If the session is revoked or expires under your tenant's policy, the app shows a **Sign in again** prompt; clicking it reopens the sign-in page in the browser.

95When a user next opens Claude Desktop, they see a **Sign in with your organization** button. Clicking it opens their browser to your Entra sign-in page; once they approve, they return to the app and can start working. The app keeps them signed in and refreshes the token in the background. If the session is revoked or expires under your tenant's policy, the app shows a **Sign in again** prompt; clicking it reopens the sign-in page in the browser.

9696

9797#### Using Okta instead

9898

from line 466

466466| - | - | - | - |

469| Sign-in flow | `inferenceGatewayOidcAuthFlow` | No | `browser` (the default) runs the sign-in in the system browser. `broker` runs it through the [OS identity broker](https://claude.com/docs/third-party/claude-desktop/entra-broker.md) on Windows and macOS, which requires `issuer` to be a Microsoft Entra ID issuer (`https://login.microsoftonline.com/TENANT_ID/v2.0`) and needs no loopback redirect. |

469| Gateway sign-in flow | `inferenceGatewayOidcAuthFlow` | No | `browser` (the default) runs the sign-in in the system browser. `broker` runs it through the [OS identity broker](https://claude.com/docs/third-party/claude-desktop/entra-broker.md) on Windows and macOS, which requires `issuer` to be a Microsoft Entra ID issuer (`https://login.microsoftonline.com/TENANT_ID/v2.0`) and needs no loopback redirect. |

470470

471471The `inferenceGatewayOidc` value is one JSON object with these fields:

472472

from line 622

622622> Google Workspace can be used as the identity provider, but in the default `id_token` mode Google does not issue a fresh ID token on background refresh, so users are prompted to sign in again roughly once an hour. Setting `bearerTokenType` to `access_token` avoids this. Entra ID and Okta are not affected in either mode.

623623

624624**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.

625

626**Chat conversations and Cowork tasks fail with `SSL certificate verification failed (UNABLE_TO_VERIFY_LEAF_SIGNATURE)`.** Claude Code, which runs these sessions, couldn't find the certificate authority (CA) that issued your gateway's certificate. A gateway that doesn't send its intermediate certificate and a private CA that the device doesn't trust can both produce this message. A passing connection test in the app doesn't rule out a missing intermediate certificate, because the app can fetch one itself and Claude Code can't.

627

628To see which certificates your gateway sends, run this command in a terminal on a machine that connects to the gateway directly. Use your gateway's host name in place of `llm-gateway.example.corp`:

629

630```bash theme={null}

631openssl s_client -connect llm-gateway.example.corp:443 -servername llm-gateway.example.corp -showcerts </dev/null

632```

633

634If the output doesn't include the intermediate certificate that issued the gateway's certificate, configure the gateway, or the load balancer in front of it, to send its full certificate chain. For a private CA, see [TLS-intercepting proxies](https://claude.com/docs/third-party/claude-desktop/network-proxy.md#tls-intercepting-proxies).

625635

626636**The 1M context window entry does not appear in the picker.** `supports1m` takes effect only when the entry's `name` matches the model ID the picker uses. Setting it on a bare alias (for example `sonnet`) while discovery returns full model IDs produces no match. Set `supports1m` on an entry whose `name` is the exact ID your gateway's `/v1/models` endpoint returns. With `prefer1m` or `modelPrefer1mContext` set, a model whose `name` matches has one entry and no **1M context window** label.

627637

third-party/claude-desktop/installation Changed · +5 / -4 lines

from line 20

2020

2121* **Log on as a service**: Cowork's virtual machine runs under an account in the built-in `NT VIRTUAL MACHINE\Virtual Machines` group, and that group needs the **Log on as a service** user right. If your organization assigns that right through Group Policy or MDM, see [Windows security policy blocks the Cowork workspace](#windows-security-policy-blocks-the-cowork-workspace).

2222* **Hooks**: a [hook](https://code.claude.com/docs/en/hooks) command written for Bash needs Git for Windows on the device. If your Windows devices have hooks in plugins or in Claude Code managed settings, see [Hooks on Windows devices without Git for Windows](https://claude.com/docs/third-party/claude-desktop/extensions.md#hooks-on-windows-devices-without-git-for-windows).

23* **Virtual desktops**: on virtual desktop infrastructure, Windows itself runs in a virtual machine, so Cowork's virtual machine starts only where the hosting platform exposes nested virtualization to that virtual machine. Run the [readiness check](#check-device-readiness) on one desktop in each pool.

2324

2425With [Unified Claude](https://claude.com/docs/third-party/claude-desktop/unified-claude.md) on, a message sent from the home screen starts a Cowork session on a device that can run Cowork. On a device that can't run Cowork's virtual machine, the message starts a Chat conversation.

2526

from line 128

127128

128129### Windows security policy blocks the Cowork workspace

129130

130On Windows, the app shows **A Windows security policy is blocking Claude's workspace** when a user-rights policy stops the virtual machine that Cowork runs in from starting. Cowork tasks don't start on that device, and [advanced file analysis](https://claude.com/docs/third-party/claude-desktop/chat.md#advanced-file-analysis) in Chat, which uses the same virtual machine, fails too. The banner's **Copy details** button copies a description of the error that includes the code `0x80070569`. Standard (non-3P) installs show this banner too.

131On Windows, the app shows **A Windows security policy is blocking Claude's workspace** when a user-rights policy stops Cowork's virtual machine from starting. On that device, Cowork tasks start, but the shell commands that Claude runs in them fail. [Advanced file analysis](https://claude.com/docs/third-party/claude-desktop/chat.md#advanced-file-analysis) in Chat, which uses the same virtual machine, fails too. The banner's **Copy details** button copies a description of the error that includes the code `0x80070569`. Standard (non-3P) installs show this banner too.

131132

132133The virtual machine runs under an account in the built-in `NT VIRTUAL MACHINE\Virtual Machines` group (SID `S-1-5-83-0`), and that group needs the **Log on as a service** user right. Microsoft's [Starting or live migrating Hyper-V VMs fails](https://learn.microsoft.com/en-us/troubleshoot/windows-server/virtualization/starting-or-live-migrating-hyper-v-vms-fails) describes the same error for Hyper-V virtual machines when the group is missing that right. A Group Policy that defines **Log on as a service** replaces the list of accounts on each device instead of adding to it. When the policy's list leaves this group out, or a policy lists the group under **Deny log on as a service**, the virtual machine can't start.

133134

from line 148

147148

148149## Endpoint security software

149150

150Claude Desktop runs Chat conversations, Cowork tasks, and Code sessions through an agent helper, a signed binary that it keeps under its user-data directory (with the standard installer) 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.

151Claude 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.

151152

152153**Allowlist the helper by signing identity rather than path** so the rule survives version updates. The helper's path includes a `<build-id>` folder, a 12-character name that differs from one build of the helper to the next.

153154

from line 171

170171%LOCALAPPDATA%\Claude-3p\claude-code\<version>\<build-id>\claude.exe

171172```

172173

173The helper is Authenticode-signed with publisher `Anthropic, PBC`. Standard installs use `%APPDATA%\Claude\` with the same subpath.

174The helper is Authenticode-signed with publisher `Anthropic, PBC`.

174175

175176For Defender ASR, a Microsoft Defender for Endpoint [certificate indicator](https://learn.microsoft.com/en-us/defender-endpoint/indicator-certificates) matches one certificate, not the publisher name. If you use certificate indicators, you need one for each of the following certificates and another whenever Anthropic renews its signing certificate:

176177

from line 263

262263

263264> [!NOTE]

264265>

265> Add the restart keys after your devices have a version that supports them. An earlier version can show people a configuration warning at every launch, or reject the managed configuration that holds the keys and ignore the device's own configuration too. For what each platform does with a key it doesn't know, see [`installedUpdateEnforcementEnabled`](https://claude.com/docs/third-party/claude-desktop/configuration#installedupdateenforcementenabled).

266> Add the restart keys after your devices have a version that supports them. An earlier version can show people a configuration warning at every launch, or reject the managed configuration that holds the keys and ignore the device's own configuration too.

266267

third-party/claude-desktop/network-proxy Changed · +5 / -4 lines

from line 6

66

77Three parts of the product make network connections, and they do not all resolve the proxy the same way:

88

9* **The app**: the Claude Desktop window itself, including sign-in, the connection test, Web Fetch in Chat and Cowork sessions, managed MCP servers the app connects to, and plugin marketplace sync.

10* **The agent**: the Claude Code engine the app runs for every Chat, Cowork, and Code session. It sends inference requests and, in Code sessions, also makes its own web fetches, remote MCP connections, and plugin installs.

9* **The app**: the Claude Desktop window itself, including sign-in, the connection test, Web Fetch in Chat and Cowork sessions, managed MCP servers the app connects to, and sync of the plugin marketplaces you configure.

10* **The agent**: the Claude Code engine the app runs for every Chat, Cowork, and Code session. It sends inference requests and makes its own remote MCP connections, for example to [a server that a marketplace plugin or a user-added plugin bundles](https://claude.com/docs/third-party/claude-desktop/extensions.md#remote-mcp-servers-in-plugins). In Code sessions, it also makes its own web fetches and plugin installs.

1111* **Cowork's sandboxed shell**: the isolated environment where commands the agent runs in a Cowork session (`curl`, `pip`, `npm`, and so on) execute.

1212

1313With [Unified Claude](https://claude.com/docs/third-party/claude-desktop/unified-claude.md) on, a Cowork session started from the home screen runs its commands in Cowork's sandboxed shell.

from line 79

7979| App window, in-app sign-in, connection test, model list | App proxy |

8080| Inference requests from Chat, Cowork, and Code sessions | The single proxy resolved for the inference endpoint (from the pinned key or the OS), or Claude Code managed settings if deployed |

8181| Agent web fetch, remote MCP servers, and plugin installs in Code sessions | Same single proxy as inference |

82| The agent's remote MCP connections in Chat and Cowork sessions, to servers that a marketplace plugin or a user-added plugin bundles | Same single proxy as inference |

8283| Web Fetch and managed MCP servers in Chat and Cowork sessions | App proxy (the app makes these connections) |

83| Plugin marketplace sync and `aws` CLI calls the app makes for Bedrock sign-in | App proxy, resolved for the specific host |

84| Sync of the plugin marketplaces you configure, and `aws` CLI calls the app makes for Bedrock sign-in | App proxy, resolved for the specific host |

8485| Cowork sandbox download from `downloads.claude.ai` | App proxy |

8586| Telemetry and crash reports to Anthropic, if enabled | App proxy |

8687| OpenTelemetry export to your collector | App proxy for the app's own events; the same single proxy as inference for Claude Code metrics and logs |

from line 113

112113

113114### The agent uses one proxy

114115

115The agent sends all of its own traffic (inference, and in Code sessions its web fetches, remote MCP connections, and plugin installs) through the one proxy resolved for your inference endpoint. Per-host PAC rules are not re-evaluated inside the agent. For most organizations this is the desirable outcome: everything the agent does is logged and inspected at one place, with nothing further to configure.

116The agent sends all of its own traffic (inference, its remote MCP connections, and in Code sessions its web fetches and plugin installs) through the one proxy resolved for your inference endpoint. Per-host PAC rules are not re-evaluated inside the agent. For most organizations this is the desirable outcome: everything the agent does is logged and inspected at one place, with nothing further to configure.

116117

117118It needs attention only when that one proxy is not right for everything the agent reaches: typically some hosts (an internal MCP server, a private package registry, a self-hosted plugin marketplace) must be reached directly while the proxy only carries public traffic, or the reverse. In order of preference:

118119

third-party/claude-desktop/vertex Changed · +5 / -5 lines

from line 168

168168

169169#### How it works

170170

171When `inferenceVertexOAuthClientId` and `inferenceVertexOAuthClientSecret` are both set, the app shows a **Sign in with Google** 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.

171When `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.

172172

173173At 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.

174174

from line 204

2042042. Provision those users into Cloud Identity (via SCIM from your IdP, or Google Cloud Directory Sync) so IAM grants resolve.

2052053. Optionally set `inferenceVertexOAuthLoginHint` so Google skips its own account chooser and routes straight to your IdP with the user's identity pre-filled.

206206

207With this in place, clicking **Sign in with Google** opens the browser, Google immediately redirects to your IdP, the user authenticates there (including smart-card or PIV authentication if your IdP supports it), and Google issues the tokens on return. Claude Desktop is unchanged; the federation is configured entirely in Google Admin and your IdP.

207With this in place, clicking **Sign in with Google Cloud** opens the browser, Google immediately redirects to your IdP, the user authenticates there (including smart-card or PIV authentication if your IdP supports it), and Google issues the tokens on return. Claude Desktop is unchanged; the federation is configured entirely in Google Admin and your IdP.

208208

209209#### Notes and limitations

210210

211211* **Precedence.** When both `inferenceVertexOAuthClientId` and `inferenceVertexCredentialsFile` are set and `inferenceCredentialKind` is not, Google sign-in takes precedence and the credentials file is ignored (the app logs a multi-credential warning). To force the credentials file, set `inferenceCredentialKind` to `vendor-profile` or remove the OAuth client keys.

212* **Both keys required.** Set `inferenceVertexOAuthClientId` and `inferenceVertexOAuthClientSecret` together. With only one of them set, the app shows no **Sign in with Google** page.

212* **Both keys required.** Set `inferenceVertexOAuthClientId` and `inferenceVertexOAuthClientSecret` together. With only one of them set, the app shows no **Sign in with Google Cloud** page.

213213* **Client rotation.** If you replace the OAuth client in Google Cloud and push the new client ID via MDM, existing users are automatically signed out and prompted to sign in again on next launch.

214214

215215### In-app Workforce Identity sign-in

from line 223

223223

224224Register the redirect URI with `127.0.0.1` rather than `localhost`, because the app uses `127.0.0.1` by default and most IdPs do not treat the two as interchangeable. If your IdP accepts only `localhost` in a registered redirect URI, set the `redirectHost` field of [`inferenceVertexWorkforceOidc`](https://claude.com/docs/third-party/claude-desktop/configuration#inferencevertexworkforceoidc) to `localhost` and register `http://localhost/callback` instead, or `http://localhost:<port>/callback` when you set `redirectPort`.

225225

226Distribute the workforce-pool provider audience and the IdP OIDC client in the managed configuration; the app shows a **Sign in** page on first launch, runs an authorization-code-with-PKCE flow against your IdP in the system browser, exchanges the returned ID token for a Google Cloud access token at `sts.googleapis.com`, and stores the IdP refresh token encrypted with the operating system's secure storage. No `gcloud` CLI, helper script, or Google identity is required.

226Distribute the workforce-pool provider audience and the IdP OIDC client in the managed configuration; the app shows a **Sign in with Google Cloud** page on first launch, runs an authorization-code-with-PKCE flow against your IdP in the system browser, exchanges the returned ID token for a Google Cloud access token at `sts.googleapis.com`, and stores the IdP refresh token encrypted with the operating system's secure storage. No `gcloud` CLI, helper script, or Google identity is required.

227227

228228The app always requests the `offline_access` scope so that the IdP returns a refresh token for silent renewal. If your IdP rejects `offline_access` on this client (for example, a PingFederate public client without the Refresh Token grant type enabled), set the `omitOfflineAccess` field of `inferenceVertexWorkforceOidc` to `true`. Without a refresh token the app cannot refresh silently, so users will be prompted to sign in again each time the IdP's ID token expires, typically about once an hour.

229229

from line 445

445445| Approach | First launch | Re-authentication |

446446| - | - | - |

447447| Credentials file (service-account key) | The app opens directly; no user action. | Never, until you rotate the key file. |

448| In-app Google sign-in | The app shows a **Sign in with Google** page. Clicking it opens Google's consent flow in the default browser. After approval, the app returns to Cowork. | When the refresh token is revoked, when you deploy a new OAuth client ID, or when your Google Cloud session-control policy expires it. |

448| In-app Google sign-in | The app shows a **Sign in with Google Cloud** page. Clicking it opens Google's consent flow in the default browser. After approval, the app returns to Cowork. | When the refresh token is revoked, when you deploy a new OAuth client ID, or when your Google Cloud session-control policy expires it. |

449449

450450For in-app Google sign-in, the browser flow runs on the host (outside the Cowork sandbox), so it can use the user's existing Google session and any security keys or passkeys configured on the device. Users can sign out by revoking the app from their Google Account's [third-party connections page](https://myaccount.google.com/connections); the app detects the revoked token and shows a **Sign in again** prompt.

451451

third-party/claude-desktop/web-tools Changed · +4 / -2 lines

from line 95

9595}

9696```

9797

98Set the per-entry `toolPolicy` to `"allow"` so users aren't prompted to approve each search. `headersHelper` is an executable that prints the auth header as a JSON object to stdout; it follows the same execution model as [`inferenceCredentialHelper`](https://claude.com/docs/third-party/claude-desktop/credential-helper) (exit 0, stdout read as JSON), but the output here is a flat header map, not the `{token, headers}` shape `inferenceCredentialHelper` uses.

98Set the per-entry `toolPolicy` to `"allow"` so users aren't prompted to approve each search in Cowork sessions and Chat conversations. For Code sessions, see [Tool permissions for managed MCP servers](https://claude.com/docs/third-party/claude-desktop/configuration.md#tool-permissions-for-managed-mcp-servers). `headersHelper` is an executable that prints the auth header as a JSON object to stdout; it follows the same execution model as [`inferenceCredentialHelper`](https://claude.com/docs/third-party/claude-desktop/credential-helper) (exit 0, stdout read as JSON), but the output here is a flat header map, not the `{token, headers}` shape `inferenceCredentialHelper` uses.

9999

100100| Provider | Header your script should output |

101101| - | - |

from line 160

160160

161161* **Web Fetch**: each host you list becomes a Claude Code `WebFetch` allow rule. The key doesn't block a fetch to another host. In Auto mode, which new Code sessions start in by default, and in bypass permissions mode, Claude Code doesn't ask the user before that fetch. For the other modes, see [WebFetch tool behavior](https://code.claude.com/docs/en/tools-reference#webfetch-tool-behavior).

162162* **Web Fetch controls**: to have the user approve every fetch, set `WebFetch` to `"ask"` in [`builtinToolPolicy`](https://claude.com/docs/third-party/claude-desktop/configuration#builtintoolpolicy), which also applies in Cowork and Chat. To remove the tool, see [Disabling web tools](#disabling-web-tools).

163* **Shell commands**: commands that run in [Claude Code's sandbox](https://claude.com/docs/third-party/claude-desktop/code.md#applied-as-managed-policy) reach only the hosts you list. On Windows, and on Linux without Claude Code's sandbox dependencies, shell commands run unsandboxed and can reach any host your network allows. To keep Code off such devices, see [Disabling Code](https://claude.com/docs/third-party/claude-desktop/code.md#disabling-code). For SSH hosts, see [Sandbox status on the remote host](https://claude.com/docs/third-party/claude-desktop/ssh-remote-sessions.md#sandbox-status-on-the-remote-host).

163* **Shell commands**: commands that run in [Claude Code's sandbox](https://claude.com/docs/third-party/claude-desktop/code.md#applied-as-managed-policy) reach only the hosts you list, and no host while the key is unset or empty. On Windows, and on Linux without Claude Code's sandbox dependencies, shell commands run unsandboxed and can reach any host your network allows. To keep Code off such devices, see [Disabling Code](https://claude.com/docs/third-party/claude-desktop/code.md#disabling-code). For SSH hosts, see [Sandbox status on the remote host](https://claude.com/docs/third-party/claude-desktop/ssh-remote-sessions.md#sandbox-status-on-the-remote-host).

164

165While the key is unset, Claude Desktop turns on Claude Code's sandbox, including on a device that you set up yourself, for example with your own API key. On a device where the sandbox runs, the **Local sandbox** and **Strict sandbox mode** switches under **Settings > Claude Code** are on and locked, and the app says that your organization manages them. To let shell commands reach a host, add it to `coworkEgressAllowedHosts` in your configuration. On a device that you set up yourself, open the [in-app configuration window](https://claude.com/docs/third-party/claude-desktop/in-app-configuration.md), go to **Capabilities**, add the host under **Allowed egress hosts**, click **Apply Changes**, and then click **Save & Restart**.

164166

165167## Disabling web tools

166168

government/deploy-desktop/configure Changed · +1 / -1 lines

from line 305

305305| On a Windows device, Cowork tasks fail, the app shows **Failed to start Claude's workspace** with a message under it about a Windows update, or Claude can't read some attached files in Chat, such as Word, Excel, or PowerPoint files | The device has installed the Windows update released September 8, 2026, but not Microsoft's later update that fixes the problem. The September 8 update stops Claude's workspace from reaching files on the device. Cowork tasks and Advanced file analysis in Chat need the workspace. | Install the latest Windows update on the device and restart it. On Windows 11 24H2 and 25H2, the fix is KB5129195. No Claude Desktop update is needed. See [Resolved: Cowork on Windows](https://claude.com/docs/cowork/changelog.md#resolved-cowork-on-windows) in the Claude Desktop changelog. |

306306| Web search is on for your organization, but a user does not have it, and under **Customize**, then **Connectors**, **Web Search** shows as not connected and **Connect** fails, while chat works | A firewall or secure web gateway on that user's network path filters traffic by application. Claude Desktop connects to web search on your Claude for Government host over HTTPS, and such equipment can classify that connection as Model Context Protocol (MCP) traffic and block it even when the host itself is allowed. | Ask your network team to allow this traffic to your Claude for Government host for the affected users. The user's `main.log` records each failed attempt, including any block page the network returned. Then have the user select **Connect** next to **Web Search**, or restart the app. |

307307| The app shows **Failed to start Claude's workspace** with a download error under it, or Chat conversations and Cowork tasks fail to start with "Host Claude Code binary not available. Check that the download completed." | Claude Desktop could not download a complete, verified copy of the Cowork workspace or the [agent helper](https://claude.com/docs/third-party/claude-desktop/installation.md#endpoint-security-software) from `downloads.claude.ai`. This usually means a proxy or web filter on the device's network path is blocking or altering the download. | Follow [Cowork workspace or Claude CLI fails to download](https://claude.com/docs/third-party/claude-desktop/installation.md#cowork-workspace-or-claude-cli-fails-to-download) in the Claude Desktop documentation. |

308| On a Windows device, the app shows **A Windows security policy is blocking Claude's workspace**, and Cowork tasks don't start | A Group Policy or MDM policy applied to the device assigns the **Log on as a service** right without the `NT VIRTUAL MACHINE\Virtual Machines` group, or lists that group under **Deny log on as a service** | Follow [Windows security policy blocks the Cowork workspace](https://claude.com/docs/third-party/claude-desktop/installation.md#windows-security-policy-blocks-the-cowork-workspace) in the Claude Desktop documentation. |

308| On a Windows device, the app shows **A Windows security policy is blocking Claude's workspace**, and the shell commands that Claude runs in Cowork tasks fail | A Group Policy or MDM policy applied to the device assigns the **Log on as a service** right without the `NT VIRTUAL MACHINE\Virtual Machines` group, or lists that group under **Deny log on as a service** | Follow [Windows security policy blocks the Cowork workspace](https://claude.com/docs/third-party/claude-desktop/installation.md#windows-security-policy-blocks-the-cowork-workspace) in the Claude Desktop documentation. |

309309

310310For anything else, the app writes its log to `~/Library/Logs/Claude-3p/main.log` on macOS, `%LOCALAPPDATA%\Claude-3p\logs\main.log` on Windows, and `~/.config/Claude-3p/logs/main.log` on Linux. The log records which configuration keys were read or dropped and why. The diagnostic report from the verification checklist produces a bundle, without conversation content, that you can send to your Anthropic representative.

311311

third-party/claude-desktop/bedrock Changed · +1 / -1 lines

from line 327

327327

328328For in-app AWS sign-in, the browser flow runs on the host (outside the Cowork sandbox), so it uses the user's existing identity-provider session and any security keys or passkeys configured on the device. The **AWS access portal session duration** setting (IAM Identity Center → **Settings** → **Authentication**) controls how long users stay signed in across app restarts. To force a user to sign in again sooner, delete their active session from the IAM Identity Center console.

329329

330If the app cannot locate the AWS CLI, it cannot drive the login itself; it instructs the user to install AWS CLI v2 and run `aws sso login --profile <name>` manually.

330With a named profile and `inferenceBedrockAwsCliPath` unset, if the app can't find the AWS CLI, it can't run `aws sso login` for the user. It tells the user to install the AWS CLI and sign in again.

331331

332332## Troubleshoot

333333

third-party/claude-desktop/chat Changed · +1 / -1 lines

from line 57

5757* Code runs in the same isolated local VM that Cowork uses. For Chat, the VM starts only when analysis is coming: on the first analysis call, or at the start of a turn with files attached.

5858* Commands in the sandbox can reach the hosts in `coworkEgressAllowedHosts`. See [Sandbox network access](#sandbox-network-access).

5959* The only conversation data the sandbox sees is the conversation's attached files (read-only), its scratch directory (writable), its own transcript and saved tool results, such as connector results (read-only), and, for a conversation inside a project, that project's memory (read-only), plus read-only reference material bundled by the app. The sandbox sees no user folders except, for a conversation inside a project, [the project's folders](#project-folders-in-chat) (read-only), and no other sessions' working directories or transcripts.

60* The sandbox doesn't see project folders in a conversation that starts while a rule for `"Read"`, `"Grep"`, or `"Glob"` is set in `disabledBuiltinTools`, in `builtinToolPolicy` with a value other than `"allow"`, or as a deny or ask rule in Claude Code's own managed settings on the device. See [`chatAdvancedFileAnalysisEnabled`](https://claude.com/docs/third-party/claude-desktop/configuration#chatadvancedfileanalysisenabled) for more cases.

60* The sandbox doesn't see project folders in a conversation that starts while a rule for `"Read"`, `"Grep"`, or `"Glob"` is set in `disabledBuiltinTools`, in `builtinToolPolicy` with a value other than `"allow"`, or as a deny or ask rule in Claude Code's own managed settings on the device.

6161* Each command runs independently; results land in the scratch directory, where Claude can offer them to the user as downloads or artifacts.

6262

6363The data flow end to end: an attached file is copied into the conversation's local uploads directory, mounted read-only into the sandbox when analysis runs, and any outputs are written to the conversation's scratch directory on local disk. File content leaves the device only as conversation context sent to your configured inference provider, in web search queries to your configured search backend, through web fetches your egress allowlist permits, through [sandbox network access](#sandbox-network-access), in a connector tool call permitted by your `toolPolicy` configuration and the user's approvals, or, if you have enabled [content capture](https://claude.com/docs/third-party/claude-desktop/telemetry.md#content-capture), in telemetry to your own collector.

third-party/claude-desktop/in-app-configuration Changed · +1 / -1 lines

from line 31

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 |

3333| 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 |

34| Egress allowlist | Your firewall or network team |

34| 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

third-party/claude-desktop/mdm Changed · +2 / -2 lines

from line 34

3434

3535| Section | What you set |

3636| - | - |

37| **Connection** | Inference provider (Gateway, Claude API, Google Cloud's Agent Platform, Bedrock, Bedrock Mantle, or Foundry) and its credentials Model list Organization UUID Optional credential-helper script |

37| **Connection** | Inference provider (Gateway, Claude API, Google Cloud's Agent Platform, Bedrock, Bedrock Mantle, or Foundry) and its credentials Model list Optional credential-helper script |

3838| **Capabilities** | Which of Cowork, Code, and Chat are available Allowed egress hosts for the sandbox Disabled built-in tools Allowed workspace folders |

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 |

40| **Telemetry & updates** | 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) |

40| **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 |

4242| **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 |

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 |

One read of Claude Documentationclaude-docs-20261030T173706Z

What this read moved