One read of Claude Documentationclaude-docs-20260814T092040Z
213 pages moved out of 213 read.
Pages moved
213
significant first
Pages read
213
in this capture
Captured
09:20 UTC
Corpus hash
dfa3e64bc187
full baseline · baseline
What this read moved
201-213 of 213, page 9 of 9This capture is too large to show at once. Changes 201-213 of 213 are below, significant first; the rest are on the following screens.
third-party/claude-desktop/feature-matrix First recorded · 72 lines, first recorded
# Features ## Key differences ## User features ## Admin features
The first capture of this source. The page was already there, and this is what it said.
# Features > Feature comparison between Claude Enterprise and Claude Desktop on third-party (3P) The tables below compare the feature set of Claude Desktop on third-party (3P) to Claude Enterprise. ## Key differences **Configuration.** Claude Enterprise uses a web-based admin console. Claude Desktop on 3P is configured entirely via [MDM](/docs/third-party/claude-desktop/mdm) (Jamf, Intune, Group Policy) or a [bootstrap server](/docs/third-party/claude-desktop/bootstrap), with no Anthropic-hosted admin interface. **Telemetry.** Claude Desktop on 3P sends usage and debugging metrics only, and these can be fully disabled via managed configuration. Claude Enterprise does not offer telemetry toggles. See [Telemetry and egress](/docs/third-party/claude-desktop/telemetry). **Inference.** Claude Desktop on 3P routes all inference through the provider you configure. For Google Cloud's Agent Platform and Amazon Bedrock, data handling is governed by Google Cloud and Amazon Bedrock respectively. For Microsoft Foundry deployments hosted on Azure, prompts and completions remain within Azure; only usage metadata and content flagged by Anthropic's safety systems egress to Anthropic. Deployments hosted on Anthropic run on Anthropic's infrastructure. See the [Microsoft Foundry page](/docs/third-party/claude-desktop/foundry) for details. **Pricing.** Claude Desktop on 3P is token-based consumption billed by your cloud provider, with no seat licensing. **Features not available in 3P.** Features marked with — are absent from the UI. Users see a clean interface without error states for unavailable features. ## User features | Feature | Claude Enterprise | Claude Desktop on 3P | | --------------------------------------------------- | :---------------: | :------------------: | | Chat | ✓ | ✓ (admin opt-in) | | Cowork | ✓ | ✓ | | Code | ✓ | ✓ | | Auto mode (Code) | ✓ | ✓ (admin opt-in) | | Automatically approve / Skip all approvals (Cowork) | — ¶ | ✓ (admin opt-in) | | Projects | ✓ | ✓ | | Code execution for analysis | ✓ | ✓ | | Web search | ✓ | ✓ § | | File access, upload, and export | ✓ | ✓ | | Local MCP | ✓ | ✓ | | Remote MCP | ✓ | ✓ | | Skills, plugins, and hooks | ✓ | ✓ | | Artifacts | ✓ | ✓ | | Memory | ✓ | ✓ † | | Scheduled tasks | ✓ | ✓ | | Global languages | ✓ | ✓ | | Project and plugin sharing | ✓ | — | | Plugin marketplaces | ✓ | ✓ | | Mobile | ✓ | — | | claude.ai web-based access | ✓ | — | | Voice mode | ✓ | — | | Claude in Chrome | ✓ | — | | Claude Design | ✓ | — | | Claude Security | ✓ | — | | Claude Tag | ✓ | — | | Computer use | — | — | § Amazon Bedrock deployments (and gateways that do not forward Anthropic server tools) need a web search provider configured first; see [Web search options](/docs/third-party/claude-desktop/web-tools#web-search-options). † Memory in Claude Desktop on 3P is stored on the device, not on Anthropic infrastructure. Users can review, delete, or pause it under **Settings → Cowork → Memory**; see [Memory](/docs/third-party/claude-desktop/data-storage#memory). Chat-history search and nightly summary generation are not available in Chat on 3P. ¶ Cowork's Automatically approve and Skip all approvals modes are not available for Claude Enterprise organizations. ## Admin features | Feature | Claude Enterprise | Claude Desktop on 3P | | --------------------------------------------- | :----------------: | :------------------: | | Endpoint / gateway configuration | — | ✓ | | Skills, hooks, and plugins distribution | ✓ | ✓ | | MCP server allowlist | ✓ | ✓ | | Feature toggles (web search, local MCP, etc.) | ✓ | ✓ | | Auto-updates | ✓ | ✓ (configurable) | | Per-user spend caps | ✓ (differentiated) | ✓ (blanket only) | | Compliance API | ✓ | — ‡ | | Analytics API | ✓ | — ‡ | | OpenTelemetry export | ✓ | ✓ | | User management via UI | ✓ | — | | RBAC | ✓ | via MDM | ‡ Many of these capabilities can be achieved via OpenTelemetry export to your own collector. See [Monitoring](/docs/cowork/monitoring).
third-party/claude-desktop/foundry First recorded · 150 lines, first recorded
# Deploy Claude Desktop on 3P with Microsoft Foundry ## Choose an authentication approach ## Set up Azure ## Prepare devices ### API key ### In-app Entra ID sign-in #### Allow network egress ## Configure the app ### Configuration keys ## What users experience ## Troubleshoot
The first capture of this source. The page was already there, and this is what it said.
# Deploy Claude Desktop on 3P with Microsoft Foundry
> Set up Microsoft Foundry, choose an authentication path for your organization, and configure Claude Desktop on 3P to use Claude models on Microsoft Foundry
This page walks an IT administrator through a Microsoft Foundry deployment: creating the Microsoft Foundry resource, choosing the authentication path that fits your organization, and pushing the managed configuration. If you only need the list of configuration keys, skip to [Configure the app](#configure-the-app).
<Note>
Claude models in Microsoft Foundry are available in two hosting options, Hosted on Azure and Hosted on Anthropic. Anthropic acts as an independent processor for Microsoft, and customers are subject to Anthropic's data use terms. For deployments hosted on Azure, prompts and completions remain within Azure; only usage metadata and content flagged by Anthropic's safety systems egress to Anthropic. Deployments hosted on Anthropic run on Anthropic's infrastructure. See [Claude in Microsoft Foundry](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options) for details.
</Note>
## Choose an authentication approach
| Scenario | Use | Per-user identity | Notes |
| --------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Proof of concept, single team | [API key](#api-key) (`inferenceFoundryApiKey`) | No (shared key) | A long-lived secret distributed in the managed profile. Simplest to start. |
| Broad rollout with per-user identity | [In-app Entra ID sign-in](#in-app-entra-id-sign-in) (`inferenceFoundryTenantId`, `inferenceFoundryClientId`, `inferenceFoundryAuthFlow`) | Yes | Users sign in with their Entra ID account inside the app, through a device code, the system browser, or the OS identity broker. The device-code flow requires app version 1.9255.0 or later; the browser flow requires app version 1.19367.0 or later. |
| Your organization already has tooling that obtains a Microsoft Foundry credential | [Credential helper](/docs/third-party/claude-desktop/configuration#inferencecredentialhelper) (`inferenceCredentialHelper`) | Depends on what the helper obtains | An executable that prints the credential to stdout at runtime. |
## Set up Azure
These steps are performed once per Azure subscription. You need permission to create resources and, for in-app sign-in, to register an application in Microsoft Entra ID.
<Steps>
<Step title="Create a Microsoft Foundry resource">
In the Azure portal, create a Microsoft Foundry resource in your subscription. Record the **resource name**; the app constructs the endpoint as `<resource-name>.services.ai.azure.com`.
</Step>
<Step title="Deploy the Claude models">
In the Microsoft Foundry portal for your resource, deploy the Claude models you intend to serve. Record each **deployment name**; you will list these in `inferenceModels`.
</Step>
<Step title="Obtain an API key (API-key approach only)">
If you chose the API-key approach, copy one of the resource's keys from the Azure portal. You will place it in the managed configuration in [Configure the app](#configure-the-app).
</Step>
<Step title="Register an Entra ID application (in-app sign-in only)">
If you chose in-app Entra ID sign-in, register an application in the [Microsoft Entra admin center](https://entra.microsoft.com) under **Identity → Applications → App registrations → New registration**. On the registration:
* Under **API permissions**, select **Add a permission**, find **Azure Cognitive Services** in the API picker, and add the **Delegated** permission **user\_impersonation** so the issued token is accepted by your Microsoft Foundry resource. (The app requests this permission as the scope `https://cognitiveservices.azure.com/.default`.) All three sign-in flows need it. After adding the permission, select **Grant admin consent**; in tenants that disable user consent, sign-in fails with error code `AADSTS65001` until consent is granted.
* Under **Authentication**, complete the setup for the sign-in flow you plan to use (see [In-app Entra ID sign-in](#in-app-entra-id-sign-in) for how the flows differ):
* For the device-code flow (the default), enable **Allow public client flows**. Entra ID rejects device-code sign-in without it.
* For the browser flow (`inferenceFoundryAuthFlow` set to `browser`), select **Add a platform → Mobile and desktop applications** and add the redirect URI `http://127.0.0.1/callback`. Use the literal address `127.0.0.1`, not `localhost`: Entra ID matches the scheme, host, and path exactly and ignores only the port. The browser flow completes sign-in without **Allow public client flows**. Conditional Access policies that block the device-code authentication flow do not apply to the browser flow.
* For the broker flow (`inferenceFoundryAuthFlow` set to `broker`), enable **Allow public client flows** and add the platform's broker redirect URI under **Mobile and desktop applications**. See [Register the Entra ID application](/docs/third-party/claude-desktop/entra-broker#register-the-entra-id-application) on the OS identity broker page for the redirect URI values and why the public-client setting is required.
Record the **Directory (tenant) ID** and **Application (client) ID**.
Grant the users or groups who will sign in a role on the Microsoft Foundry resource that permits inference (for example, **Cognitive Services User**).
</Step>
</Steps>
## Prepare devices
What each end-user device needs depends on the authentication approach you chose.
### API key
No per-device preparation is required. Place the resource's API key in the managed configuration as `inferenceFoundryApiKey`.
### In-app Entra ID sign-in
Distribute `inferenceFoundryTenantId` and `inferenceFoundryClientId` in the managed configuration. To use the browser or broker flow instead of the default device-code flow, also set `inferenceFoundryAuthFlow` to `browser` or `broker`.
The device-code and browser flows need no per-device preparation. The broker flow signs in through the operating system's native Microsoft identity broker, so each device must meet the platform requirements on the [OS identity broker](/docs/third-party/claude-desktop/entra-broker#prepare-devices) page.
When the tenant and client IDs are set and `inferenceCredentialKind` is `interactive`, the app shows a **Sign in with Microsoft** page at first launch. Clicking the button starts a sign-in against `login.microsoftonline.com`; what the user sees depends on `inferenceFoundryAuthFlow`:
* **Device code** (the key is unset or `device-code`): the app displays a short verification code and opens the Microsoft sign-in page in the default browser, where the user enters the code and approves access.
* **Browser** (the key is `browser`): the app opens the Microsoft sign-in page in the default browser, where the user signs in and approves access. The browser shows a confirmation page and the user switches back to the app; there is no code to enter.
* **Broker** (the key is `broker`): the app opens the operating system's native Microsoft account picker, where the user selects or signs in to a work account. The dialog closes and the app returns to Cowork; nothing opens in the browser. Because the broker issues the token, sign-in satisfies Conditional Access policies that require a compliant or managed device or token protection, which the other two flows cannot satisfy on their own. See [Sign in through the OS identity broker](/docs/third-party/claude-desktop/entra-broker) for what the broker is and when to choose it.
On success, the app returns to Cowork. For the device-code and browser flows the app stores the refresh token encrypted with the operating system's secure storage (Keychain on macOS, DPAPI on Windows), and both flows store the same token against the same app registration, so switching between them later does not itself prompt users to sign in again. For the broker flow the operating system's broker holds the credential, and the app stores only a reference to the signed-in account.
If the app can no longer renew the credential silently, it shows a **Sign in again** prompt; clicking it reopens the configured sign-in flow. For the device-code and browser flows this happens when the stored refresh token expires or is revoked. For the broker flow it happens when the broker can no longer renew the token silently.
`inferenceFoundryTenantId` and `inferenceFoundryClientId` can be set only via an MDM profile, not via a bootstrap server. `inferenceFoundryAuthFlow` can be set via either.
<Note>
In-app sign-in and a [bootstrap server](/docs/third-party/claude-desktop/bootstrap) are separate layers that work together. In-app sign-in supplies each user's inference credential, the Entra ID token that authorizes model calls. A bootstrap server supplies per-user configuration values when the app starts. A bootstrap server does not replace sign-in: a deployment with a bootstrap server still needs each user to sign in, and signing in does not deliver configuration.
</Note>
#### Allow network egress
The sign-in flow reaches `login.microsoftonline.com` in addition to your Microsoft Foundry endpoint. Both hosts are included automatically in the **Egress** section of the in-app configuration window when these keys are set.
## Configure the app
Open the [in-app configuration window](/docs/third-party/claude-desktop/in-app-configuration#open-the-configuration-window) (**Developer → Configure Third-Party Inference…**). In the **Connection** section, set **Inference provider** to **Foundry**, then fill in the **Foundry credentials** card with the values for whichever authentication approach you chose:
| Field | API key | In-app Entra ID sign-in |
| ------------------------------ | ----------------------- | ---------------------------------------------------------------------- |
| Azure AI Foundry resource name | `your-foundry-resource` | `your-foundry-resource` |
| Azure AI Foundry API key | your resource key | *leave empty* |
| Entra ID tenant ID | *leave empty* | `00000000-0000-0000-0000-000000000000` |
| Entra ID client ID | *leave empty* | `11111111-1111-1111-1111-111111111111` |
| Entra ID sign-in flow | *leave empty* | `browser` or `broker`, or leave empty for the default device-code flow |
Under **Models**, add at least one **Model list** entry using the Microsoft Foundry deployment name.
Then click **Export** to produce a `.mobileconfig` (macOS) or `.reg` (Windows) file for your MDM. See [Deploy with MDM](/docs/third-party/claude-desktop/mdm) for the export and deployment workflow.
### Configuration keys
The full set of `inferenceFoundry*` keys is below. Set `inferenceProvider` to `foundry`, supply the resource name, and provide exactly one credential source.
| Setting | Type | Availability | Default | Description |
| ---------------------------------------------------------------------------------------------------- | -------- | --------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| <span id="inferencefoundryresource" />Azure AI Foundry resource name<br />`inferenceFoundryResource` | `string` | MDM + Bootstrap | — | Azure AI Foundry resource name used to construct the endpoint URL. |
| <span id="inferencefoundryapikey" />Azure AI Foundry API key<br />`inferenceFoundryApiKey` | `string` | MDM + Bootstrap | — | API key for Azure AI Foundry inference. |
| <span id="inferencefoundrytenantid" />Entra ID tenant ID<br />`inferenceFoundryTenantId` | `string` | MDM + Bootstrap | — | Directory (tenant) ID of the Entra ID app registration that has the Cognitive Services scope. |
| <span id="inferencefoundryclientid" />Entra ID client ID<br />`inferenceFoundryClientId` | `string` | MDM + Bootstrap | — | Application (client) ID of the Entra ID app registration. Device-code sign-in requires the app to allow public client flows. |
| <span id="inferencefoundryauthflow" />Entra ID sign-in flow<br />`inferenceFoundryAuthFlow` | `enum` | MDM + Bootstrap | — | How Entra sign-in runs: device code (default), system browser, or the OS identity broker. One of: `device-code`, `browser`, `broker`. |
<AccordionGroup>
<Accordion title="inferenceFoundryAuthFlow details">
* **`device-code`** (default) — shows a code to enter at microsoft.com/devicelogin. The app registration must have **Allow public client flows** enabled.
* **`browser`** — opens the system browser for an authorization-code (PKCE) sign-in on a loopback redirect URI. The app registration must include `http://127.0.0.1/callback` under the **Mobile and desktop applications** platform (Entra ignores the loopback port, but not the path). Works with **Allow public client flows** disabled, and is unaffected by Conditional Access policies that block device-code authentication.
* **`broker`** — signs in through the OS identity broker (Web Account Manager on Windows, Company Portal on macOS), so it can satisfy Conditional Access policies that require a compliant/managed device or token protection. The app registration must include the broker redirect URIs `ms-appx-web://Microsoft.AAD.BrokerPlugin/{client-id}` (Windows) and `msauth.com.anthropic.claudefordesktop://auth` (macOS) under the **Mobile and desktop applications** platform. Not supported on Linux.
App versions that predate this key always use device code; versions that predate the broker option treat `broker` as unset and use device code.
</Accordion>
</AccordionGroup>
You must also set `inferenceModels` to a list of Microsoft Foundry deployment names. See the [Configuration reference](/docs/third-party/claude-desktop/configuration#inferencemodels).
## What users experience
| Approach | First launch | Re-authentication |
| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| API key | The app opens directly; no user action. | Never, until you rotate the key in the managed profile. |
| In-app Entra ID sign-in, device-code flow | The app shows a **Sign in with Microsoft** page; the user approves a device code in the browser, and the app returns to Cowork. | When the stored refresh token expires or is revoked under your tenant's policy. The app prompts in-app. |
| In-app Entra ID sign-in, browser flow | The app shows a **Sign in with Microsoft** page; the user signs in through the system browser, with no code to enter, and the app returns to Cowork. | When the app can no longer renew the stored token. The app prompts in-app. |
| In-app Entra ID sign-in, broker flow | The app shows a **Sign in with Microsoft** page; the user picks or signs in to a work account in the operating system's native account picker, and the app returns to Cowork. | When the broker can no longer renew the token silently. The app prompts in-app. |
## Troubleshoot
To confirm which keys the app read and whether credentials validated, use **Help → Troubleshooting → Copy Managed Configuration Report**; see [Verifying the deployment](/docs/third-party/claude-desktop/installation#verifying-the-deployment) for that workflow and the common causes when the app does not enter 3P mode. Application log locations are listed in [Data storage and residency](/docs/third-party/claude-desktop/data-storage).
If sign-in fails at the token step, confirm the **Azure Cognitive Services** permission is granted and consented on the app registration. For the device-code flow, also confirm **Allow public client flows** is enabled; Entra ID rejects device-code sign-in without it.
If sign-in fails with error code `AADSTS650057`, the **user\_impersonation** permission is missing from the app registration. Add it under **API permissions**.
If sign-in fails with error code `AADSTS65001`, the permission has not been consented. Select **Grant admin consent** on the **API permissions** page, or have the user accept the consent prompt if your tenant allows user consent.
If browser-flow sign-in fails in the browser with error code `AADSTS50011`, the redirect URI is missing from the app registration or does not match. Add `http://127.0.0.1/callback` under **Authentication → Mobile and desktop applications**, using the literal address `127.0.0.1`, not `localhost`.
If the browser shows the confirmation page but in-app sign-in still fails, with error code `AADSTS7000218` in the application logs, the redirect URI is registered under the **Web** platform. Move it under **Mobile and desktop applications**.
For broker-flow sign-in failures (error codes `AADSTS50011`, `AADSTS900971`, `AADSTS7000218`, or a message that the OS identity broker is unavailable), see [Troubleshoot](/docs/third-party/claude-desktop/entra-broker#troubleshoot) on the OS identity broker page. To unblock a device that cannot meet the broker requirements, set `inferenceFoundryAuthFlow` to `browser` for that device instead.
Each sign-in attempt has a time limit: five minutes for the device-code and broker flows and two minutes for the browser flow. If the user does not finish within the limit, the attempt fails and the user can click **Sign in with Microsoft** to start again.
third-party/claude-desktop/gateway First recorded · 302 lines, first recorded
# Deploy Claude Desktop on 3P with an LLM gateway ## Choose an authentication approach ## Prepare devices ### Static API key ### Single sign-on with your identity provider #### Set up single sign-on #### Using Okta instead #### Map users at the gateway #### Refresh tokens and session lifetime ## Configure the app ### Configuration keys ### Single sign-on configuration keys ### Models ### MCP tool search ## Troubleshoot
The first capture of this source. The page was already there, and this is what it said.
# Deploy Claude Desktop on 3P with an LLM gateway
> Configure Claude Desktop on 3P to use Claude models on a self-hosted gateway that implements the Anthropic Messages API
To use a self-hosted LLM gateway (for example LiteLLM, Portkey, or an in-house proxy) as the inference provider, set `inferenceProvider` to `gateway` and supply the base URL and credentials described below.
The gateway must implement the Anthropic [Messages API](https://docs.claude.com/en/api/messages):
* `POST /v1/messages` with [streaming](https://docs.claude.com/en/api/streaming) and [tool use](https://docs.claude.com/en/docs/tool-use) is required.
* `GET /v1/models` is optional. If the gateway implements it, Claude Desktop on 3P auto-discovers available models; if not, set `inferenceModels` explicitly.
## Choose an authentication approach
| Scenario | Use | Notes |
| -------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| Proof of concept, or your gateway already issues per-team keys | [Static API key](#static-api-key) (`inferenceGatewayApiKey`) | A long-lived secret distributed in the managed profile. |
| Per-user attribution and identity-provider enforcement (MFA, conditional access) | [Single sign-on](#single-sign-on-with-your-identity-provider) (`inferenceGatewayOidc`) | Each user signs in with their own work account. Requires app version 1.6889.0 or later. |
| Your organization already has tooling that obtains a gateway credential | [Credential helper](/docs/third-party/claude-desktop/configuration#inferencecredentialhelper) (`inferenceCredentialHelper`) | An executable that prints the gateway credential to stdout at runtime. |
## Prepare devices
### Static API key
No per-device preparation is required. Generate an API key in your gateway and place it in the managed configuration as `inferenceGatewayApiKey` (see [Configure the app](#configure-the-app)).
### Single sign-on with your identity provider
Instead of distributing a shared gateway API key, you can have each user sign in with their own work account. The first time a user opens Claude Desktop, the app opens their browser to your organization's normal sign-in page (Microsoft Entra ID, Okta, or any OpenID Connect provider). After they sign in, the app sends a per-user token to your gateway on every request, and your gateway checks that token to confirm who the user is.
This gives you per-user attribution in your gateway logs, lets your identity provider enforce MFA and conditional access, and means there is no long-lived credential to distribute or rotate.
You need three things in place:
* An LLM gateway that can validate JSON Web Tokens (LiteLLM, Kong, Envoy, and Azure API Management all support this)
* Admin access to your identity provider to register a new application
* A way to push managed configuration to user devices (your existing MDM)
The walkthrough below uses Microsoft Entra ID. An Okta variant follows.
#### Set up single sign-on
<Steps>
<Step title="Register an application in Entra ID">
In the [Microsoft Entra admin center](https://entra.microsoft.com), go to **Identity → Applications → App registrations** and select **New registration**. Give it a name such as `Claude Desktop gateway`, choose **Accounts in this organizational directory only**, and select **Register**.
On the overview page, copy the **Application (client) ID** and **Directory (tenant) ID**. You will use both in the next two steps.
Open the **Authentication** blade, select **Add a platform**, and choose **Mobile and desktop applications**. Under **Custom redirect URIs**, add exactly:
```text theme={null}
http://127.0.0.1/callback
```
A few details that matter here: use `127.0.0.1` (not `localhost`), include the `/callback` path, and add it under the **Mobile and desktop applications** platform specifically. That platform is the only one Entra allows to use any local port, which the app needs because it picks a free port at sign-in time. You do not need a client secret or any additional API permissions.
</Step>
<Step title="Configure your gateway to validate the token">
Tell your gateway to accept the bearer token only if it was issued by your tenant **for this application**. In LiteLLM that looks like:
```yaml theme={null}
general_settings:
litellm_jwtauth:
public_key_url: https://login.microsoftonline.com/YOUR_TENANT_ID/discovery/v2.0/keys
audience: YOUR_CLIENT_ID
user_id_jwt_field: oid
```
Replace `YOUR_TENANT_ID` and `YOUR_CLIENT_ID` with the values from step 1.
<Warning>
The `audience` line is required. Without it, your gateway accepts tokens issued to any application in your tenant, not just this one.
</Warning>
For Kong, Envoy, or Azure API Management, configure the equivalent JWT validation policy with the same JWKS URL and audience.
</Step>
<Step title="Configure in the app">
Open the [in-app configuration window](/docs/third-party/claude-desktop/in-app-configuration#open-the-configuration-window) (**Developer → Configure Third-Party Inference…**). In the **Connection** section, set **Inference provider** to **Gateway** and **Credential kind** to **Interactive sign-in**. This hides the API-key field and reveals **Gateway SSO IdP (OIDC)**:
| Field | Value |
| -------------------------------------- | ------------------------------------------------------- |
| Gateway base URL | `https://llm-gateway.example.corp` |
| Credential kind | **Interactive sign-in** |
| Gateway SSO IdP (OIDC) → Client ID | `YOUR_CLIENT_ID` |
| Gateway SSO IdP (OIDC) → Issuer URL | `https://login.microsoftonline.com/YOUR_TENANT_ID/v2.0` |
| Gateway SSO IdP (OIDC) → Scopes | *leave empty for the default* |
| Gateway SSO IdP (OIDC) → Redirect port | *leave empty* |
Then click **Export** to produce a `.mobileconfig` (macOS) or `.reg` (Windows) file for your MDM. See [Deploy with MDM](/docs/third-party/claude-desktop/mdm) for the export and deployment workflow.
When 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.
</Step>
</Steps>
#### Using Okta instead
In the Okta Admin Console, create a **Native** application with the **Authorization Code** and **Refresh Token** grant types. Okta requires the redirect URI to match exactly, including the port, so pick a fixed port (for example `53180`), register `http://127.0.0.1:53180/callback`, and set that same port in **Gateway SSO IdP (OIDC)**:
| Field | Value |
| ------------- | ----------------------------- |
| Client ID | `YOUR_CLIENT_ID` |
| Issuer URL | `https://YOUR_ORG.okta.com` |
| Scopes | *leave empty for the default* |
| Redirect port | `53180` |
<Note>
Use the **issuer** value, not the **Metadata URI**. Okta's admin console shows the metadata URI (ending in `/.well-known/openid-configuration`) prominently — that is the discovery document the app fetches *from* the issuer, not the issuer itself. If you are unsure, open the metadata URI in a browser and copy the `"issuer"` field from the JSON response. For a custom Okta authorization server the issuer is `https://YOUR_ORG.okta.com/oauth2/AUTH_SERVER_ID`.
</Note>
Point your gateway's JWT validation at `https://YOUR_ORG.okta.com/oauth2/v1/keys` with `audience` set to the Okta client ID.
#### Map users at the gateway
Claude Desktop forwards the identity provider's token to your gateway verbatim — it does not add, remove, or rewrite any claims. With the default scopes (`openid profile email offline_access`), the ID token your gateway receives contains the standard OIDC `sub`, `email`, and `name` claims, plus whatever your provider includes for the `profile` scope. You can confirm exactly what is present by base64-decoding the middle segment of the `Authorization: Bearer` value your gateway receives.
Key the gateway's user record on the provider's immutable user ID rather than email, so the record survives email or name changes:
| Provider | Stable user-ID claim |
| ---------------------------------- | -------------------- |
| Entra ID | `oid` |
| Okta and most other OIDC providers | `sub` |
If your gateway has no existing user records to preserve, the simplest setup is to auto-provision on first sign-in. For LiteLLM, extend the validation block from step 2:
```yaml theme={null}
general_settings:
enable_jwt_auth: true
litellm_jwtauth:
public_key_url: https://YOUR_ORG.okta.com/oauth2/v1/keys
audience: YOUR_CLIENT_ID
user_id_jwt_field: sub # use "oid" for Entra ID
user_email_jwt_field: email
user_id_upsert: true
```
If you need additional claims (for example, a `groups` claim for team-level budgets), add them on your identity provider's authorization server — they pass through to the gateway unchanged. To request a non-default scope, set `scopes` in `inferenceGatewayOidc` (see [Single sign-on configuration keys](#single-sign-on-configuration-keys)).
#### Refresh tokens and session lifetime
Silent token refresh requires a refresh token from your identity provider, which in turn requires the `offline_access` scope on the authorization request. Whether Claude Desktop sends that scope depends on how you set `scopes` and `bearerTokenType`:
* **`scopes` left unset** — the default (`openid profile email offline_access`) includes `offline_access`, so a refresh token is issued.
* **`bearerTokenType: "access_token"`** — Claude Desktop automatically appends `offline_access` to whatever `scopes` value you supply, unless `appendOfflineAccess` is set to `false`.
* **`bearerTokenType: "id_token"` (the default) with `scopes` set explicitly** — Claude Desktop does **not** add `offline_access` for you. Include it in your `scopes` value if you want silent refresh; without it, users are prompted to sign in again each time the ID token expires (commonly about one hour).
Per [OpenID Connect Core 1.0 §11](https://openid.net/specs/openid-connect-core-1_0.html#OfflineAccess), requesting `offline_access` signals that the client may use the refresh token while the user is not present, and the provider must obtain consent for it. Claude Desktop therefore does not add this scope to an administrator-supplied `scopes` value in the default mode, so that requesting offline access remains an explicit choice.
**Authorization servers that reject `offline_access`.** Standard OIDC providers (Entra ID, Okta, Auth0) accept `offline_access` and require it to issue a refresh token, so the automatic append is what you want. If your authorization server instead rejects unrecognized scopes with an `invalid_scope` error — for example, servers that issue refresh tokens via a provider-specific scope rather than `offline_access` — set `appendOfflineAccess` to `false` and include your provider's own refresh-token scope in `scopes` directly.
Refresh tokens govern whether users are re-prompted to sign in, not how long a sign-in may stay valid. To cap the sign-in lifetime under your identity provider's session policy, set [`inferenceSessionLifetimeSec`](/docs/third-party/claude-desktop/configuration#inferencesessionlifetimesec); Claude Desktop shows a re-authenticate banner before the session expires.
## Configure the app
Open the [in-app configuration window](/docs/third-party/claude-desktop/in-app-configuration#open-the-configuration-window) (**Developer → Configure Third-Party Inference…**). In the **Connection** section, set **Inference provider** to **Gateway**, then fill in the **Gateway credentials** card:
| Field | Value |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| Gateway base URL | `https://llm-gateway.example.corp` |
| Gateway API key | your gateway key (or a placeholder if your gateway has none) |
| Credential kind | **Static API key** (default), or **Interactive sign-in** for [single sign-on](#single-sign-on-with-your-identity-provider) |
| Gateway auth scheme | **Bearer** (default) or **x-api-key** |
Then click **Export** to produce a `.mobileconfig` (macOS) or `.reg` (Windows) file for your MDM. See [Deploy with MDM](/docs/third-party/claude-desktop/mdm) for the export and deployment workflow.
### Configuration keys
| Setting | Type | Availability | Default | Description |
| -------------------------------------------------------------------------------------------------- | -------- | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| <span id="inferencegatewaybaseurl" />Gateway base URL<br />`inferenceGatewayBaseUrl` | `string` | MDM + Bootstrap | — | Full URL of the inference gateway endpoint. |
| <span id="inferencegatewayapikey" />Gateway API key<br />`inferenceGatewayApiKey` | `string` | MDM + Bootstrap | — | API key for the configured inference gateway. |
| <span id="inferencegatewayauthscheme" />Gateway auth scheme<br />`inferenceGatewayAuthScheme` | `enum` | MDM + Bootstrap | `bearer` | How the gateway credential is sent on the wire (Authorization: Bearer vs x-api-key header). One of: `bearer`, `x-api-key`. Defaults to `bearer`. |
| <span id="inferencegatewayoidcauthflow" />Gateway sign-in flow<br />`inferenceGatewayOidcAuthFlow` | `enum` | MDM + Bootstrap | — | How the IdP sign-in runs: system browser (default) or the OS Microsoft Entra broker. One of: `browser`, `broker`. |
| <span id="inferencegatewayoidc" />Gateway SSO IdP (OIDC)<br />`inferenceGatewayOidc` | `object` | MDM + Bootstrap | — | External IdP for gateway sign-in. The user’s token from this issuer is sent to the gateway as the Bearer credential. |
<AccordionGroup>
<Accordion title="inferenceGatewayOidcAuthFlow details">
* **`browser`** (default) — opens the system browser for an authorization-code (PKCE) sign-in on a loopback redirect URI. See the **IdP setup** notes on `inferenceGatewayOidc` for redirect-URI registration.
* **`broker`** — signs in through the OS identity broker (Web Account Manager on Windows, Company Portal on macOS). Requires the IdP to be **Microsoft Entra ID** — the `issuer` on `inferenceGatewayOidc` must be `https://login.microsoftonline.com/{tenant-id}/v2.0`. The broker satisfies Conditional Access policies that require a compliant/managed device or token protection, and needs no `127.0.0.1/callback` loopback redirect. The Entra app registration must include the broker redirect URIs `ms-appx-web://Microsoft.AAD.BrokerPlugin/{client-id}` (Windows) and `msauth.com.anthropic.claudefordesktop://auth` (macOS) under the **Mobile and desktop applications** platform. Not supported on Linux.
Broker mode mints a token in the customer's own Entra tenant with the customer-configured `scopes`, and forwards it to the customer's own gateway; both endpoints of that trust relationship are inside the customer's control.
</Accordion>
<Accordion title="inferenceGatewayOidc details">
**External IdP mode.** The app discovers `<issuer>/.well-known/openid-configuration`, runs an OIDC authorization-code-with-PKCE flow in the system browser with `clientId`, and sends the resulting token as `Authorization: Bearer` on every inference request — see **Bearer token type** below for how the gateway validates it.
**Bearer token type.** `id_token` (the default) sends the OIDC ID token — the gateway validates signature + `iss` + `aud`, where `aud` is the `clientId` configured here. `access_token` sends the OAuth access token — the gateway validates as an OAuth resource server against the audience/scope the IdP issued the token for; set `scopes` to the gateway's registered API scope (required in this mode). Use `access_token` for gateways that expect a resource-server token (Portkey, Kong, Envoy JWT filter, AWS API Gateway authorizers).
**The gateway MUST validate `iss` AND `aud`, not just the signature.** Signature + issuer alone accepts *any* token from the same tenant, including tokens issued to unrelated apps. In `id_token` mode the audience is the `clientId`:
```yaml theme={null}
# LiteLLM example — `audience` is REQUIRED, not optional
general_settings:
litellm_jwtauth:
public_key_url: https://login.microsoftonline.com/<tenant>/discovery/v2.0/keys
audience: <clientId> # ⚠ omitting this accepts any token from the tenant
```
**IdP setup.** The app's loopback callback binds `http://127.0.0.1:<port>/callback` (RFC 8252 §7.3). Register `127.0.0.1`; most IdPs do **not** treat `localhost` and `127.0.0.1` as interchangeable. **Entra:** register a public-client app, add a *Mobile and desktop applications* redirect URI of `http://127.0.0.1/callback`. (Microsoft's docs say the path is wildcarded for loopback; in practice it is not: `http://127.0.0.1` without `/callback` fails with `AADSTS50011`. The port IS wildcarded.) Grant `openid profile email offline_access` (delegated, no admin consent); in `access_token` mode **also** add the gateway API's delegated permission under *API permissions* (and ensure the gateway's own app registration exposes that scope via *Expose an API*) — without it Entra rejects the sign-in with `AADSTS65001`. **Okta:** register a *Native* app with the exact redirect URI `http://127.0.0.1:<port>/callback` and set `redirectPort` here to that port (Okta requires an exact match).
**Refresh:** `offline_access` returns a refresh token; the app refreshes the bearer silently before expiry. When refresh fails (revoked, idle past the IdP's window), the user re-authenticates in the browser. **Google Workspace caveat (`id_token` mode only):** Google never returns `id_token` on a refresh-token grant, so a Google-backed gateway in `id_token` mode will prompt a browser sign-in roughly once per ID-token TTL (\~1h). Entra and Okta return a fresh `id_token` and are unaffected; `access_token` mode is unaffected on all IdPs.
**Leave this unset** for a gateway that hosts its own RFC 8414 metadata at `<baseUrl>/.well-known/oauth-authorization-server` (the original gateway-as-AS path).
| Field | Type | Default | Description |
| --------------------------------- | --------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `clientId` | `string` | — | OAuth client ID of the desktop app registration at your identity provider (public client, PKCE). |
| `issuer` | `string` | — | HTTPS issuer with OIDC discovery. Set this, or set the authorization and token URLs instead. |
| `authorizationUrl` | `string` | — | HTTPS authorization endpoint. Used with the token URL when no issuer is set. |
| `tokenUrl` | `string` | — | HTTPS token endpoint. Used with the authorization URL when no issuer is set. |
| `bearerTokenType` | `enum` | `id_token` | Which token to send as the gateway bearer. Use access token for gateways that validate as an OAuth resource server. One of: `id_token`, `access_token`. |
| `scopes` | `string` | — | Space-separated scopes. Required in access-token mode: set the gateway’s API scope. offline\_access is appended automatically unless disabled below. |
| `appendOfflineAccess` | `boolean` | `true` | Automatically append offline\_access to scopes so the IdP returns a refresh token for silent refresh. |
| `resource` | `string` | — | Absolute URL identifying the gateway as the access-token audience. Sent as the RFC 8707 resource parameter when set; leave unset for Microsoft Entra ID. |
| `redirectPort` | `integer` | — | Fixed loopback port for the sign-in redirect ([http://127.0.0.1:PORT/callback](http://127.0.0.1:PORT/callback)). Leave unset to use a free port each time. |
| `additionalRedirectReferrerHosts` | `string` | — | Space-separated hostnames also accepted as the referrer of the sign-in callback. Only needed when the IdP completes sign-in from a different host. |
</Accordion>
</AccordionGroup>
To send additional HTTP headers on every inference request (tenant routing, org IDs, and similar), set [`inferenceCustomHeaders`](/docs/third-party/claude-desktop/configuration#inferencecustomheaders). It applies to all providers, not just gateways.
### Single sign-on configuration keys
Single sign-on is enabled by setting `inferenceCredentialKind` to `interactive` **and** supplying `inferenceGatewayOidc`. Both are required — `interactive` alone (without `inferenceGatewayOidc`) selects a different mode where the gateway itself acts as the authorization server.
| Setting | MDM key | Required | Description |
| ---------------------- | ------------------------- | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| Credential kind | `inferenceCredentialKind` | Yes — must be `interactive` | Selects sign-in instead of an API key. |
| Gateway SSO IdP (OIDC) | `inferenceGatewayOidc` | Yes | A **single JSON object** describing the identity provider (fields below). The resulting token is sent to the gateway as the bearer credential. |
The `inferenceGatewayOidc` value is one JSON object with these fields:
| Field | Required | Description |
| --------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `clientId` | Yes | Application (client) ID registered with the identity provider. |
| `issuer` | Yes\* | OIDC issuer URL — the base URL only, **without** `/.well-known/openid-configuration`. The app appends that path itself to discover the authorization and token endpoints. |
| `authorizationUrl` | No\* | Explicit OIDC authorization endpoint. Use together with `tokenUrl` instead of `issuer` when the identity provider does not serve `/.well-known/openid-configuration`. Ignored when `issuer` is set. |
| `tokenUrl` | No\* | Explicit OIDC token endpoint. Must be set together with `authorizationUrl`. Ignored when `issuer` is set. |
| `scopes` | No | Space-separated OIDC scopes. Defaults to `openid profile email offline_access`. Required when `bearerTokenType` is `access_token`. See [Refresh tokens and session lifetime](#refresh-tokens-and-session-lifetime) for how this field interacts with silent refresh. |
| `redirectPort` | No | Fixed local port for the loopback redirect. Leave unset to let the app choose an ephemeral port (Entra). Set when the provider requires an exact port match (Okta). |
| `bearerTokenType` | No | Which token the app sends to the gateway as the `Authorization: Bearer` value. `id_token` (the default) sends the OIDC ID token — the gateway validates it offline against the provider's JWKS with `aud` equal to the client ID. `access_token` sends the OAuth access token instead — use this for gateways that validate as an OAuth resource server rather than validating the ID token directly. When set to `access_token`, `scopes` is required. |
| `appendOfflineAccess` | No | Whether to automatically append `offline_access` to `scopes` in `access_token` mode. Defaults to `true`. Set to `false` only if your authorization server rejects `offline_access` as an unrecognized scope. See [Refresh tokens and session lifetime](#refresh-tokens-and-session-lifetime). |
\* Either `issuer`, or both `authorizationUrl` and `tokenUrl`, is required.
<Warning>
`inferenceGatewayOidc` is **one MDM key whose value is a JSON string** — not separate keys like `inferenceGatewayOidc.clientId`. See [how object-typed keys are encoded](/docs/third-party/claude-desktop/configuration#value-types). The in-app **Export** produces the correct format automatically.
</Warning>
In a macOS `.mobileconfig` payload (Okta example):
```xml theme={null}
<key>inferenceCredentialKind</key>
<string>interactive</string>
<key>inferenceGatewayOidc</key>
<string>{"issuer":"https://YOUR_ORG.okta.com","clientId":"YOUR_CLIENT_ID","redirectPort":53180}</string>
```
Earlier app versions used `inferenceGatewayAuthScheme: "sso"` to select this mode. That value is deprecated; set `inferenceCredentialKind: "interactive"` instead. Existing deployments that still send `inferenceGatewayAuthScheme: "sso"` continue to work.
### Models
When `inferenceModels` is unset, Claude Desktop on 3P populates the model picker from your gateway's `GET /v1/models` response. Auto-discovery shows only models whose IDs are recognizably Claude; if your gateway advertises models under opaque aliases, set `inferenceModels` explicitly. Set [`inferenceModels`](/docs/third-party/claude-desktop/configuration#models) to override discovery with an explicit list — the picker will show exactly the entries you provide. Use the model IDs your gateway expects (for example `bedrock/us.anthropic.claude-opus-5` for a LiteLLM-style routing prefix).
If your gateway serves a Claude model under an opaque routing alias, it can mark the model as Claude by returning an `anthropic_family_tier` field (a Claude tier name such as `sonnet` or `opus`) on that model object in its `/v1/models` response, optionally with `is_family_default: true` when several models map to the same tier. Models marked this way pass the auto-discovery filter.
If your gateway does not implement `GET /v1/models`, give every `inferenceModels` entry the full model ID your gateway accepts; bare tier aliases such as `sonnet` rely on discovery to resolve. When every entry is a full model ID, the app skips the `/v1/models` call automatically. A list that contains a bare alias keeps discovery on, so for a gateway without the endpoint, replace the alias with the full model ID; a bare alias cannot be resolved without discovery. On earlier app versions that do not skip the call automatically, also set [`modelDiscoveryEnabled`](/docs/third-party/claude-desktop/configuration#modeldiscoveryenabled) to `false` to avoid the discovery attempt. The cost of leaving discovery on without the endpoint depends on how the gateway fails: an error response makes the app fall back to the `inferenceModels` list immediately, while an endpoint that accepts the request and hangs delays the model list by up to 10 seconds at launch.
If your deployment supports the 1M-token context window for a model, set `supports1m: true` on that model's entry:
```json theme={null}
[{"name": "bedrock/us.anthropic.claude-opus-5", "supports1m": true}]
```
The model picker then shows a second entry for the model, described as **1M context window**; the standard entry has no context-size label, and the default selection is unchanged. `supports1m` is an assertion about your gateway rather than something the app can verify: if the gateway does not accept 1M-token requests for that model, requests made from the 1M picker entry fail at inference time. Only set it on models you have confirmed against your deployment. The [Models section of the configuration reference](/docs/third-party/claude-desktop/configuration#models) documents the remaining entry fields, including display labels and tier mapping.
### MCP tool search
[MCP tool search](https://code.claude.com/docs/en/mcp#scale-with-mcp-tool-search) loads MCP tool schemas on demand instead of inlining every schema into the context window. It reduces context pressure when many MCP tools are configured (sessions that otherwise compact every turn or two). Claude Desktop on 3P turns it off by default, along with Claude Code's other experimental beta features, because strict gateways reject the experimental `anthropic-beta` request headers and request fields those features add. This suppression takes precedence over the `ENABLE_TOOL_SEARCH` environment variable, so setting that variable has no effect on Claude Desktop sessions. The variable applies only to terminal Claude Code running outside Claude Desktop.
To turn tool search on for Claude Desktop, set the [`toolSearchEnabled`](/docs/third-party/claude-desktop/configuration#toolsearchenabled) configuration key. Requires app version 1.21459.0 or later.
<Warning>
Setting `toolSearchEnabled` causes sessions to send experimental `anthropic-beta` request headers, and the beta request fields that ride with them, to your gateway. Enable it only if your gateway forwards and accepts those headers and fields; when it does not, requests fail with HTTP 400. LiteLLM in passthrough mode and Cloudflare AI Gateway both forward `anthropic-beta` headers and `tool_reference` content blocks. As a preflight, run terminal Claude Code through the same gateway with `ENABLE_TOOL_SEARCH=true`: Claude Desktop sends the same request surface, so if the terminal works, Claude Desktop will too. Enabling the key also re-enables Claude Code's other experimental beta features for these sessions. Do not enable it on [Vertex](/docs/third-party/claude-desktop/vertex) deployments: Vertex rejects the tool-search beta header.
</Warning>
## Troubleshoot
**`gateway SSO: server does not advertise device_authorization_endpoint`** — The app could not read your `inferenceGatewayOidc` value, so it fell back to treating the gateway itself as the sign-in server. Almost always this means the value is not a valid JSON string (for example, separate dotted keys, or a plist `<dict>` instead of a `<string>`). Re-export from the in-app configuration window, or copy the `.mobileconfig` snippet above.
**`OIDC discovery failed (HTTP 404)` or `(HTTP 405)`** — The `issuer` value is not the issuer base URL. Most often the metadata URI (ending in `/.well-known/openid-configuration`) was pasted instead, which doubles the path. Remove that suffix so `issuer` is just `https://YOUR_ORG.okta.com` (or the equivalent for your provider).
**`no credential configured for provider "gateway": set inferenceCredentialKind or one of the credential fields`** — `inferenceCredentialKind: "interactive"` is not present in the pushed configuration.
**Browser shows "Connected" but the app reports the sign-in failed, or `Token exchange failed (HTTP 401)`** — The browser step succeeded, but the identity provider rejected the follow-up token request. This usually means the IdP application is registered as a confidential (Web) client, which expects a client secret. Claude is a public PKCE client and doesn't send one. Register a public/native client instead: **Native Application** in Okta, or the **Mobile and desktop applications** platform in Entra ID. Application type generally can't be changed after creation, so you may need to create a new one.
<Note>
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.
</Note>
**Model picker is empty or missing models.** Auto-discovery filters out model IDs that are not recognizably Claude, so models your gateway serves under opaque aliases appear only if the gateway marks them with `anthropic_family_tier` in its `/v1/models` response or you list them in `inferenceModels` (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.
Cut at 300 lines. The page has the rest.
third-party/claude-desktop/in-app-configuration First recorded · 34 lines, first recorded
# In-app configuration ## Open the configuration window ## Apply locally or export for a fleet
The first capture of this source. The page was already there, and this is what it said.
# In-app configuration > Build, test, and export a Claude Desktop on 3P configuration from inside the app, with validation and per-provider guidance The in-app configuration window is the recommended way to configure Claude Desktop for third-party inference. It validates values as you enter them, shows exactly which fields your inference provider requires, tests the connection against your endpoint, and computes the network egress allowlist for your settings, so you don't have to hand-edit JSON, plists, or registry keys. ## Open the configuration window From the macOS menu bar (or on Windows, the application menu ☰ in the top-left of the sign-in screen), go to **Help → Troubleshooting → Enable Developer Mode**, then **Developer → Configure Third-Party Inference…**. <Frame caption="The in-app configuration window, showing the Connection section for a gateway provider."> <img src="https://mintcdn.com/claude-ai/kVj7_7KF4fI3bEAn/images/third-party/in-app-configuration-window.png?fit=max&auto=format&n=kVj7_7KF4fI3bEAn&q=85&s=c3f15a85dea85082bc6dbc9459e6a974" alt="Claude Desktop in-app configuration window with the sidebar of setting groups on the left and the Connection form on the right." width="1812" height="1462" data-path="images/third-party/in-app-configuration-window.png" /> </Frame> The sidebar groups settings the same way the [configuration reference](/docs/third-party/claude-desktop/configuration) does. Fill in **Connection** first, then work down through the sections your deployment needs. ## Apply locally or export for a fleet Use **Apply locally** to write the configuration to this device only and relaunch into it. This is the [single-machine setup](/docs/third-party/claude-desktop/installation#single-machine-setup) path for evaluation and pilots. Use the **Export** menu to generate deployment artifacts for a fleet: | Export option | Use with | | --------------------------- | --------------------------------------------------------------------------------------------------- | | `.mobileconfig` profile | Jamf or any macOS MDM | | `.reg` policy file | Intune, Group Policy, or any Windows MDM | | ADMX template (`.zip`) | Intune or Group Policy; a schema-only template, you enter values in the management console | | Profile Manifest (`.plist`) | Jamf, ProfileCreator, or similar macOS tools; a schema-only template, you enter values in your tool | | Bootstrap JSON | The response body for a [bootstrap server](/docs/third-party/claude-desktop/bootstrap) | | Egress allowlist | Your firewall or network team | See [Deploy with MDM](/docs/third-party/claude-desktop/mdm) or [Deploy with a bootstrap server](/docs/third-party/claude-desktop/bootstrap) to distribute what you exported. When a managed profile is already present on the device, the window opens in read-only mode and shows the deployed values. Author new configurations from a device without a managed profile.
third-party/claude-desktop/installation First recorded · 162 lines, first recorded
# Installation and setup ## System requirements ## Check device readiness ## Install the app ## Choose a configuration delivery model ## Single-machine setup ## Verifying the deployment ## Troubleshooting ## Endpoint security software ## Offline installation ## Updates
The first capture of this source. The page was already there, and this is what it said.
# Installation and setup > Install Claude Desktop on 3P, check device readiness, and choose how configuration reaches your devices: an MDM profile or a bootstrap server Claude Desktop on third-party (3P) is the standard Claude Desktop application plus a managed configuration that activates third-party inference mode. Setup is two pieces: install the regular Claude Desktop app, and deliver the configuration to it. ## System requirements Cowork, the agent workspace at the center of Claude Desktop on 3P, has the following device requirements: | Requirement | macOS | Windows | | ---------------- | ---------------------------- | -------------------------------------------------------------------- | | Operating system | macOS 14 (Sonoma) or later | Windows 10 build 19041 (version 2004) or later, including Windows 11 | | CPU architecture | Apple silicon or Intel (x64) | x64 or Arm64 | | Installer | `.dmg` | `.msix` | On Windows, Cowork requires the `.msix` package: fleets provisioned with the legacy `.exe` installer get Claude Desktop without Cowork, and migrating them to `.msix` enables it. Cowork also requires working hardware virtualization, which the [readiness check](#check-device-readiness) verifies along with the requirements above. ## Check device readiness Before installing Claude Desktop, you can confirm that a device supports Cowork by running the readiness check: a small standalone program that requires no installation or sign-in. | Platform | Download | | ------------- | ---------------------------------------------------------------------------------------------------------------------------- | | macOS | [Cowork readiness check for macOS](https://claude.ai/api/desktop/darwin/universal/cowork-readiness-check/latest/redirect) | | Windows (Arm) | [Cowork readiness check for Windows arm64](https://claude.ai/api/desktop/win32/arm64/cowork-readiness-check/latest/redirect) | | Windows (x64) | [Cowork readiness check for Windows x64](https://claude.ai/api/desktop/win32/x64/cowork-readiness-check/latest/redirect) | Open the downloaded program to run the check. A ready device reports **This computer is ready for Cowork**. For fleet deployments, run the check on one device of each hardware model in your fleet before the broad rollout to identify unsupported models early. ## Install the app Download the installer for your platform from [claude.com/download](https://claude.com/download). | Platform | Installer | Notes | | -------- | --------- | ----------------------------------------------------------- | | macOS | `.dmg` | Drag **Claude.app** to Applications | | Windows | `.msix` | Supports per-machine provisioning for enterprise deployment | For fleet rollouts, distribute the installer through your standard software-distribution mechanism after the configuration reaches devices; [Choose a configuration delivery model](#choose-a-configuration-delivery-model) covers how the configuration gets there. ## Choose a configuration delivery model Configuration reaches devices in one of two ways. Both typically use your MDM tooling to push a profile; the difference is what the profile contains. | | MDM profile | Bootstrap server | | -------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | | What you deploy to devices | The full configuration, exported as a `.mobileconfig` or `.reg` profile | A minimal profile containing only the bootstrap keys (`bootstrapUrl`, optionally `bootstrapOidc`) | | Where settings live | In the profile, identical for every device the profile targets | On an HTTPS endpoint you operate, which returns each user's configuration at sign-in | | Per-user values | Separate profiles per device group | The server keys its response to the signed-in user | | Changing settings | Export and push an updated profile | Change your server's response; devices pick it up at the next fetch, with no profile push | Choose an MDM profile when one configuration, or a few group-scoped profiles, covers your fleet. Most MDMs support role-based distribution, so per-group configuration doesn't require a bootstrap server. Building the configuration in the app is optional. The [in-app configuration window](/docs/third-party/claude-desktop/in-app-configuration) can also export schema-only templates (an ADMX template for Windows, a Profile Manifest `.plist` for macOS) from its **Export** menu, so you can enter values directly in your management console instead. See [Export the profile](/docs/third-party/claude-desktop/mdm#2-export-the-profile) for all formats. Choose a bootstrap server when your organization doesn't use MDM, or when per-user credentials or frequently changing settings would make per-group profiles unwieldy. The tradeoff is that you operate the endpoint. The two models don't combine: when a bootstrap response is in effect, it replaces MDM-delivered values wholesale, and a few device-level keys are only available via MDM (see the Availability column in the [configuration reference](/docs/third-party/claude-desktop/configuration)). Pick your path: * [Deploy with MDM](/docs/third-party/claude-desktop/mdm) covers authoring the configuration in the app, exporting the profile, and deploying it to your fleet. * [Deploy with a bootstrap server](/docs/third-party/claude-desktop/bootstrap) covers getting the bootstrap keys onto devices and running the server. On either path, deploy the configuration before the app so users open Claude for the first time and land directly in the third-party deployment. ## Single-machine setup For evaluating before a fleet rollout, for pilots, or for organizations that don't use MDM, a single machine can be configured directly in the app. 1. Install Claude Desktop from [claude.com/download](https://claude.com/download). 2. Launch the app. **Do not sign in or create an Anthropic account.** From the macOS menu bar (or on Windows, the application menu ☰ in the top-left of the login screen), go to **Help → Troubleshooting → Enable Developer Mode**, then **Developer → Configure Third-Party Inference…** to open the [in-app configuration window](/docs/third-party/claude-desktop/in-app-configuration). 3. Enter the provider, endpoint, and credential values supplied by your administrator. 4. Click **Apply locally**. The app relaunches and the sign-in screen now offers the option to start in Claude Desktop on 3P using the configuration you entered. The configuration is written to the application's local config file and applies only to that device and user account. It can be edited from the same window at any time. To return to standard Claude Desktop, choose the Anthropic sign-in option on the sign-in screen instead. If your organization runs a [bootstrap server](/docs/third-party/claude-desktop/bootstrap) but doesn't use MDM, your administrator can instead supply a small configuration file containing only the bootstrap keys. Load it with **Import configuration** in the same window; the bootstrap server supplies everything else after you sign in. When the configuration works on a single machine, roll it out to the fleet with the [delivery model you chose](#choose-a-configuration-delivery-model); on the MDM path, you can export the tested configuration as the profile you deploy. ## Verifying the deployment On any configured device, open Claude Desktop and go to **Help → Troubleshooting → Copy Managed Configuration Report**. This copies a summary showing which keys were detected, where they were read from (managed profile vs. user store), and whether the inference credentials validated successfully. Secret values are redacted. Also confirm that the [in-app configuration window](/docs/third-party/claude-desktop/in-app-configuration) (**Developer → Configure Third-Party Inference…**) opens read-only on a managed device. The app reads managed keys from the profile by name and silently ignores a misspelled key rather than reporting an error. On macOS, a window that is still editable means no recognized key reached the app, even if your MDM shows the profile as delivered. On Windows, even a misspelled value under `HKLM\SOFTWARE\Policies\Claude` counts as machine policy and locks the window, so use the Managed Configuration Report to see which keys were actually read. If your profile deliberately sets [only the update keys](/docs/third-party/claude-desktop/mdm#update-keys-and-managed-precedence), an editable window is expected. If the app shows the standard claude.ai sign-in screen instead of Cowork, the configuration was not read. Common causes: * `inferenceProvider` is missing, misspelled, or set to an unrecognized value * The configuration was applied while the app was running (fully quit and relaunch) * The configuration was written to the local config file but you're checking the managed location (or vice versa) * A required key for the chosen provider is missing; check **Help → Troubleshooting** or the application log at `~/Library/Logs/Claude-3p/main.log` (macOS) / `%LOCALAPPDATA%\Claude-3p\Logs\main.log` (Windows) * On Windows (v1.19367.0 and later), the configuration is in `HKCU\SOFTWARE\Policies\Claude` but machine policy is also present: any `REG_SZ`, `REG_EXPAND_SZ`, or `REG_DWORD` value directly under `HKLM\SOFTWARE\Policies\Claude` causes the app to ignore user policy entirely. The Managed Configuration Report (**Help → Troubleshooting → Copy Managed Configuration Report**) shows which source the app read. A `REG_EXPAND_SZ` value shows as present in `reg query` output while the app reports the managed configuration as invalid or absent, because the app counts the value as machine policy but cannot read its contents ## Troubleshooting If installation or setup fails, generate a diagnostic report before requesting support: on the affected machine, go to **Help → Troubleshooting → Generate Diagnostic Report**, choose a save location, and send the resulting folder to your Anthropic representative. The report contains the configuration state, application logs, and environment details needed to investigate. It does not include user data or conversation content. ## Endpoint security software 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 Cowork agent helper may be blocked from launching. The symptom is that Claude Desktop opens normally and reads the managed configuration, but Cowork sessions fail to start. The agent helper is a signed binary that Claude Desktop installs under its user-data directory. **Allowlist by signing identity rather than path** so the rule survives version updates. **macOS** ``` ~/Library/Application Support/Claude-3p/claude-code/<version>/claude.app/Contents/MacOS/claude ``` The helper is Developer ID signed and notarized: * Team ID: `Q6L2SF6YDW` (Anthropic PBC) * Signing ID: `com.anthropic.claude-code` For Santa, a `TEAMID` allow rule for `Q6L2SF6YDW` covers the helper across version updates. Standard (non-3P) installs use `~/Library/Application Support/Claude/` with the same subpath. **Windows** ``` %LOCALAPPDATA%\Claude-3p\claude-code\<version>\claude.exe ``` The helper is Authenticode-signed with publisher `Anthropic, PBC`. For Defender ASR or AppLocker, allowlist by publisher rather than path. Standard installs use `%APPDATA%\Claude\` with the same subpath. ## Offline installation Standard installs fetch two large runtime components from `downloads.claude.ai` at session start: the VM workspace bundle that Cowork sessions run in, and the Claude CLI binary. For networks that cannot reach `downloads.claude.ai`, Anthropic publishes an offline installer variant with both components built into the installer package and verified against checksums compiled into the application, so sessions can start without any connection to Anthropic. The offline installers are several gigabytes larger than the standard ones. Each supported platform and architecture has a fixed download URL that serves the current offline installer: | Platform | Format | Download URL | | --------------------- | ------- | -------------------------------------------------------------------- | | Windows (x64) | `.msix` | `https://claude.ai/api/desktop/win32/x64/offline/latest/redirect` | | Windows (Arm) | `.msix` | `https://claude.ai/api/desktop/win32/arm64/offline/latest/redirect` | | macOS (Apple silicon) | `.dmg` | `https://claude.ai/api/desktop/darwin/arm64/offline/latest/redirect` | | macOS (Intel) | `.dmg` | `https://claude.ai/api/desktop/darwin/x64/offline/latest/redirect` | Each URL responds with an HTTP redirect to a versioned installer file, so any HTTP client that follows redirects downloads the installer directly. New versions of Claude Desktop roll out to connected devices gradually; these URLs serve the newest version whose rollout has completed. The redirect's `Location` header contains the version number, so tooling can detect a new version by requesting the URL without following the redirect. If the offline installer for the version the URL serves is not yet available, the download fails with HTTP 404 rather than falling back to an older installer; this can happen just after a new version appears in the `Location` header. Keep the installer you last downloaded and retry later. Download the installer from a connected machine and bring it across your boundary with your usual software-distribution process. Pair the offline installer with [`disableAutoUpdates`](/docs/third-party/claude-desktop/configuration#disableautoupdates): the app cannot reach the update feed from an air-gapped network, and you update the fleet by distributing each new offline installer through your MDM. Aside from updates, the only egress an air-gapped deployment needs is your inference provider; see [Telemetry and egress](/docs/third-party/claude-desktop/telemetry#required-egress-paths). ## Updates By default, Claude Desktop downloads updates from Anthropic's update server automatically and applies them the next time the app restarts. If the app hasn't restarted within 72 hours of downloading an update, it restarts itself, waiting for 10 minutes of user inactivity before doing so. This enforcement is always on and offers no in-app prompt to defer the restart; the `autoUpdaterEnforcementHours` key tunes the 72-hour window rather than enabling it. In 3P deployments you can: * **Leave auto-update enabled** (recommended) so fixes reach users without IT intervention. Set `autoUpdaterEnforcementHours` to shorten the enforcement window (1 to 72 hours; values above 72 are rejected). Setting the key also makes the window strict: the restart fires as soon as the window elapses, without waiting for a pause in user activity. * **Disable auto-update** (`disableAutoUpdates`) and redistribute new builds through your MDM on your own cadence. This is required for [air-gapped environments](#offline-installation) but means your IT team owns the update pipeline. See [Telemetry and egress](/docs/third-party/claude-desktop/telemetry) for the network paths the updater uses.
third-party/claude-desktop/legal First recorded · 43 lines, first recorded
# Legal and compliance ## Legal agreements ### License ### Commercial agreements ## Compliance ## Usage policy ## Privacy and telemetry ## Security and trust ### Security vulnerability reporting
The first capture of this source. The page was already there, and this is what it said.
# Legal and compliance > Legal agreements, compliance, and security information for Claude Desktop on 3P ## Legal agreements ### License Your use of the Claude Desktop application, including in Claude Desktop on third-party (3P) mode, is subject to Anthropic's [Commercial Terms of Service](https://www.anthropic.com/legal/commercial-terms). ### Commercial agreements Claude Desktop on 3P routes model inference through the provider you configure (Google Cloud's Agent Platform, Amazon Bedrock, Microsoft Foundry, a compatible gateway, or the Anthropic API directly). Inference usage is billed by, and subject to your agreement with, that provider. When you configure the Anthropic API as your provider, inference billing and data terms fall under your Anthropic agreement. Your existing commercial agreement with Anthropic continues to apply to your use of the Claude Desktop application, unless we've mutually agreed otherwise. ## Compliance When using Google Cloud's Agent Platform or Amazon Bedrock, conversation content is sent only to your configured inference endpoint and stored on the local device; data handling is governed by [Google Cloud](https://cloud.google.com/vertex-ai/generative-ai/docs/data-governance) and [Amazon Bedrock](https://docs.aws.amazon.com/bedrock/latest/userguide/data-protection.html) respectively, and the compliance posture of your deployment is determined by your inference provider and the device environment you control. When using Microsoft Foundry, Anthropic acts as an independent processor for Microsoft and customers are subject to Anthropic's data use terms; for deployments hosted on Azure, prompts and completions remain within Azure; only usage metadata and content flagged by Anthropic's safety systems egress to Anthropic. See the [Overview](/docs/third-party/claude-desktop/overview) for the architecture and the provider-specific data path. For Anthropic's certifications and compliance reports, see the [Anthropic Trust Center](https://trust.anthropic.com). For HIPAA, see [HIPAA](/docs/third-party/claude-desktop/overview#hipaa) on the Overview page. When using Google Cloud's Agent Platform or Amazon Bedrock, Anthropic does not interact with PHI; the BAA relationship is between you and your cloud service provider, and any remote MCP servers you connect should be reviewed for HIPAA compliance. ## Usage policy Use of Claude models, including via Claude Desktop on 3P, is subject to the [Anthropic Usage Policy](https://www.anthropic.com/legal/aup). ## Privacy and telemetry The Claude Desktop application sends operational telemetry (crash reports and product analytics) to Anthropic by default. This telemetry contains no prompt or response content and can be fully disabled via managed configuration. See [Telemetry and egress](/docs/third-party/claude-desktop/telemetry) for what each category contains and how to disable it. Anthropic's [Privacy Policy](https://www.anthropic.com/legal/privacy) describes how Anthropic handles data it receives. ## Security and trust Security architecture, threat-model, and data-flow documentation for Claude Desktop and Claude Desktop on 3P is available on the [Anthropic Trust Center](https://trust.anthropic.com). ### Security vulnerability reporting Anthropic manages our security program through HackerOne. [Use this form to report vulnerabilities](https://hackerone.com/4f1f16ba-10d3-4d09-9ecc-c721aad90f24/embedded_submissions/new). *** © Anthropic PBC. All rights reserved. Use is subject to applicable Anthropic Terms of Service.
third-party/claude-desktop/local-access First recorded · 46 lines, first recorded
# Desktop and filesystem access ## Workspace folder allowlist ## Network drives on Windows ## WSL
The first capture of this source. The page was already there, and this is what it said.
# Desktop and filesystem access > How Claude Desktop on 3P reads and writes files on the user's machine, and how to constrain it Like [Cowork](/docs/cowork/overview) in standard Claude Desktop, Claude Desktop on third-party (3P) works directly with files on the user's computer. Users attach one or more **workspace folders** to a session; the agent can then read, create, and modify files anywhere inside those folders, and run code against them inside the sandbox VM. In Claude Desktop on 3P, administrators can constrain which folders users are allowed to attach. ## Workspace folder allowlist The `allowedWorkspaceFolders` configuration key restricts which paths users may attach as workspace folders. | Value | Behavior | | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | Unset | Unrestricted. Users can attach any folder they have OS-level access to, matching standard Claude Desktop. | | `["~/Documents/Claude", "/Volumes/Shared/Projects"]` | Users may attach only folders **inside** one of the listed roots. | | `[]` | No folders may be attached. The agent can still create files in its own sandbox scratch space, but cannot read or write the user's filesystem. | A leading `~` expands to the user's home directory, so a single profile can express per-user roots like `~/Documents/Claude` across the fleet. The check is enforced against the **resolved** path, so symlinks and `..` traversal can't be used to escape an allowed root. <Note> The allowlist controls what users can **attach**. Within an attached folder, the agent has full read/write access to every file the user's OS account can reach. To isolate sensitive data, keep it outside the allowed roots. </Note> ## Network drives on Windows Users can attach a mapped network drive (for example, `Z:\`) as a workspace folder through the folder picker. Raw UNC paths (`\\server\share`) are not supported; map the share to a drive letter first. What the agent can do on the network drive depends on whether the drive was mapped and reachable when the sandbox started: * **Mapped and reachable at sandbox start:** the sandbox mounts the attached folder alongside local folders. File tools and shell commands both work. * **Mapped later, or unreachable at sandbox start:** file tools still work, but shell commands cannot reach the drive. Copy the relevant files to a local folder before running a script or build against them. The sandbox can stay running between sessions. A drive the user maps while the sandbox is already up falls into the second case until the sandbox next restarts. The agent cannot attach a network-drive path on its own; only the user can, through the folder picker. This is a security boundary. On macOS, network mounts under `/Volumes/` are currently treated as local folders. ## WSL You do not need Windows Subsystem for Linux (WSL) to run Claude Desktop or Cowork. On Windows, Cowork's sandbox runs on the operating system's built-in virtualization, which the [readiness check](/docs/third-party/claude-desktop/installation#check-device-readiness) verifies. Install the macOS or Windows package (see [System requirements](/docs/third-party/claude-desktop/installation#system-requirements)); there is no installation path inside WSL. Run the Windows app and work with WSL files from there. Windows exposes a WSL distribution's filesystem as a UNC path (`\\wsl$\<distro>` or `\\wsl.localhost\<distro>`). Like any other raw UNC path, these cannot be attached as workspace folders directly. To attach files that live inside WSL as a workspace folder, map the share to a drive letter and attach the mapped drive, or copy the files to a local Windows folder. [Network drives on Windows](#network-drives-on-windows) describes what the agent can do on a mapped drive.
third-party/claude-desktop/mantle First recorded · 76 lines, first recorded
# Deploy Claude Desktop on 3P with Amazon Bedrock Mantle ## Choose an authentication approach ## Set up AWS ## Prepare devices ### Bearer token ## Configure the app ### Configuration keys ## What users experience ## Troubleshoot
The first capture of this source. The page was already there, and this is what it said.
# Deploy Claude Desktop on 3P with Amazon Bedrock Mantle
> Configure Claude Desktop on 3P to use Claude models through Amazon Bedrock Mantle's Anthropic-native API surface
Amazon Bedrock Mantle is Amazon Bedrock's Anthropic-native API surface. Unlike the standard [Amazon Bedrock provider](/docs/third-party/claude-desktop/bedrock), Mantle speaks the Anthropic Messages API directly and authenticates with a bearer token rather than the AWS SigV4 credential chain, so no AWS CLI, named profile, or IAM Identity Center setup is needed on the device. In practice, Mantle is the Amazon Bedrock provider with a different runtime endpoint and a single bearer-token credential path.
## Choose an authentication approach
Mantle supports a bearer token only. There is no in-app AWS sign-in or named-profile support for this provider; if you need per-user IAM Identity Center authentication, use the standard [Amazon Bedrock provider](/docs/third-party/claude-desktop/bedrock) instead.
| Scenario | Use | Notes |
| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| Any Mantle deployment | [Bearer token](#bearer-token) (`inferenceBedrockBearerToken`) | A long-lived token distributed in the managed profile. |
| Token must not be stored statically | [Credential helper](/docs/third-party/claude-desktop/configuration#inferencecredentialhelper) (`inferenceCredentialHelper`) | An executable that prints the bearer token to stdout at runtime. |
## Set up AWS
Enable Claude models in Amazon Bedrock for the region you will set as `inferenceBedrockRegion`, and obtain a Mantle bearer token for that account. See [Set up AWS](/docs/third-party/claude-desktop/bedrock#set-up-aws) on the Amazon Bedrock page for the model-access step; the IAM Identity Center steps there are not needed for Mantle.
## Prepare devices
### Bearer token
No per-device preparation is required. Place the Mantle bearer token in the managed configuration as `inferenceBedrockBearerToken`.
The app reaches `bedrock-mantle.<region>.api.aws` (or the host in `inferenceBedrockBaseUrl` if you set one). This host is included automatically in the **Egress** section of the in-app configuration window. The `.api.aws` zone has no FIPS endpoint variant.
## Configure the app
Open the [in-app configuration window](/docs/third-party/claude-desktop/in-app-configuration#open-the-configuration-window) (**Developer → Configure Third-Party Inference…**). In the **Connection** section, set **Inference provider** to **Bedrock Mantle**, then fill in the credentials card:
| Field | Value |
| ---------------- | ------------------------ |
| AWS region | e.g. `us-east-1` |
| AWS bearer token | your Mantle bearer token |
| Bedrock base URL | *optional* |
If you set **Bedrock base URL**, provide the full SDK base URL including the `/anthropic` path (for example `https://bedrock-mantle.us-east-1.api.aws/anthropic`); it replaces the default `bedrock-mantle.<region>.api.aws/anthropic` endpoint.
Under **Models**, add at least one **Model list** entry. Mantle has no model-list endpoint, so model discovery is not available and `inferenceModels` is required.
Then click **Export** to produce a `.mobileconfig` (macOS) or `.reg` (Windows) file for your MDM. See [Deploy with MDM](/docs/third-party/claude-desktop/mdm) for the export and deployment workflow.
### Configuration keys
Mantle reuses the `inferenceBedrock*` key names. Only `inferenceBedrockRegion`, `inferenceBedrockBearerToken`, and `inferenceBedrockBaseUrl` apply; the other keys below (`inferenceBedrockProfile`, `inferenceBedrockSso*`, `inferenceBedrockAwsDir`, `inferenceBedrockAwsCliPath`, `inferenceBedrockServiceTier`) are ignored for this provider.
| Setting | Type | Availability | Default | Description |
| ------------------------------------------------------------------------------------------------ | -------- | --------------- | ------- | ----------------------------------------------------------------------------------------------------------------- |
| <span id="inferencebedrockregion" />AWS region<br />`inferenceBedrockRegion` | `string` | MDM + Bootstrap | — | AWS region for the Bedrock runtime endpoint. |
| <span id="inferencebedrockbaseurl" />Bedrock base URL<br />`inferenceBedrockBaseUrl` | `string` | MDM + Bootstrap | — | For VPC endpoints or gateway proxies. Host origin only. |
| <span id="inferencebedrockservicetier" />Bedrock service tier<br />`inferenceBedrockServiceTier` | `enum` | MDM + Bootstrap | — | Sent as the X-Amzn-Bedrock-Service-Tier header. Leave unset for on-demand. One of: `flex`, `priority`. |
| <span id="inferencebedrockbearertoken" />AWS bearer token<br />`inferenceBedrockBearerToken` | `string` | MDM + Bootstrap | — | Static bearer token for inference. For providers that support profile or helper-script credentials, prefer those. |
| <span id="inferencebedrockssostarturl" />AWS SSO start URL<br />`inferenceBedrockSsoStartUrl` | `string` | MDM + Bootstrap | — | Enables in-app AWS sign-in (no AWS CLI needed). Set with the three SSO fields below. |
| <span id="inferencebedrockssoregion" />AWS SSO region<br />`inferenceBedrockSsoRegion` | `string` | MDM + Bootstrap | — | IAM Identity Center home region. |
| <span id="inferencebedrockssoaccountid" />AWS SSO account ID<br />`inferenceBedrockSsoAccountId` | `string` | MDM + Bootstrap | — | 12-digit AWS account ID assigned to users in IAM Identity Center. |
| <span id="inferencebedrockssorolename" />AWS SSO role name<br />`inferenceBedrockSsoRoleName` | `string` | MDM + Bootstrap | — | IAM Identity Center permission-set name granting bedrock:InvokeModel\* on the account above. |
| <span id="inferencebedrockprofile" />AWS profile name<br />`inferenceBedrockProfile` | `string` | MDM + Bootstrap | — | AWS named profile to use for Bedrock inference credentials. |
| <span id="inferencebedrockawsdir" />AWS config directory<br />`inferenceBedrockAwsDir` | `string` | MDM + Bootstrap | — | Folder with AWS config/credentials. Defaults to \~/.aws when no bearer token is set. |
| <span id="inferencebedrockawsclipath" />AWS CLI path<br />`inferenceBedrockAwsCliPath` | `string` | MDM + Bootstrap | — | Absolute path to the aws executable. Leave unset to find it on PATH. |
<AccordionGroup>
<Accordion title="inferenceBedrockServiceTier details">
Tier availability varies by model and region. Reserved capacity uses a provisioned-throughput ARN as the model ID instead of this setting. Older bundled Claude Code CLI versions ignore this key.
</Accordion>
</AccordionGroup>
You must also set `inferenceModels`. As with the standard Amazon Bedrock provider, server-side Web Search is not supported. See the [Configuration reference](/docs/third-party/claude-desktop/configuration#inferencemodels).
## What users experience
The app opens directly on first launch with no user action. Users are never prompted to sign in; re-authentication happens only when you rotate the bearer token in the managed profile.
## Troubleshoot
To confirm which keys the app read and whether credentials validated, use **Help → Troubleshooting → Copy Managed Configuration Report**; see [Verifying the deployment](/docs/third-party/claude-desktop/installation#verifying-the-deployment) for that workflow and the common causes when the app does not enter 3P mode. Application log locations are listed in [Data storage and residency](/docs/third-party/claude-desktop/data-storage).
third-party/claude-desktop/mdm First recorded · 150 lines, first recorded
# Deploy with MDM ## Recommended rollout ## 1. Build a configuration in the app ## 2. Export the profile ### Creating profiles for multiple user groups ## 3. Allow required network egress ## 4. Deploy the configuration ### Update keys and managed precedence ## 5. Distribute the app ## 6. Deploy organization plugins (optional) ## Next steps
The first capture of this source. The page was already there, and this is what it said.
# Deploy with MDM
> Author a full configuration in the app, export it as a profile, and deploy it fleet-wide with Jamf, Intune, Group Policy, or any MDM
On the MDM delivery model, the profile you deploy carries your organization's full configuration, and every device the profile targets gets the same settings. This page covers the workflow end to end: build the configuration in the app, export it, open the firewall, and deploy the profile and installer to your fleet.
Before you start, install Claude Desktop on an admin workstation; see [Installation and setup](/docs/third-party/claude-desktop/installation). If you deliver configuration from a [bootstrap server](/docs/third-party/claude-desktop/bootstrap) instead, follow that page; your profile then carries only the bootstrap keys, but it is exported and deployed the same way described here.
## Recommended rollout
Roll out in this order; the numbered sections on this page cover each step in detail.
<Steps>
<Step title="Build a configuration in the app">
An admin builds and tests a working configuration in the [in-app configuration window](/docs/third-party/claude-desktop/in-app-configuration) on their own device.
</Step>
<Step title="Export the profile">
Export the validated configuration in the format your MDM expects.
</Step>
<Step title="Allow required network egress">
Open the hostnames your configuration requires on your perimeter firewall; the configuration window lists them for the exact settings you chose.
</Step>
<Step title="Deploy the configuration, then the app">
Distribute the profile through your MDM, then push the installer. Deploying the configuration first means users open Claude for the first time and land directly in the third-party deployment, with no opportunity to sign in to claude.ai by mistake.
</Step>
</Steps>
## 1. Build a configuration in the app
Launch Claude Desktop. **Do not sign in or create an Anthropic account**; stay on the login screen. From the macOS menu bar (or on Windows, the application menu ☰ in the top-left of the login screen), go to **Help → Troubleshooting → Enable Developer Mode**, then **Developer → Configure Third-Party Inference…** to open the configuration window.
The window is organized into sections in the left sidebar. Work through them in order; each maps to a group of [configuration keys](/docs/third-party/claude-desktop/configuration), and the window validates values as you enter them.
| Section | What you set |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Connection** | Inference provider (Gateway, Anthropic API, Google Cloud's Agent Platform, Bedrock, or Foundry) and its credentials<br />Model list<br />Organization UUID<br />Optional credential-helper script |
| **Workspace** | Which of Cowork, Code, and Chat are available<br />Allowed egress hosts for the sandbox<br />Disabled built-in tools<br />Allowed workspace folders |
| **Connectors** | Managed MCP servers pushed to all users<br />Whether users can add their own local MCP servers<br />Whether desktop extensions (`.mcpb`) are allowed<br />Whether the extension directory is shown<br />Whether unsigned extensions are rejected |
| **Telemetry & updates** | OpenTelemetry collector endpoint<br />Whether auto-updates are blocked, and the enforcement window if not<br />The three Anthropic-bound telemetry toggles (essential, nonessential, nonessential services) |
| **Limits** | Per-device token cap and its window length |
| **Appearance** | Persistent banner shown across the app window |
| **Plugins** | [Plugin marketplaces](/docs/third-party/claude-desktop/extensions#plugin-marketplaces-admin), added by GitHub repo or git URL<br />Shows the org-plugins folder path for your platform; plugin bundles are mounted to that folder via your MDM, not through this window |
| **Egress** | A read-only firewall allowlist derived from everything you've entered above, grouped by feature<br />**Copy hostnames**, **Download .txt**, and **Test connectivity** actions |
| **Source** | The bootstrap keys, if you are using the [bootstrap server](/docs/third-party/claude-desktop/bootstrap) delivery model instead of a full MDM profile<br />Bootstrap-delivered configuration takes priority over MDM-delivered values: it replaces them wholesale rather than merging key by key |
<Note>
When a managed (MDM-delivered) configuration is already present on the device, the configuration window opens read-only: it shows what the admin deployed, marks the configuration as organization-managed, and directs users to their IT administrator. To author a new configuration, use a device without a managed profile, or temporarily remove the profile. Profiles that set [only the two update keys](#update-keys-and-managed-precedence) leave the window editable.
</Note>
## 2. Export the profile
Once your configuration tests successfully, click **Export** and choose a format:
| Format | Platform | Deploy with |
| --------------------------- | -------- | --------------------------------------------------------------------------------------------------------------- |
| `.mobileconfig` | macOS | Jamf, Kandji, Mosyle, Workspace ONE, or any Apple MDM |
| `.reg` | Windows | Group Policy (import into a GPO), Intune (via custom ADMX or script), or any MDM that can write registry policy |
| `.zip` (ADMX template) | Windows | Schema-only template for Intune or Group Policy; you enter values in the management console |
| `.plist` (Profile Manifest) | macOS | Schema-only template for Jamf, ProfileCreator, or similar macOS tools |
The two actions in the configuration window do different things:
* **Apply locally** writes the selected configuration to your own machine's Claude settings and relaunches the app, so you can test it end to end before deploying it.
* **Export** writes a deployment file in the format you choose and leaves your local settings untouched.
### Creating profiles for multiple user groups
Many organizations deploy distinct configurations to different populations: for example, a permissive profile for an engineering pilot group and a restricted profile for the broader rollout, or per-region profiles that point at different inference endpoints.
The configuration window can hold multiple named configurations. Use the picker in the top-right of the window:
* **New configuration** creates an empty configuration.
* **Duplicate** copies the current configuration as a starting point for a variant.
* **Rename** and **Delete** manage the list.
* **Reveal in Finder** opens the on-disk location where saved configurations are stored.
Selecting a configuration in the picker loads it for editing; the **applied** badge marks the one currently active on your machine. **Apply locally** and **Export** each act on whichever configuration is selected, so you can test each one locally and export them independently.
In your MDM, scope each exported profile to the corresponding device or user group. Targeting is handled by your MDM's assignment rules; the configuration name is for your authoring workflow and is not part of the deployed profile.
<Note>
On Windows, check which registry hive your assignment rules write to. If your assignment rules deliver a profile in user context, it lands in user policy (`HKCU`), and the app ignores user policy entirely when machine policy is present; see [Deploy the configuration](#4-deploy-the-configuration). To vary configuration per user group on Windows, deliver every profile through user policy and keep `HKLM\SOFTWARE\Policies\Claude` empty, or serve per-user configuration from a [bootstrap server](/docs/third-party/claude-desktop/bootstrap).
</Note>
## 3. Allow required network egress
The hosts the app needs to reach depend on the configuration you built: your inference provider's endpoint is always required, and each telemetry, update, and service setting you leave enabled adds its own hosts. The configuration window shows the exact allowlist for your settings and can export it as a text file for your network team.
<Warning>
`downloads.claude.ai` is required to run the app regardless of your configuration: it serves the VM workspace bundle and the latest Claude Code binary, fetched at session start. Without it, Cowork sessions cannot start. The [offline installer variant](/docs/third-party/claude-desktop/installation#offline-installation) builds both components into the installer package and does not need this host.
</Warning>
Open these hosts on your perimeter firewall before rolling out to devices. See [Telemetry and egress](/docs/third-party/claude-desktop/telemetry#required-egress-paths) for the full list of hosts grouped by the setting that controls each one, and for the distinction between the perimeter firewall and the in-app sandbox allowlist.
## 4. Deploy the configuration
Push the exported configuration through your MDM. The app reads from these locations:
<Tabs>
<Tab title="macOS">
| Source | Path | Precedence |
| ------------------ | -------------------------------------------------------------------------- | ---------- |
| Managed (per-user) | `/Library/Managed Preferences/<user>/com.anthropic.claudefordesktop.plist` | Highest |
| Managed (machine) | `/Library/Managed Preferences/com.anthropic.claudefordesktop.plist` | |
| Local (user) | `~/Library/Application Support/Claude-3p/configLibrary/` | Lowest |
A `.mobileconfig` profile delivered by MDM lands in the Managed Preferences locations automatically. Both managed paths are read; where a key appears in both, the per-user value wins.
</Tab>
<Tab title="Windows">
| Source | Path | Precedence |
| -------------- | ----------------------------------------- | ---------- |
| Machine policy | `HKLM\SOFTWARE\Policies\Claude` | Highest |
| User policy | `HKCU\SOFTWARE\Policies\Claude` | |
| Local (user) | `%LOCALAPPDATA%\Claude-3p\configLibrary\` | Lowest |
A Group Policy Object or Intune configuration profile writes to the registry policy paths. The hives are not merged: when machine policy is present (any `REG_SZ`, `REG_EXPAND_SZ`, or `REG_DWORD` value directly under `HKLM\SOFTWARE\Policies\Claude`, including an empty string, and the key's unnamed default value when set), the app ignores `HKCU\SOFTWARE\Policies\Claude` entirely. Deploy the complete configuration to one hive; machine policy (`HKLM`) is the recommended location.
<Warning>
Values must sit directly under `HKLM\SOFTWARE\Policies\Claude` or `HKCU\SOFTWARE\Policies\Claude`. The app never reads values nested in a subkey, as some ADMX-based and Policy CSP tooling writes them: they do not apply as configuration and do not count as machine policy being present. Write values as `REG_SZ` (`REG_DWORD` is also accepted for boolean and integer keys and is read as its decimal value). Avoid `REG_EXPAND_SZ`: the app counts it as machine policy being present but cannot read its contents, so a single `REG_EXPAND_SZ` value under `HKLM` disables user policy without supplying any configuration. The app cannot see `REG_QWORD`, `REG_MULTI_SZ`, or `REG_BINARY` values at all.
</Warning>
<Note>
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.
</Note>
</Tab>
</Tabs>
When a managed source sets any key other than the two update keys, the managed configuration owns the device: it takes effect, the in-app configuration window becomes read-only, and locally authored values in `configLibrary/` are ignored.
### Update keys and managed precedence
The update keys `disableAutoUpdates` and `autoUpdaterEnforcementHours` are treated specially, so you can set an update policy from MDM without managing the whole configuration. When a managed source sets only these keys (one or both), the device keeps its locally authored configuration and the configuration window stays editable. The update keys themselves are still enforced as a pair: both are resolved from the managed source alone, so a locally set value for either key is ignored even if the profile only sets the other one.
If the managed profile sets any other recognized key, the normal rule above applies and the whole configuration is managed.
## 5. Distribute the app
Deploy the Claude Desktop installer to enrolled devices using your standard software-distribution mechanism. On launch, the app reads the managed configuration, detects the configured inference provider and credentials, and the sign-in screen offers users the option to start in Claude Desktop on 3P.
## 6. Deploy organization plugins (optional)
If you're distributing [organization plugins](/docs/third-party/claude-desktop/extensions#organization-plugins-admin), push the plugin bundles to the org-plugins directory on each device alongside the configuration profile. Plugins are picked up at the next app launch.
## Next steps
After deployment, confirm devices picked up the configuration with the checks in [Verifying the deployment](/docs/third-party/claude-desktop/installation#verifying-the-deployment).
third-party/claude-desktop/overview First recorded · 85 lines, first recorded
# Overview ## Who it's for ## Architecture ### Security posture ## Data residency and international deployment ## Public sector and highly regulated environments ## HIPAA ## Next steps
The first capture of this source. The page was already there, and this is what it said.
# Overview
> Run Claude Desktop against your own cloud inference provider
Claude Desktop on third-party (3P) is a deployment mode of Claude Desktop that routes all model inference through a provider you configure: Google Cloud's Agent Platform, Amazon Bedrock, Microsoft Foundry, any compatible gateway you operate, or the Anthropic API directly. The app runs from a bundled local web application, and conversation history is stored on the user's device.
You get the full Claude Desktop experience (Chat, Cowork, and Code, including file creation, multi-step research, and sub-agent coordination) with inference and billing handled by the provider you choose.
## Who it's for
Claude Desktop on 3P is designed for organizations whose security, regulatory, or contractual requirements prevent them from sending data to Anthropic's first-party infrastructure. Typical deployments include:
* **Highly regulated enterprises on 3P only:** organizations that use third-party inference for regulatory or security reasons
* **International enterprises with data residency requirements:** organizations that require in-region data residency and cannot send conversation data to the United States
If your organization can use Anthropic's first-party products directly, standard Claude Desktop with [Cowork](/docs/cowork/overview) on a Team or Enterprise plan is simpler to deploy, offers an in-app UI for user management, analytics, and RBAC, and releases new features more quickly than Claude Desktop on 3P. Choose Claude Desktop on 3P when routing inference through Anthropic's API is not an option.
## Architecture
Claude Desktop on 3P keeps the standard feature set and relocates inference to the provider you configure.
| Component | Standard Claude Desktop | Claude Desktop on 3P |
| ---------------------- | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| Model inference | Anthropic API | Your configured provider endpoint (Google Cloud's Agent Platform, Amazon Bedrock, Microsoft Foundry, or gateway), or the Anthropic API |
| Web application | Loaded from claude.ai | Bundled inside the desktop app |
| User identity | Anthropic account | Local device identity only |
| Conversation storage | Anthropic backend | Local disk on the user's machine |
| Code execution sandbox | Local VM | Local VM (identical) |
| Configuration | Admin console at claude.ai | OS-native configuration (MDM-managed or per-user) |
The desktop app detects 3P mode at launch from the configured inference provider. When a provider and its credentials are present, the sign-in screen offers the option to skip Anthropic authentication and start the app using your inference-provider configuration instead.
### Security posture
* **Conversation content goes only to your configured endpoint.** Prompts, responses, files, and tool outputs are sent only to your configured inference endpoint and stored only on the local machine; data handling at the provider is governed by your inference provider. For Microsoft Foundry deployments hosted on Azure, prompts and completions remain within Azure; only usage metadata and content flagged by Anthropic's safety systems egress to Anthropic.
* **Sandboxed tool execution.** Shell commands run in the hardened Cowork VM; file access is scoped to your allowed folders and web fetches to your egress allowlist.
* **Auditable telemetry.** Crash reports and product analytics are scrubbed of conversation and user data before being sent to Anthropic, and can be fully disabled via configuration keys. Independently, you can export session activity to your own OpenTelemetry collector. The export is metadata only by default, with prompt and tool content available as an explicit opt-in.
* **Centrally managed.** All configuration is delivered via your existing MDM (Jamf, Intune, Workspace ONE, Group Policy) and cannot be overridden by end users when an admin profile is present.
For a detailed treatment of the threat model, sandbox boundaries, and data flows, request access to the [Claude Cowork Desktop Security Architecture Overview](https://trust.anthropic.com/resources?s=2a7bbzo1lyymvdt551q7kl\&name=claude-cowork-desktop-security-architecture-overview) on Anthropic's Trust Center. For architecture, telemetry, and controls information specific to Claude Desktop on 3P, see the [Claude Desktop Security Overview (Third-party platforms)](https://trust.anthropic.com/resources?s=0c8rx4s7mm5ierz8ppetfs\&name=claude-cowork-security-overview-\(third-party-platforms\)) on the Trust Center.
## Data residency and international deployment
**Google Cloud's Agent Platform and Amazon Bedrock:** Inference requests go directly from the user's machine to the regional endpoint you configure. Conversation data goes only to that endpoint, to local disk, and optionally to your configured OpenTelemetry collector. Residency is determined by:
1. The cloud region you select for inference
2. The physical location of the user's device, where conversations are persisted
For multi-region organizations, deploy distinct MDM configuration profiles per geography so each user population points at an in-region endpoint. Google Cloud's Agent Platform and Amazon Bedrock each offer Claude models in the EU, UK, and Asia/Pacific regions; consult your provider's model-availability documentation for the current list.
## Public sector and highly regulated environments
This section applies when using Google Cloud's Agent Platform or Amazon Bedrock.
Because inference runs in your cloud tenant, Claude Desktop on 3P operates inside whatever compliance boundary your provider and region give you. The desktop application itself contacts Anthropic-operated hosts only to download the VM workspace bundle and Claude CLI binary (always required), and for crash reporting, product analytics, non-essential services (connector favicons, artifact previews, and the MCP registry), and auto-updates. Each of the latter four can be disabled independently via managed configuration.
With Anthropic-bound telemetry, non-essential services, and updates all disabled, the only remaining Anthropic-operated egress is `downloads.claude.ai` for the VM bundle at session start. Beyond that, the compliance posture of your deployment is determined by your inference provider. See [Telemetry and egress](/docs/third-party/claude-desktop/telemetry) for the full set of network paths and how to lock them down.
## HIPAA
This section applies when using Google Cloud's Agent Platform or Amazon Bedrock.
Claude Desktop on 3P does not process user data, prompts, or completions. As such, Anthropic does not interact with PHI the user may upload to Claude Desktop on 3P; that data is transmitted only to the customer's cloud service provider or any remote MCP servers they optionally choose to configure. For a HIPAA-compliant solution, customers should ensure they have a BAA in place with their CSP and review any MCP servers for HIPAA compliance before connecting them to Claude Desktop on 3P.
Disabling telemetry is not required to run Claude Desktop on 3P in a HIPAA-compliant way, since Anthropic's telemetry does not collect user data, prompts, or completions, only redacted crash reporting and aggregated usage metrics that do not reveal sensitive data.
## Next steps
<Columns cols={2}>
<Card title="Installation and setup" icon="download" href="/docs/third-party/claude-desktop/installation">
Roll out Claude Desktop on 3P to your organization with MDM, or configure a single machine for evaluation.
</Card>
<Card title="Configuration reference" icon="sliders" href="/docs/third-party/claude-desktop/configuration">
Every managed-configuration key, what it does, and recommended security profiles.
</Card>
<Card title="Extensions" icon="puzzle-piece" href="/docs/third-party/claude-desktop/extensions">
Deploy MCP servers, plugins, skills, and hooks across your fleet.
</Card>
<Card title="Telemetry and egress" icon="shield-halved" href="/docs/third-party/claude-desktop/telemetry">
What the app sends to Anthropic, how to turn it off, and the firewall allowlist you'll need.
</Card>
</Columns>
third-party/claude-desktop/telemetry First recorded · 254 lines, first recorded
# Telemetry and egress ## Telemetry categories ### Essential telemetry ### Non-essential telemetry ### Non-essential services ### Auto-updates ## Sending telemetry to your own collector ### Collector endpoint and headers ### User attribution ### Exporter protocol ### Content capture ### Traces (beta) ## Required egress paths ### Always required ### Inference provider ### Auto-updates (`disableAutoUpdates: false`) ### Essential telemetry (`disableEssentialTelemetry: false`) ### Non-essential telemetry (`disableNonessentialTelemetry: false`) ### Non-essential services (`disableNonessentialServices: false`) ### Optional features ## Disabling all Anthropic-bound connections ## Proxy support ### TLS-intercepting proxies on macOS
The first capture of this source. The page was already there, and this is what it said.
# Telemetry and egress
> What Claude Desktop on 3P sends to Anthropic, how to disable it, and the network paths your firewall needs to allow
When Claude Desktop on third-party (3P) is configured with Google Cloud's Agent Platform, Amazon Bedrock, or Microsoft Foundry, the app sends conversation content only to your configured inference endpoint. For Microsoft Foundry, how data is handled beyond that endpoint depends on the deployment's hosting option; see [Claude in Microsoft Foundry](/docs/third-party/claude-desktop/foundry). The app does, by default, send a small amount of operational telemetry (crash reports and product analytics) that helps Anthropic diagnose issues and improve the product. Each category can be disabled independently via managed configuration.
This page covers what each category contains, how to turn it off, and the complete set of outbound hostnames the app uses so you can configure your perimeter firewall.
## Telemetry categories
### Essential telemetry
Crash reports, error stack traces, and performance timings. Contains diagnostic metadata (app version, OS, error type, redacted stack frames) but **never prompt or response content**. Attributed to your organization via `deploymentOrganizationUuid` so Anthropic support can find issues you report.
| Setting | Default | Effect when `true` |
| --------------------------- | ------- | ----------------------------------------- |
| `disableEssentialTelemetry` | `false` | No crash or error data leaves the device. |
<Warning>
Disabling essential telemetry opts you into a **manual support model**. Anthropic will have zero remote visibility into failures on your fleet, so to get help with an issue your team will need to collect application logs from affected machines and send them to Anthropic directly. Leave this enabled during initial rollout.
</Warning>
### Non-essential telemetry
Product-usage analytics: feature adoption, session counts, UI interactions. Used to understand how Claude Desktop is used in aggregate. Contains no prompt or response content. Also gates the **Send** button in Help → Generate Diagnostic Report; with this disabled, diagnostic bundles can only be saved locally.
| Setting | Default | Effect when `true` |
| ------------------------------ | ------- | -------------------------------------- |
| `disableNonessentialTelemetry` | `false` | No product analytics leave the device. |
Leaving this enabled also adds `api.anthropic.com` to the [agent egress allowlist](#required-egress-paths) automatically, so Claude Code can deliver its usage telemetry from inside the sandbox. Allow that host at the perimeter too; it appears in the non-essential telemetry table below.
### Non-essential services
Cosmetic third-party fetches: favicons for connectors shown in the UI, the MCP connector directory lookup, the sandboxed iframe that renders interactive artifact previews, and the sandboxed iframes that render [MCP Apps](/docs/connectors/building/mcp-apps/getting-started), the interactive widgets connectors can display. Disabling these degrades the UI (generic icons, no directory suggestions, static artifact previews, and connector tool results shown as text instead of widgets) but doesn't affect functionality.
| Setting | Default | Effect when `true` |
| ----------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `disableNonessentialServices` | `false` | Favicon, artifact-preview, and MCP App widget fetches are blocked. Connectors that return MCP Apps show the tool's text result instead of the widget. |
### Auto-updates
Checks Anthropic's update feed and downloads new builds.
| Setting | Default | Effect when `true` |
| -------------------- | ------- | ----------------------------------------------------------------------------------------- |
| `disableAutoUpdates` | `false` | The app never checks for or downloads updates. Your IT team must redistribute new builds. |
## Sending telemetry to your own collector
Independently of what's sent to Anthropic, you can export session activity to your own OpenTelemetry collector by setting `otlpEndpoint`. This is the recommended way to retain an audit trail in environments that disable Anthropic-bound telemetry.
For third-party deployments, the export includes session metadata (event names, durations, token counts, result counts, errors) by default, but not message content. It also identifies the signed-in user; see [User attribution](#user-attribution). See [Monitoring](/docs/cowork/monitoring) for the event schema and the [`otlp*` keys](/docs/third-party/claude-desktop/configuration#otlpendpoint) in the configuration reference.
The export carries logs and metrics. Cowork sessions, Code sessions, and the desktop application's own events arrive under the `service.name` values `cowork`, `claude-code-desktop`, and `claude-desktop` respectively. The app adds the collector host to the sandbox egress allowlist automatically, so `otlpEndpoint` does not need an entry in `coworkEgressAllowedHosts`; your perimeter firewall still needs to allow the host.
For collector authentication headers, extra resource attributes, and the log level of the desktop application's own event stream, see [`otlpHeaders`, `otlpResourceAttributes`, and `otlpDesktopLogLevel`](/docs/third-party/claude-desktop/configuration#otlpheaders) in the configuration reference.
### Collector endpoint and headers
Set [`otlpEndpoint`](/docs/third-party/claude-desktop/configuration#otlpendpoint) to the base address of your collector's OTLP/HTTP receiver, for example `https://otel-collector.example.com:4318`. The app appends the OpenTelemetry request paths itself (`/v1/logs`, `/v1/metrics`, and `/v1/traces` when [traces](#traces-beta) are enabled), so enter the address without those suffixes. A path prefix in front of them, such as `https://observability.example.com/otlp`, is kept.
The receiver must implement the OpenTelemetry protocol (OTLP) over HTTP in both its protobuf and JSON encodings, as an OpenTelemetry Collector does by default. If your logging or SIEM platform accepts only its own HTTP ingestion format, run an OpenTelemetry Collector that receives OTLP and forwards to that platform, and set `otlpEndpoint` to the collector's address. Each device opens its own connection to the collector, so the collector must present a TLS certificate the operating system trusts. See [Proxy support](#proxy-support) if a TLS-intercepting proxy sits in between.
[`otlpHeaders`](/docs/third-party/claude-desktop/configuration#otlpheaders) is a JSON object that maps each header name to its value, for example `{"Authorization":"Bearer <token>","X-Tenant":"agency"}`. As with the other object-typed keys described under [Value types](/docs/third-party/claude-desktop/configuration#value-types), write it as a JSON string rather than a native plist dictionary or registry structure.
The app reads both keys at launch, so users must restart it after a change. If the collector refuses requests or cannot be reached, the app keeps working, shows no error, and drops the affected telemetry batches. Check the collector's own request logs to confirm data is arriving.
### User attribution
Every record sent to your collector carries the user's identity as two resource attributes, on all three `service.name` streams:
* `enduser.id` — the signed-in user's identity. With an interactive sign-in flow (for example, Workforce Identity Federation or Google sign-in on Google Cloud's Agent Platform), this is the identity from the provider's claims, normally the user's email address. With credential methods that carry no identity claims (a static key, a credential helper, or an application default credentials file), it is the operating-system login name.
* `process.owner` — the operating-system login name.
`enduser.id` is the same identity the app shows in the sidebar and account menu, and is controlled by the [`endUserAttribution`](/docs/third-party/claude-desktop/configuration#enduserattribution) key: set it to `false` to remove the identity from both the app and the export. `process.owner` is not gated by that key — it is standard OpenTelemetry process metadata and is always present. A static value set under [`otlpResourceAttributes`](/docs/third-party/claude-desktop/configuration#otlpresourceattributes) overrides either attribute: a static `enduser.id` is always passed through — taking precedence over the signed-in identity, and surviving `endUserAttribution: false` — and a static `process.owner` replaces the login name.
These attributes are attached only to the OpenTelemetry export; the Anthropic-bound telemetry described earlier on this page does not carry them.
### Exporter protocol
The `otlpProtocol` key selects the transport for the telemetry export to your collector: `http/protobuf` (the default), `http/json`, or `grpc`. The protocol applies per session type:
* [Code](/docs/third-party/claude-desktop/code) sessions export over the protocol as configured, including `grpc`.
* Cowork sessions do not support gRPC export. When `otlpProtocol` is set to `grpc`, Cowork sessions export over `http/protobuf` instead; other protocol values apply as configured.
* The desktop application's own event stream (`claude-desktop`) always exports over `http/json`, whatever `otlpProtocol` is set to.
The fallback changes the protocol only, not the endpoint. When `otlpProtocol` is `grpc`, the Cowork and desktop-application exports go to the same `otlpEndpoint` over HTTP; if that address is your collector's OTLP/gRPC receiver (conventionally port 4317), that telemetry never reaches the collector. To receive all three streams with one collector, set `otlpProtocol` to `http/protobuf` and point `otlpEndpoint` at the collector's OTLP/HTTP receiver (conventionally port 4318).
### Content capture
To include content in the export, set `otlpContentCapture` to an array of categories:
| Category | Captures |
| -------------------- | --------------------------------------------------------------- |
| `userPrompts` | User message text |
| `assistantResponses` | Model response text |
| `toolDetails` | Tool input arguments (for example, the web-search query string) |
| `toolContent` | Tool output content |
| `rawApiBodies` | Full inference request and response bodies |
On Claude Desktop version 1.17377 or later, enabling `userPrompts` also captures model responses, even if `assistantResponses` is not listed. On those versions, no `otlpContentCapture` configuration captures user prompts without model responses.
Content is exported only to your configured `otlpEndpoint`. Anthropic does not receive it.
### Traces (beta)
The export carries logs (events) and metrics; it does not include traces unless you enable them. To export OpenTelemetry traces as well, set `otlpTracesEnabled` to `true`. Cowork and Code sessions then record a trace for each user interaction, with spans for model requests and tool executions, and every event emitted during a span carries that span's `trace_id` and `span_id`. This lets your backend correlate a prompt's events end-to-end natively, with no transformation on ingest.
Traces use the same `otlpEndpoint` and `otlpProtocol` as the rest of the export, including the Cowork gRPC fallback described in [Exporter protocol](#exporter-protocol). Span and span-event content is gated by the same `otlpContentCapture` categories as events: with no categories enabled, traces carry metadata only (timing, tool names, durations, token counts). Captured content appears primarily on events; spans stay close to metadata.
Two scope notes:
* The metrics in this export don't carry trace context, so trace-based correlation covers traces and events. Correlate metrics with a session via the `session.id` attribute.
* Trace export uses Claude Code's session-tracing beta, and the span structure may change while the feature is in beta.
`otlpTracesEnabled` requires Claude Desktop **1.22209.0** or later.
## Required egress paths
Claude Desktop on 3P has **two** independent network boundaries:
1. **Perimeter firewall:** your corporate network controls what the device can reach. The hostnames below are what you allowlist here.
2. **Agent egress allowlist:** the [`coworkEgressAllowedHosts`](/docs/third-party/claude-desktop/configuration#coworkegressallowedhosts) key controls what the agent's web-fetch and shell tools can reach. This is independent of, and stricter than, the perimeter.
<Note>
The **Egress** section of the in-app configuration window is the authoritative source for your deployment. It computes the exact allowlist from your current settings, updates as you change them, and can export the list as a text file for your firewall team. Use the tables below as a static reference; defer to the configuration window for the precise set your build requires.
</Note>
All traffic is HTTPS on port 443. Allowlist by hostname (SNI); path-level rules aren't required.
### Always required
| Host | Purpose |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `downloads.claude.ai` | VM workspace bundle and Claude CLI binary, fetched at session start. **Without this, Cowork sessions cannot start**, unless the app was installed with the [offline installer variant](/docs/third-party/claude-desktop/installation#offline-installation), which includes both components in the installer package. |
### Inference provider
The host(s) for your configured provider. These carry conversation content.
<Tabs>
<Tab title="Google Cloud's Agent Platform">
| Host | Purpose |
| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `<region>-aiplatform.googleapis.com` | Model inference for single regions. The `global` region uses `aiplatform.googleapis.com`, and the `eu` / `us` multi-regions use `aiplatform.eu.rep.googleapis.com` / `aiplatform.us.rep.googleapis.com`. Replaced by the host of `inferenceVertexBaseUrl` if set. |
| `oauth2.googleapis.com` | Google auth token exchange |
| `sts.googleapis.com` | Google auth token exchange |
| `accounts.google.com` | Google auth token exchange |
| `iamcredentials.googleapis.com` | Google auth token exchange |
</Tab>
<Tab title="Amazon Bedrock">
| Host | Purpose |
| ------------------------------------------------------------------ | -------------------------------------------------------------------------- |
| `bedrock-runtime.<region>.amazonaws.com` | Model inference. Replaced by the host of `inferenceBedrockBaseUrl` if set. |
| `bedrock.<region>.amazonaws.com` | Control plane (model discovery) |
| `sts.amazonaws.com`, `sts.<region>.amazonaws.com` | STS token exchange (profile auth only) |
| `portal.sso.<region>.amazonaws.com`, `oidc.<region>.amazonaws.com` | AWS SSO (profile auth only) |
With `inferenceBedrockBearerToken` set, the runtime and control-plane hosts are required.
For AWS GovCloud regions (`us-gov-*`), the app automatically uses the FIPS endpoints instead: `bedrock-runtime-fips.<region>.amazonaws.com` and `bedrock-fips.<region>.amazonaws.com`.
</Tab>
<Tab title="Microsoft Foundry">
| Host | Purpose |
| ---------------------------------- | ---------------------------------------- |
| `<resource>.services.ai.azure.com` | Model inference |
| `login.microsoftonline.com` | Entra ID auth (interactive sign-in only) |
</Tab>
<Tab title="Gateway">
| Host | Purpose |
| --------------------------------- | --------------- |
| Host of `inferenceGatewayBaseUrl` | Model inference |
</Tab>
</Tabs>
### Auto-updates (`disableAutoUpdates: false`)
| Host | Purpose |
| --------------------- | ---------------------------------------- |
| `claude.ai` | Update feed |
| `api.anthropic.com` | Update feed |
| `downloads.claude.ai` | Update binaries (already required above) |
### Essential telemetry (`disableEssentialTelemetry: false`)
| Host | Purpose |
| ---------------------------------- | ----------------------------------------------------------------------------------------------- |
| `sentry.io` | Crash and error reporting (apex; some firewalls don't match it under `*.sentry.io`) |
| `*.sentry.io` | Crash and error reporting |
| `*.ingest.us.sentry.io` | Crash and error reporting (listed separately for firewalls that match wildcards one label deep) |
| `browser-intake-us5-datadoghq.com` | Performance timing. The configuration window lists additional regional Datadog intake hosts. |
### Non-essential telemetry (`disableNonessentialTelemetry: false`)
| Host | Purpose |
| --------------------- | --------------------------------------------------------------- |
| `a-cdn.anthropic.com` | Analytics SDK |
| `api.anthropic.com` | Claude Code usage telemetry, sent from inside the agent sandbox |
| `a-api.anthropic.com` | Analytics events |
| `claude.ai` | Analytics events |
### Non-essential services (`disableNonessentialServices: false`)
| Host | Purpose |
| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `api.anthropic.com` | MCP connector directory |
| `www.claudeusercontent.com` | Artifact preview iframe |
| `*.claudemcpcontent.com` | [MCP Apps](/docs/connectors/building/mcp-apps/getting-started), the interactive widgets connectors can render. Each widget loads in a sandboxed iframe on its own generated subdomain, so allowlist the wildcard. |
| `assets.claude.ai` | Fonts loaded by MCP App widget iframes |
| `cdnjs.cloudflare.com`, `cdn.jsdelivr.net`, `fonts.googleapis.com` | Artifact preview asset CDNs |
| `www.google.com`, `*.gstatic.com` | Connector favicons |
### Optional features
| Host | Required when |
| --------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
| Host of `otlpEndpoint` | OpenTelemetry export is configured |
| `github.com`, `objects.githubusercontent.com`, `pypi.org`, `files.pythonhosted.org` | Python-based desktop extensions are enabled |
| Hosts of each entry in `managedMcpServers` (server URL, plus `oauth.authorizationServer` and `login.microsoftonline.com` if configured) | Managed MCP servers are configured |
| Hosts in `coworkEgressAllowedHosts` | Sandbox web access is configured |
## Disabling all Anthropic-bound connections
With `disableEssentialTelemetry`, `disableNonessentialTelemetry`, `disableNonessentialServices`, and `disableAutoUpdates` all set to `true`, the desktop application makes **no outbound connections to Anthropic-operated hosts at runtime**. The only required egress is `downloads.claude.ai` (for the VM bundle at session start) and your inference provider. With the [offline installer variant](/docs/third-party/claude-desktop/installation#offline-installation), `downloads.claude.ai` is not needed either, and your inference provider is the only required egress. This describes the application's own connections; what happens to conversation content after it reaches your inference provider is governed by that provider; see the [Overview](/docs/third-party/claude-desktop/overview).
See the [Locked down profile](/docs/third-party/claude-desktop/configuration#recommended-security-profiles) for a complete configuration.
## Proxy support
The Cowork sandbox honors the host operating system's proxy configuration, including PAC (proxy auto-configuration) files. If the device routes HTTPS through a corporate proxy, the sandbox will too, with no additional configuration required.
### TLS-intercepting proxies on macOS
If your proxy performs TLS interception, it presents its own certificate authority. Claude configures its CLI processes to trust the macOS System keychain in addition to the bundled CA roots, so a corporate CA installed there normally works without extra setup.
If inference or tool requests still fail certificate verification, the CA was likely added with policy-restricted trust: certificates installed via `security add-trusted-cert -p ssl …` are trusted by Safari and Chrome but are not picked up by the CLI runtime's keychain reader. Re-add the CA with full root trust (omit `-p`):
```bash theme={null}
sudo security add-trusted-cert -d -r trustRoot \
-k /Library/Keychains/System.keychain /path/to/corp-ca.pem
```
If the certificate is MDM-managed and you cannot change how it is installed, set `NODE_EXTRA_CA_CERTS` as a fallback, then quit and relaunch Claude:
```bash theme={null}
security find-certificate -a -p /Library/Keychains/System.keychain > ~/corp-ca.pem
launchctl setenv NODE_EXTRA_CA_CERTS "$HOME/corp-ca.pem"
```
`launchctl setenv` makes the variable visible to apps launched from Finder or the Dock (shell-profile exports only reach terminal sessions). It applies until the next reboot; to make it permanent, run the command from a LaunchAgent at login.
third-party/claude-desktop/vertex First recorded · 312 lines, first recorded
# Deploy Claude Desktop on 3P with Google Cloud's Agent Platform ## Choose an authentication approach ## How the two sign-in flows compare ### Workforce Identity sign-in ### Google sign-in (OAuth) ### Side by side ## Set up Google Cloud ## Prepare devices ### Credentials file ### In-app Google sign-in #### How it works #### Create the OAuth client #### Federate to a third-party identity provider #### Notes and limitations ### In-app Workforce Identity sign-in ## Configure the app ### Configuration keys ## What users experience ## Troubleshoot
The first capture of this source. The page was already there, and this is what it said.
# Deploy Claude Desktop on 3P with Google Cloud's Agent Platform
> Set up Google Cloud, choose an authentication path for your organization, and configure Claude Desktop on 3P to use Claude models on Google Cloud's Agent Platform
This page walks an IT administrator through a complete deployment on Google Cloud's Agent Platform (formerly Vertex AI): enabling Claude in your Google Cloud project, choosing the authentication path that fits your organization, preparing devices, and pushing the managed configuration. If you only need the list of configuration keys, skip to [Configure the app](#configure-the-app).
## Choose an authentication approach
Google Cloud's Agent Platform authenticates with Google Cloud Application Default Credentials, which can be supplied several ways. The right one depends on whether your users have Google identities and whether you need per-user attribution in Cloud Audit Logs.
| Scenario | Use | Per-device prerequisite | Per-user Cloud Audit Logs identity | Notes |
| --------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| Proof of concept, single team | [Service-account key](#credentials-file) (`inferenceVertexCredentialsFile`) | The key file on each device | No (shared service account) | A long-lived secret distributed to every device. Simplest to start; not recommended for broad rollout. |
| Users have Google Workspace or Cloud Identity accounts | [In-app Google sign-in](#in-app-google-sign-in) (`inferenceVertexOAuth*`) | None | Yes | Users sign in with their Google account inside the app. See the session-control warning below. |
| Users authenticate with a third-party IdP (Entra ID, Okta, Ping, …) and you don't want to provision Google identities | [In-app Workforce Identity sign-in](#in-app-workforce-identity-sign-in) (`inferenceVertexWorkforce*`) | None | Yes (workforce-pool principal) | Users sign in with their corporate identity inside the app. The app runs PKCE against your IdP and exchanges the ID token at Google STS. |
| Your organization already has tooling that obtains a bearer token accepted by Google Cloud's Agent Platform | [Credential helper](/docs/third-party/claude-desktop/configuration#inferencecredentialhelper) (`inferenceCredentialHelper`) | The helper executable on each device | Depends on what the helper obtains | The helper's stdout is sent as the bearer on each inference request. |
| You already operate an LLM proxy | [Gateway provider](/docs/third-party/claude-desktop/gateway) instead of Google Cloud's Agent Platform | None | At your gateway | The proxy holds the Google Cloud credentials; the app authenticates only to the proxy. |
<Warning>
If your Google Workspace or Cloud Identity organization enforces a **Google Cloud session length** of a few hours or less (Admin console → Security → Google Cloud session control), the in-app Google sign-in stores a refresh token that is subject to that policy, and users will be prompted to sign in again each time it expires. For short session policies, either mark your OAuth client as a [trusted app exempt from reauthentication](https://support.google.com/a/answer/9368756), or use a service-account key, Workforce Identity sign-in, or the gateway provider instead.
</Warning>
## How the two sign-in flows compare
The [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.
### Workforce Identity sign-in
Claude Desktop runs authorization code with PKCE directly against **your** IdP. The IdP's ID token is then exchanged at Google's Security Token Service for a short-lived Google Cloud access token. Google STS is stateless and never issues a refresh token, so every renewal starts at your IdP.
```mermaid theme={null}
sequenceDiagram
autonumber
participant App as Claude Desktop
participant Browser as System browser
participant IdP as Your IdP<br/>(Entra ID, Okta, Ping, ...)
participant GCP as Google Cloud<br/>(STS and Vertex AI)
App->>App: Generate PKCE verifier and challenge,<br/>listen on http://127.0.0.1:PORT/callback
App->>Browser: Open IdP /authorize<br/>(client_id, redirect_uri, code_challenge, scope)
Browser->>IdP: Authorization request
IdP-->>Browser: Sign-in page (password, PIV/CAC, MFA)
Browser->>IdP: User authenticates
IdP-->>Browser: 302 to http://127.0.0.1:PORT/callback?code=...
Browser->>App: Deliver authorization code on loopback
App->>IdP: POST /token<br/>(code, code_verifier, client_id, no client secret)
rect rgba(235, 219, 188, 0.4)
IdP-->>App: id_token (+ refresh_token if the<br/>Refresh Token grant is enabled)
Note over App,IdP: IdP-issued tokens.<br/>The refresh_token, when present, belongs to your IdP.
end
App->>GCP: POST sts.googleapis.com/v1/token<br/>(grant_type=token-exchange,<br/>subject_token=id_token, subject_token_type=...:id_token,<br/>audience=//iam.googleapis.com/.../workforcePools/POOL/providers/PROVIDER)
rect rgba(191, 219, 254, 0.4)
GCP-->>App: Google Cloud access_token<br/>(the pool's session duration, 1 hour by default,<br/>capped at the id_token's remaining lifetime, no refresh_token)
Note over App,GCP: Google-issued token. STS is stateless and never returns a refresh_token.
end
App->>GCP: Vertex AI request (Authorization: Bearer access_token)
GCP-->>App: Model response
Note over App,GCP: No ADC file is written. The IdP tokens are stored encrypted with the<br/>operating system's secure storage (Keychain on macOS, DPAPI on Windows).
alt Silent renewal (IdP issued a refresh_token)
App->>IdP: POST /token (grant_type=refresh_token)
IdP-->>App: Fresh id_token
App->>GCP: Repeat STS exchange for a fresh access_token
else No IdP refresh_token
App->>Browser: Repeat the full browser flow when the id_token expires
end
```
### Google sign-in (OAuth)
Claude 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.
```mermaid theme={null}
sequenceDiagram
autonumber
participant App as Claude Desktop
participant Browser as System browser
participant Goog as Google OAuth<br/>(accounts.google.com,<br/>oauth2.googleapis.com)
participant Vertex as Vertex AI
App->>App: Generate PKCE verifier and challenge,<br/>listen on http://127.0.0.1:PORT/callback
App->>Browser: Open accounts.google.com/o/oauth2/v2/auth<br/>(client_id, redirect_uri, code_challenge,<br/>scope=openid email cloud-platform,<br/>access_type=offline, prompt=consent)
Browser->>Goog: Authorization request
opt Cloud Identity is SAML-federated to your IdP
Goog-->>Browser: Redirect to your corporate IdP
Browser->>Goog: Return with SAML assertion
Note over Browser,Goog: Happens inside Google's page.<br/>Claude Desktop never sees this hop.
end
Goog-->>Browser: 302 to http://127.0.0.1:PORT/callback?code=...
Browser->>App: Deliver authorization code on loopback
App->>Goog: POST oauth2.googleapis.com/token<br/>(code, code_verifier, client_id, client_secret)
rect rgba(191, 219, 254, 0.4)
Goog-->>App: access_token + refresh_token
Note over App,Goog: Google-issued tokens.<br/>The refresh_token belongs to Google.
end
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)
Note over App,Vertex: At each session start
App->>App: Write the ADC JSON to a per-session file,<br/>set GOOGLE_APPLICATION_CREDENTIALS
App->>Goog: google-auth-library reads ADC and<br/>POSTs oauth2.googleapis.com/token (grant_type=refresh_token)
Goog-->>App: Fresh access_token
App->>Vertex: Vertex AI request (Authorization: Bearer access_token)
Vertex-->>App: Model response
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.
```
### Side by side
| | Workforce Identity sign-in | Google sign-in (OAuth) |
| ------------------------------------------ | ------------------------------------------------------------------ | ---------------------------------------------------------------------------- |
| OAuth peer the app talks to | Your IdP's OIDC endpoints | Google's OAuth 2.0 endpoints |
| Where your corporate IdP appears | Directly (the app opens it) | Inside Google's sign-in page, via Cloud Identity SAML federation (optional) |
| Refresh token issued by | Your IdP (when the Refresh Token grant is enabled on the client) | Google |
| Google STS (`sts.googleapis.com`) involved | Yes, on every access-token renewal | No |
| ADC file written | No | Yes (`authorized_user` JSON, pointed to by `GOOGLE_APPLICATION_CREDENTIALS`) |
| Registered on the Google side | Workforce pool and OIDC provider (IAM & Admin) | Desktop-app OAuth 2.0 client (APIs & Services → Credentials) |
| Per-user prerequisite | An account at your IdP | A Google Workspace or Cloud Identity account |
| 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) |
## Set up Google Cloud
These steps are performed once per Google Cloud project, regardless of which authentication approach you chose. You need a project with Owner or Editor access.
<Steps>
<Step title="Enable the Vertex AI API">
In the [Google Cloud console](https://console.cloud.google.com/apis/library/aiplatform.googleapis.com), enable the **Vertex AI API** for your project.
</Step>
<Step title="Enable Claude models in Model Garden">
In the [Model Garden](https://console.cloud.google.com/vertex-ai/model-garden), locate the Claude models you intend to deploy and click **Enable** on each. Model availability varies by region; enable them in the region you will set as `inferenceVertexRegion`.
</Step>
<Step title="Grant users access to Google Cloud's Agent Platform">
Each authenticated principal needs permission to call the model. On the project's **IAM** page, grant the **Vertex AI User** role (`roles/aiplatform.user`) to:
* the service account, if using a service-account key file
* the Google group containing your users, if using in-app Google sign-in
If your organization uses a narrower custom role, it must include at minimum `aiplatform.endpoints.predict`.
</Step>
<Step title="Create an OAuth client (in-app Google sign-in only)">
If you chose in-app Google sign-in, create a Desktop-app OAuth client in your project. See [In-app Google sign-in](#in-app-google-sign-in) below for the full procedure, including consent-screen setup.
</Step>
<Step title="Federate to your IdP (optional)">
If your users authenticate with Microsoft Entra ID, Okta, or another identity provider and do not already have Google accounts, you have two options:
* **Workforce Identity Federation** (recommended). Create a workforce pool with an OIDC provider, and use the [in-app Workforce Identity sign-in](#in-app-workforce-identity-sign-in) approach. Users sign in directly with their corporate identity; no Google identity is provisioned.
* **Cloud Identity with SAML SSO.** Provision a free Cloud Identity tenant and configure SAML single sign-on to your IdP. Users then sign in through the in-app Google sign-in approach with a Google identity that is backed by your IdP. See [Set up SSO with a third-party IdP](https://support.google.com/cloudidentity/answer/12032922) in the Cloud Identity documentation.
</Step>
</Steps>
## Prepare devices
What each end-user device needs depends on the authentication approach you chose.
### Credentials file
Create a service account in your project, grant it the **Vertex AI User** role, and download its JSON key. Distribute the key file to a fixed path on each device through your device-management tooling and set `inferenceVertexCredentialsFile` to that path.
`inferenceVertexCredentialsFile` accepts any Application Default Credentials JSON format, so if your environment already produces an `authorized_user` file (from `gcloud auth application-default login`) or an `external_account` Workforce Identity Federation configuration, you can point at that file instead. For `external_account` files, the `credential_source` must be of type `file` or `url` (`executable` sources are not supported), and separate tooling on the device must obtain the IdP token and write it to the configured location; Claude Desktop does not perform that step.
### In-app Google sign-in
No per-device preparation is required. The sign-in experience uses a Google OAuth client that **you create in your own Google Cloud project**; Anthropic does not provide or operate an OAuth client for this flow. Distribute the OAuth client ID and secret in the managed configuration (see [Configure the app](#configure-the-app)).
#### How it works
When `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.
At 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`) into the session sandbox and points `GOOGLE_APPLICATION_CREDENTIALS` at it. The Google Cloud client library inside the sandbox handles access-token minting and refresh automatically.
If 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.
#### Create the OAuth client
<Steps>
<Step title="Configure the OAuth consent screen">
In the Google Cloud Console, in the project where you enabled Claude models, open **APIs & Services → OAuth consent screen**.
If your project belongs to a Google Workspace organization, select the **Internal** user type. Internal apps are limited to users in your Workspace and do not require Google verification, regardless of which scopes they request.
If the project is not in a Workspace organization, you must use the **External** user type. Because this flow requests the `https://www.googleapis.com/auth/cloud-platform` scope, Google classifies the app as using a sensitive scope, and publishing it beyond test users requires Google's OAuth verification process. For that reason, Internal is strongly recommended for enterprise deployments.
</Step>
<Step title="Create a Desktop OAuth client">
In **APIs & Services → Credentials**, choose **Create credentials → OAuth client ID**, and select **Desktop app** as the application type.
Record the generated **Client ID** (ending in `.apps.googleusercontent.com`) and **Client secret**. For installed applications, Google does not treat the client secret as confidential; the flow is protected by PKCE and by the loopback redirect, so it is safe to distribute the secret in a managed configuration profile.
You do not need to add redirect URIs. Desktop-app clients permit loopback (`http://127.0.0.1:<port>`) redirects automatically.
</Step>
<Step title="Allow network egress">
The sign-in flow and subsequent token refreshes reach `accounts.google.com` and `oauth2.googleapis.com` from the user's device. These hosts are already included in the standard egress requirements for Google Cloud's Agent Platform, so if you allowed egress based on the **Egress** section of the configuration window, no additional firewall changes are needed.
</Step>
</Steps>
#### Federate to a third-party identity provider
The in-app sign-in always opens Google's authorization endpoint, because Google Cloud's Agent Platform only accepts Google-issued access tokens. To have users authenticate with your organization's own identity provider (Microsoft Entra ID, Okta, Ping, or an in-house SAML IdP) instead of a Google password, configure Cloud Identity as a broker:
1. In the Google Admin console, set up [SSO with a third-party IdP](https://support.google.com/cloudidentity/answer/12032922) and assign the SSO profile to your Claude Desktop users' organizational unit.
2. Provision those users into Cloud Identity (via SCIM from your IdP, or Google Cloud Directory Sync) so IAM grants resolve.
3. Optionally set `inferenceVertexOAuthLoginHint` so Google skips its own account chooser and routes straight to your IdP with the user's identity pre-filled.
With 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.
#### Notes and limitations
* **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.
* **Both keys required.** If only one of `inferenceVertexOAuthClientId` or `inferenceVertexOAuthClientSecret` is set, the app logs a warning and falls back to standard Application Default Credentials discovery.
* **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.
### In-app Workforce Identity sign-in
No per-device preparation is required. In Google Cloud, create a [workforce pool](https://cloud.google.com/iam/docs/workforce-identity-federation) with an OIDC provider pointing at your organization's IdP, and grant the pool's principals the **Vertex AI User** role on the project.
In your IdP, register a native OAuth client for the app. The app does not send a client secret in this flow, so the client must be public (no client authentication) with PKCE required. The sign-in redirect lands on `http://127.0.0.1:<port>/callback`, where the operating system chooses `<port>` on each sign-in:
* If your IdP permits loopback redirect URIs on any port (the [RFC 8252](https://datatracker.ietf.org/doc/html/rfc8252#section-7.3) native-app pattern, supported by Microsoft Entra ID under the **Mobile and desktop applications** platform), register `http://127.0.0.1/callback` and leave `redirectPort` unset.
* If your IdP requires an exact registered redirect URI (such as Okta or PingFederate), set the `redirectPort` field of `inferenceVertexWorkforceOidc` to a fixed port and register the resulting URI exactly, for example `http://127.0.0.1:53180/callback`.
Use `127.0.0.1`, not `localhost`; most IdPs do not treat them as interchangeable.
Distribute 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.
The 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.
## Configure the app
With Google Cloud set up and devices prepared, open the [in-app configuration window](/docs/third-party/claude-desktop/in-app-configuration#open-the-configuration-window) (**Developer → Configure Third-Party Inference…**) on an evaluation device. In the **Connection** section, set **Inference provider** to **Vertex AI** and fill in the **Vertex AI credentials** card with the values for whichever authentication approach you chose:
| Field | Service-account key | In-app Google sign-in |
| -------------------------- | ---------------------- | ---------------------------------------------- |
| GCP project ID | `your-gcp-project` | `your-gcp-project` |
| GCP region | e.g. `us-east5` | e.g. `us-east5` |
| GCP credentials file path | `/path/to/sa-key.json` | *leave empty* |
| Vertex OAuth client ID | *leave empty* | `1234567890-abc123.apps.googleusercontent.com` |
| Vertex OAuth client secret | *leave empty* | `GOCSPX-xxxxxxxxxxxxxxxxxxxx` |
| Vertex OAuth scopes | *leave empty* | *leave empty for the default* |
| Vertex AI base URL | *optional* | *optional* |
Under **Models**, add at least one **Model list** entry using the publisher model ID, for example `claude-sonnet-5`.
Then click **Export** to produce a `.mobileconfig` (macOS) or `.reg` (Windows) file for your MDM. See [Deploy with MDM](/docs/third-party/claude-desktop/mdm) for the export and deployment workflow.
### Configuration keys
The full set of `inferenceVertex*` keys is below. Set `inferenceProvider` to `vertex`, supply a project and region, and provide exactly one credential source.
The region can be a single region such as `us-east5`, the `eu` or `us` multi-region, or `global`. The app routes inference to a different endpoint host for multi-regions and `global`; if you allowlist egress by hostname, see the [inference provider egress hosts](/docs/third-party/claude-desktop/telemetry#inference-provider).
| Setting | Type | Availability | Default | Description |
| ------------------------------------------------------------------------------------------------------------------------------ | -------- | --------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| <span id="inferencevertexprojectid" />GCP project ID<br />`inferenceVertexProjectId` | `string` | MDM + Bootstrap | — | Google Cloud project ID for Vertex AI inference. |
| <span id="inferencevertexregion" />GCP region<br />`inferenceVertexRegion` | `string` | MDM + Bootstrap | — | GCP region where your Vertex AI Claude models are deployed. |
| <span id="inferencevertexbaseurl" />Vertex AI base URL<br />`inferenceVertexBaseUrl` | `string` | MDM + Bootstrap | — | PSC endpoint, if using one. |
| <span id="inferencevertexoauthclientid" />Vertex OAuth client ID<br />`inferenceVertexOAuthClientId` | `string` | MDM + Bootstrap | — | Desktop-app OAuth client ID. Enables Sign in with Google instead of a credentials file. |
| <span id="inferencevertexoauthclientsecret" />Vertex OAuth client secret<br />`inferenceVertexOAuthClientSecret` | `string` | MDM + Bootstrap | — | Secret for the Desktop-app OAuth client above. |
| <span id="inferencevertexoauthscopes" />Vertex OAuth scopes<br />`inferenceVertexOAuthScopes` | `string` | MDM + Bootstrap | — | Override the Google OAuth scopes (space-separated). Leave blank for the default. |
| <span id="inferencevertexoauthloginhint" />Vertex OAuth login hint<br />`inferenceVertexOAuthLoginHint` | `string` | MDM + Bootstrap | — | Pre-fill Google's account chooser and forward to your federated IdP. \{username} expands to the OS login name. |
| <span id="inferencevertexworkforceaudience" />Workforce Identity audience<br />`inferenceVertexWorkforceAudience` | `string` | MDM + Bootstrap | — | Workforce-pool provider audience. When set, sign-in uses your own IdP plus a GCP STS exchange instead of a Google identity. |
| <span id="inferencevertexworkforceuserproject" />Workforce Identity billing project<br />`inferenceVertexWorkforceUserProject` | `string` | MDM + Bootstrap | — | GCP project for STS billing and quota. Defaults to the Vertex project ID above. |
| <span id="inferencevertexworkforceauthflow" />Workforce Identity sign-in flow<br />`inferenceVertexWorkforceAuthFlow` | `enum` | MDM + Bootstrap | — | How the IdP sign-in runs: system browser (default) or the OS Microsoft Entra broker. One of: `browser`, `broker`. |
| <span id="inferencevertexworkforceoidc" />Workforce Identity IdP (OIDC)<br />`inferenceVertexWorkforceOidc` | `object` | MDM + Bootstrap | — | Your organization’s OIDC IdP. The app runs an authorization-code-with-PKCE flow against this issuer and exchanges the returned ID token at GCP STS. |
| <span id="inferencevertexcredentialsfile" />GCP credentials file path<br />`inferenceVertexCredentialsFile` | `string` | MDM + Bootstrap | — | Absolute path to service-account JSON. Leave blank to fall back to ADC. |
<AccordionGroup>
<Accordion title="inferenceVertexWorkforceAuthFlow details">
* **`browser`** (default) — opens the system browser for an authorization-code (PKCE) sign-in on a loopback redirect URI. See the **IdP setup** notes on `inferenceGatewayOidc` for redirect-URI registration; the same rules apply here.
* **`broker`** — signs in through the OS identity broker (Web Account Manager on Windows, Company Portal on macOS). Requires the workforce-pool IdP to be **Microsoft Entra ID** — the `issuer` on `inferenceVertexWorkforceOidc` must be `https://login.microsoftonline.com/{tenant-id}/v2.0`. The broker satisfies Conditional Access policies that require a compliant/managed device or token protection, and needs no `127.0.0.1/callback` loopback redirect. The Entra app registration must include the broker redirect URIs `ms-appx-web://Microsoft.AAD.BrokerPlugin/{client-id}` (Windows) and `msauth.com.anthropic.claudefordesktop://auth` (macOS) under the **Mobile and desktop applications** platform. Not supported on Linux.
The GCP STS token-exchange step is unchanged in either flow; only how the Entra id\_token is acquired differs.
</Accordion>
<Accordion title="inferenceVertexWorkforceOidc details">
| Field | Type | Default | Description |
| --------------------------------- | --------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `clientId` | `string` | — | OAuth client ID of the desktop app registration at your identity provider (public client, PKCE). |
| `issuer` | `string` | — | HTTPS issuer with OIDC discovery. Set this, or set the authorization and token URLs instead. |
| `authorizationUrl` | `string` | — | HTTPS authorization endpoint. Used with the token URL when no issuer is set. |
| `tokenUrl` | `string` | — | HTTPS token endpoint. Used with the authorization URL when no issuer is set. |
| `scopes` | `string` | — | Space-separated scopes. Defaults to openid profile email offline\_access. |
| `redirectPort` | `integer` | — | Fixed loopback port for the sign-in redirect ([http://127.0.0.1:PORT/callback](http://127.0.0.1:PORT/callback)). Leave unset to use a free port each time. |
| `omitOfflineAccess` | `boolean` | — | Only enable if your IdP rejects the offline\_access scope on this client. Without it the app prompts for sign-in each time the token expires. |
| `additionalRedirectReferrerHosts` | `string` | — | Space-separated hostnames also accepted as the referrer of the sign-in callback. Only needed when the IdP completes sign-in from a different host. |
</Accordion>
</AccordionGroup>
If none of `inferenceVertexCredentialsFile`, the OAuth client keys, the Workforce Identity keys, or `inferenceCredentialHelper` is set, the Google client library falls back to the standard Application Default Credentials search path on the device (`~/.config/gcloud/application_default_credentials.json`, then the environment's metadata server).
You must also set `inferenceModels` to a list of publisher model IDs, for example `claude-sonnet-5`. See the [Configuration reference](/docs/third-party/claude-desktop/configuration#inferencemodels).
## What users experience
Cut at 300 lines. The page has the rest.
third-party/claude-desktop/web-tools First recorded · 153 lines, first recorded
# Web search and web fetch ## Web Search ### Web search options #### Provider-native search #### Built-in web search #### Gateway-side search #### Remote search MCP #### Data handling ## Web Fetch ## Disabling web tools
The first capture of this source. The page was already there, and this is what it said.
# Web search and web fetch
> How Claude Desktop on 3P reaches the internet, which providers support search, and how to control or disable web access
Claude Desktop includes two built-in tools for reaching the web:
* **Web Search** runs a search-engine query and returns ranked results.
* **Web Fetch** retrieves the contents of a specific URL.
In Claude Desktop on third-party (3P), both are subject to your configuration: search depends on your inference provider, and fetch is gated by the sandbox network allowlist.
## Web Search
Web Search is a **server-side tool** executed by your inference provider, not by the desktop app. Availability depends on which provider you've configured:
| Provider | Web Search |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Google Cloud's Agent Platform | Available |
| Microsoft Foundry | Available |
| Amazon Bedrock | Not available natively; use the [built-in web search](#built-in-web-search) below |
| Anthropic API | Available |
| Gateway | Available if your gateway implements Anthropic's `web_search` server tool, passes it through to a provider that does, or runs the search itself; see [Gateway-side search](#gateway-side-search) |
Because the search runs on the provider's infrastructure, queries and results travel over the same path as model inference and are subject to your provider's data-handling terms. No additional firewall rules are needed beyond the inference endpoint itself.
<Note>
`coworkEgressAllowedHosts` governs client-side egress (Web Fetch and in-sandbox shell network activity). The SDK Web Search tool in the table above executes server-side at your inference provider, so the allowlist does not apply to it. The built-in `websearch` server under [Web search options](#web-search-options) runs in the desktop app and does count as client-side egress. To let the agent fetch pages it finds via search, add the relevant hosts to `coworkEgressAllowedHosts` or set it to `["*"]`. To disable provider-side search, add `"WebSearch"` to `disabledBuiltinTools`.
</Note>
### Web search options
If your inference provider supports native search (Google Cloud's Agent Platform, Microsoft Foundry), that's the simplest path and no additional configuration is required. For Amazon Bedrock or a custom gateway, or whenever you want to choose the search backend, use the built-in `websearch` server.
| Option | Best for | Where you configure it | Search backend |
| ------------------------------------------ | ---------------------------------------------------------------------------------------------- | ----------------------------- | -------------------------------------- |
| [Provider-native](#provider-native-search) | Google Cloud's Agent Platform, Microsoft Foundry | Your cloud provider's console | The provider's |
| [Built-in](#built-in-web-search) | Amazon Bedrock or a custom gateway; or any provider when you want to choose the search backend | `managedMcpServers` | Brave, Tavily, Exa, or your own server |
| [Gateway-side](#gateway-side-search) | A custom gateway you already run | Your gateway's configuration | Whatever your gateway is wired to |
| [Remote search MCP](#remote-search-mcp) | A search MCP you already run, or Amazon Bedrock AgentCore | `managedMcpServers` | Whatever that MCP exposes |
#### Provider-native search
Google Cloud's Agent Platform grounding and Microsoft Foundry execute search inside the model call. There's nothing to configure in Claude Desktop; enable search on the cloud provider's side. Amazon Bedrock has no native equivalent (Amazon Bedrock AgentCore is a remote MCP server; see [Remote search MCP](#remote-search-mcp)).
#### Built-in web search
Add the bundled `websearch` server to [`managedMcpServers`](/docs/third-party/claude-desktop/configuration#managedmcpservers). Search runs in the desktop app itself, so it works on every inference provider, including Amazon Bedrock.
You can add it from the [in-app configuration window](/docs/third-party/claude-desktop/in-app-configuration): under **Connectors**, add a **Web search** server, choose the search provider, and supply the vendor key as a header or through a headers helper script.
<Frame caption="The Web search server in the Connectors section of the in-app configuration window, with the search provider menu open.">
<img src="https://mintcdn.com/claude-ai/iVbkJluVpijKTo5a/images/third-party/config-window-web-search.png?fit=max&auto=format&n=iVbkJluVpijKTo5a&q=85&s=19cf4844972d9fd47addec8690db09c8" alt="Web search server card in the in-app configuration window with fields for name, tool policy, headers, and headers helper script, and a search provider menu offering brave, tavily, exa, and custom." width="1428" height="1330" data-path="images/third-party/config-window-web-search.png" />
</Frame>
In the exported configuration, set `provider` to a hosted search vendor (`brave`, `tavily`, or `exa`) for the lowest setup, or to `custom` with `customUrl` to point at a search server you run.
Hosted vendor:
```json theme={null}
{
"managedMcpServers": [
{
"name": "Web search",
"server": "websearch",
"provider": "tavily",
"headersHelper": "/opt/org/bin/tavily-headers",
"toolPolicy": { "web_search": "allow" }
}
]
}
```
<Note>
A hosted-vendor key configured in `headers` or returned by `headersHelper` is the same key on every device, and a local user can extract it. The exposure is limited to billing abuse on that key (it grants no data access). For regulated environments, set spend caps and rotate the key on a schedule, or have `headersHelper` fetch a per-user key: Tavily and Exa support per-user or per-team keys; see their key-management docs.
</Note>
Your own server:
```json theme={null}
{
"managedMcpServers": [
{
"name": "Web search",
"server": "websearch",
"provider": "custom",
"customUrl": "https://search.internal.example.com/v1/search",
"headersHelper": "/opt/org/bin/search-headers",
"toolPolicy": { "web_search": "allow" }
}
]
}
```
Set 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`](/docs/third-party/claude-desktop/credential-helper) (run with no arguments, exit 0, stdout read as JSON), but the output here is a flat header map, not the `{token, headers}` shape `inferenceCredentialHelper` uses.
| Provider | Header your script should output |
| -------- | ----------------------------------- |
| `brave` | `{"X-Subscription-Token": "<key>"}` |
| `tavily` | `{"Authorization": "Bearer <key>"}` |
| `exa` | `{"x-api-key": "<key>"}` |
| `custom` | Whatever your search server expects |
You can use a static `headers` object instead if you don't need a secrets manager.
#### Gateway-side search
If your inference gateway can execute search itself, the search key stays server-side and never reaches end-user devices.
For LiteLLM proxy server, enable [`websearch_interception`](https://docs.litellm.ai/docs/tutorials/claude_code_websearch) in `callbacks` and configure a search backend in the proxy. The gateway intercepts the model's `web_search_20250305` request, runs the search, and returns results to Claude Desktop.
If your gateway translates between API formats (for example, Anthropic to OpenAI chat completions), note that `web_search_20250305` is an Anthropic server tool with no chat-completions equivalent. The translation layer needs to handle it explicitly: run the search when the model requests it and emit `server_tool_use` and `web_search_tool_result` blocks in the response. Reach out to your account team for a reference implementation.
#### Remote search MCP
Connect a search MCP server as a remote `managedMcpServers` entry: either one you host, or Amazon Bedrock AgentCore Gateway with the Web Search target enabled (configure AgentCore for JWT authentication through your identity provider). Whether this stays inside your boundary depends on where the server is hosted; AgentCore is available in commercial AWS regions.
#### Data handling
Search queries go to whichever backend you configure. In every option, the query is also visible to your inference provider as part of the conversation, because the model emits the search call. Anthropic does not receive search queries in any third-party configuration. For audit, the desktop app emits search events to your OTLP collector regardless of which option you choose; add `toolDetails` to [`otlpContentCapture`](/docs/third-party/claude-desktop/telemetry#content-capture) to capture the query text. To keep queries entirely inside your network, use `provider: "custom"` (or a self-hosted MCP) pointed at a search index that itself runs inside your boundary.
<Note>
If you previously routed inference through a LiteLLM proxy to add search, the built-in `websearch` server with `provider: "custom"` is an alternative that removes the proxy from the search path; gateway-side interception remains a valid choice if you prefer the search key to stay server-side.
</Note>
## Web Fetch
Web Fetch runs in the Claude Desktop main process on the user's device. The model supplies only the target URL; it cannot set headers, a request body, or credentials. Every fetch, including redirect targets, is checked against `coworkEgressAllowedHosts` before the request is sent.
By default, the sandbox can reach only your inference provider's endpoint, so Web Fetch will fail for any other host unless you've allowed it. To permit fetches:
| Goal | Set `coworkEgressAllowedHosts` to |
| -------------------------------------- | --------------------------------------------------- |
| Allow specific domains | `["docs.example.com", "*.example.corp"]` |
| Allow all hosts (no sandbox filtering) | `["*"]` |
| Block all fetches | `[]` and add `"WebFetch"` to `disabledBuiltinTools` |
Wildcards match one or more leading subdomain labels (`*.example.com` matches `a.example.com` and `a.b.example.com`, but not `example.com`).
<Note>
`coworkEgressAllowedHosts` controls what the agent's tools can reach. Your perimeter firewall is a separate, outer layer, so a host allowed by this key still won't be reachable if your corporate network blocks it. See [Telemetry and egress](/docs/third-party/claude-desktop/telemetry#required-egress-paths) for the distinction.
</Note>
The same allowlist governs other in-sandbox network activity (for example, `curl` or `pip install` from the agent's shell), not just the Web Fetch tool.
## Disabling web tools
To remove web tools entirely, add them to `disabledBuiltinTools`:
```json theme={null}
["WebSearch", "WebFetch"]
```
With both disabled and `coworkEgressAllowedHosts` empty, the agent has no path to the public internet from inside the sandbox. It can still read and write local files, run code against them, and call any MCP servers you've provisioned. See the [Locked down profile](/docs/third-party/claude-desktop/configuration#recommended-security-profiles).