For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.

Manage LLM clients with Microsoft Intune and keep them configured for agentgateway

Use Microsoft Intune to install supported LLM clients, configure them to use agentgateway, and repair configuration drift. The endpoint-management workflow applies to both Kubernetes and standalone deployments. This guide uses Codex and Claude Desktop for complete examples and describes the management options for the other supported clients.

Intune manages the client endpoint. Agentgateway remains the enforcement point for authentication, authorization, rate limits, guardrails, and observability.

Before you begin

1. Install the agentgateway binary.
2. Configure the LLM provider that your managed clients use.
3. Expose the Gateway through a stable HTTPS hostname that Intune-managed devices can resolve, such as https://llm.example.com.
4. Enroll your test devices in Intune by following the Windows enrollment guide or the macOS enrollment guide.
5. Review the configuration guide for each supported LLM client that you plan to manage.

For standalone, terminate TLS on agentgateway by following the HTTPS listener configuration. Use a certificate whose subject alternative name matches the managed hostname and whose issuer is trusted by the client devices.

Plan the Intune policy

Use four controls for each managed client.

1. Required application: Deploy the client as a required Intune application. Use a Win32 app on Windows. On macOS, use a DMG app when the vendor image contains the application bundle, or an unmanaged PKG app when the vendor supplies a PKG or the installation requires scripts or custom packaging. For either macOS app type, set Ignore app version to Yes for a self-updating client so that Intune detects the bundle instead of reinstalling an older uploaded version. To enforce an exact version, set it to No, control the client’s auto-update behavior when supported, and upload each approved replacement package.
2. Managed configuration: See Choose a management method to identify the supported mechanism for each client. When the client supports native managed policy, deploy that policy through Intune. Otherwise, use a platform script or remediation to manage only the gateway-related settings without overwriting unrelated user configuration.
3. Drift enforcement: Prefer native managed policy, such as managed preferences on macOS. For a macOS client without native managed policy, deploy a recurring Intune shell script to detect and restore the approved configuration. On supported Windows devices, Intune Remediations can run on an hourly schedule. Intune Remediations are not available for macOS.
4. Compliance and access: On enrolled macOS, Linux, and supported Windows devices, optionally use an Intune custom compliance discovery script to report whether the approved gateway configuration is effective. Custom compliance reports drift but does not repair it. Protect agentgateway separately, and optionally use the device compliance result with Microsoft Entra Conditional Access.

A recurring shell script or Windows remediation is periodic, not continuous. A user can change an ordinary user configuration between evaluations. Native managed policy is stronger, but network and gateway policies are still required if users must not bypass agentgateway with another executable or SDK. These macOS controls apply to an enrolled BYOD Mac, but the user can unenroll a personally owned device. Use compliance and Conditional Access policies when access must require continued enrollment.

Choose a management method

The supported clients expose different configuration and enforcement mechanisms. This guide provides end-to-end application deployment, managed configuration, drift enforcement, compliance, and verification examples for Codex and Claude Desktop. The other clients receive configuration-specific guidance. Start with clients that provide native managed policy.

For clients with an ordinary user settings file, detect and update only the gateway-related keys. Replacing the entire file can delete a user’s unrelated editor, model, or accessibility settings.

Configure a gateway client key for the pilot

Use one revocable agentgateway client key for the Codex and Claude Desktop pilot examples in this guide. Protect the OpenAI and Anthropic routes with the same virtual key, and keep the provider credentials separate.

For the pilot, you do not need a different gateway client key or client-key store for each application. In Kubernetes, configure the API key policies on both client HTTPRoutes to use the same virtual-key source. Do not apply the policy to a shared Gateway listener if another route must accept a different credential.

For production, use separate gateway client keys for each application or security boundary. Separate keys provide per-client attribution and let you rotate, revoke, and apply policy to one client without affecting the others. Claude Desktop’s Entra ID mode does not use a gateway client key because agentgateway validates the signed-in user’s JWT instead.

Store the raw pilot key in a password manager while you build the client policies. The examples refer to it as AGENTGATEWAY_API_KEY. Before a broad production assignment, replace the shared static key with per-user, per-device, or identity-based credentials so that you can revoke access and attribute usage independently.

Manage Codex

Codex supports managed configuration in the Codex CLI, IDE extension, and Codex in the ChatGPT desktop app. Managed configuration overrides the user’s config.toml and CLI --config values when the client starts.

Choose a Codex authentication option

Choose one authentication method for the custom agentgateway provider.

This guide uses the environment-variable method. The variable must be available to the process that launches Codex. Setting it only in an interactive shell does not make it available to a Codex desktop application launched from the macOS Finder or Windows Start menu. Use your organization’s secret delivery mechanism to provision the value in the intended user context. Do not place the raw value in the managed TOML.

The Codex verification and compliance scripts in this guide validate this complete environment-variable example. Adapt and test the scripts before you use them to enforce a different Codex authentication method.

For production, a command-backed authentication helper can retrieve a short-lived or device-specific credential from Keychain, Credential Manager, or an internal secret broker. Do not combine auth with env_key, experimental_bearer_token, or requires_openai_auth. For the supported fields, see the Codex configuration reference.

For the distinction between these methods, see Codex custom-provider authentication.

Create the following approved configuration. Replace the example hostname with the stable HTTPS address that exposes agentgateway. Keep the /v1 suffix because Codex sends Responses API requests to /v1/responses.

model_provider = "agentgateway"

[model_providers.agentgateway]
name = "OpenAI via agentgateway"
base_url = "https://llm.example.com/v1"
wire_api = "responses"
env_key = "AGENTGATEWAY_API_KEY"

For more information about the client behavior, see Codex.

macOS

Codex reads managed preferences from the com.openai.codex domain. Deploy the TOML as a base64-encoded config_toml_base64 value.

1. Save the approved configuration as managed_config.toml.

2. Encode the file without line wrapping.

   base64 < managed_config.toml | tr -d '\n'

3. Save the following Intune preference-file content as codex-managed-preferences.xml. Replace BASE64_ENCODED_TOML with the output from the previous step.

   <key>config_toml_base64</key>
   <string>BASE64_ENCODED_TOML</string>

   Warning

   The Intune Preference file template accepts a .plist or .xml file, but the uploaded file must contain only the key-value pairs. Do not add an XML declaration, DOCTYPE, <plist>, or <dict> wrapper. Those elements cause Intune to reject or incorrectly process this preference-file payload.

4. In the Intune admin center, go to Devices > Manage devices > Configuration > Create > New policy.

5. Select macOS and Templates > Preference file.

6. Use com.openai.codex as the preference domain, upload codex-managed-preferences.xml, and assign the policy to your pilot device group.

7. Restart Codex.

For more information about the Intune workflow, see Add preference file settings to macOS devices.

You can also deploy requirements_toml_base64 in the same preference domain to enforce supported Codex security requirements. Provider and base URL fields are managed defaults, not supported requirements.toml constraints.

Verify Codex on macOS

1. In the Intune admin center, open Devices > All devices, select the Mac, and open Device configuration. Confirm that the Codex preference policy reports Succeeded.

2. On the Mac, open Company Portal, select the device, and select Check status to request the latest assigned configuration.

3. Configure the macOS verification script with Codex enabled, and then follow Deploy the verification script on macOS. Confirm that Intune reports success for the installation, effective managed configuration, and network checks. The script reports only check results and does not return the decoded TOML.

4. From the intended user context, verify the gateway key independently. The environment variable must contain the gateway client key, not the OpenAI provider key.

   curl --fail-with-body \
     --header "Authorization: Bearer $AGENTGATEWAY_API_KEY" \
     "https://llm.example.com/v1/models?client_version=intune-verification"

5. Fully quit Codex. On macOS, use Command-Q instead of only closing the window. Reopen Codex so that it loads the managed defaults, and start a new local task. A cloud task does not run through the local managed provider.

6. Start the agentgateway log stream as described in Verify the deployment, and then send a harmless prompt from the new task.

   Reply exactly: AGW-CODEX-VERIFY. Do not use tools.

   To test the Codex CLI on the same managed Mac, you can instead run the following command.

   codex exec 'Reply exactly: AGW-CODEX-VERIFY. Do not use tools.'

7. Correlate the request by its time. Codex might first send GET /v1/models. The decisive entry is a successful POST /v1/responses with the configured gateway hostname, the expected route, and http.status=200. The access log does not need to contain the prompt text.

8. If no entry appears, check that the task is local, Codex was fully restarted, DNS resolves the managed hostname, the HTTPS listener serves a trusted certificate for that hostname, and the managed URL uses https. If the authenticated curl request succeeds but Codex returns HTTP 401, confirm that AGENTGATEWAY_API_KEY is available to the Codex process and restart the application. If both requests return HTTP 401, confirm that the supplied value matches the virtual key configured on the route.

9. Add a conflicting provider or base URL to the user’s config.toml, or start Codex with a conflicting --config value. Restart Codex and confirm that it starts with the managed agentgateway values.

Managed defaults apply when Codex starts. A user can change a supported setting during a running session, but Codex reapplies the managed value at the next launch. Use requirements.toml for supported security constraints and use gateway or network policy when a control must not depend on a client restart.

Windows

Codex reads managed defaults from ~/.codex/managed_config.toml on Windows. Use an Intune Remediation script package to detect and restore the file. Run both scripts with the logged-on user’s credentials so that USERPROFILE resolves to the intended Codex user.

Create the detection script.

$path = Join-Path $env:USERPROFILE ".codex\managed_config.toml"
$expected = @'
model_provider = "agentgateway"

[model_providers.agentgateway]
name = "OpenAI via agentgateway"
base_url = "https://llm.example.com/v1"
wire_api = "responses"
env_key = "AGENTGATEWAY_API_KEY"
'@

if (-not (Test-Path -LiteralPath $path -PathType Leaf)) {
    Write-Output "Codex managed configuration is missing."
    exit 1
}

$actual = [IO.File]::ReadAllText($path).Replace("`r`n", "`n").TrimEnd()
if ($actual -ne $expected.Replace("`r`n", "`n").TrimEnd()) {
    Write-Output "Codex managed configuration differs from policy."
    exit 1
}

Write-Output "Codex managed configuration matches policy."
exit 0

Create the remediation script with the same approved TOML.

$directory = Join-Path $env:USERPROFILE ".codex"
$path = Join-Path $directory "managed_config.toml"
$expected = @'
model_provider = "agentgateway"

[model_providers.agentgateway]
name = "OpenAI via agentgateway"
base_url = "https://llm.example.com/v1"
wire_api = "responses"
env_key = "AGENTGATEWAY_API_KEY"
'@

New-Item -ItemType Directory -Path $directory -Force | Out-Null
$encoding = New-Object Text.UTF8Encoding($false)
[IO.File]::WriteAllText($path, $expected.TrimEnd() + "`n", $encoding)
Write-Output "Restored the Codex managed configuration."

In the Intune admin center, go to Devices > Manage devices > Scripts and remediations and create a script package with these settings.

• Upload the detection and remediation scripts.
• Set Run this script using the logged-on credentials to Yes.
• Set Run script in 64-bit PowerShell to Yes.
• Sign the scripts and enable signature enforcement if your organization has a code-signing process.
• Assign the package to a pilot group and select an hourly schedule.

Change managed_config.toml on a pilot device. At the next evaluation, the detection script exits with code 1 and Intune runs the remediation script to restore the approved content.

Manage Claude Code

Claude Code provides native endpoint-managed settings that users and projects cannot normally override. Set ANTHROPIC_BASE_URL in the managed env object.

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://llm.example.com"
  }
}

Deploy the JSON through one of these Intune-compatible policy locations.

• macOS managed preference domain: com.anthropic.claudecode.
• Windows machine policy: the Settings string value under HKLM\SOFTWARE\Policies\ClaudeCode.
• Managed file: /Library/Application Support/ClaudeCode/managed-settings.json on macOS or C:\Program Files\ClaudeCode\managed-settings.json on Windows.

Use the machine policy or managed file instead of ~/.claude/settings.json. The managed source has higher precedence and is designed for endpoint management.

Manage Claude Desktop

Use Microsoft Intune to deploy a managed Claude Desktop configuration that routes inference through agentgateway. The workflow applies to agentgateway running in Kubernetes or standalone mode and supports three credential models: an agentgateway API key, Microsoft Entra ID, or an advanced per-user Claude subscription passthrough configuration.

Intune installs the application and enforces its endpoint configuration. The credential model determines whether agentgateway validates a gateway key or an Entra identity before adding a centrally managed Anthropic credential, or passes each user’s Claude subscription token upstream.

Prepare the rollout

1. Complete the Claude Desktop guide for your agentgateway mode and chosen credential model.
2. Expose agentgateway through a stable HTTPS hostname that the managed devices can resolve. Claude Desktop rejects plain HTTP for non-loopback addresses with baseUrl: must use https (or http on loopback).
3. Enroll your Windows devices or macOS devices in Intune.
4. Install a supported Claude Desktop release on an unmanaged administrator workstation so that you can build and test the configuration before export.
5. Create an Intune pilot device group. For Entra mode, also create an Entra ID pilot user group. Do not begin with a tenant-wide assignment.

Choose one authentication model

Choose exactly one of the following models before you build the managed profile. The credential settings are mutually exclusive.

Option 1: Use a gateway API key

Gateway API key mode is the recommended starting point. Claude Desktop sends a client key that agentgateway validates, and agentgateway replaces it with a separately managed Anthropic API key for the upstream request. Complete the Claude Desktop gateway API key setup for your agentgateway mode before you build the Intune profile.

For an initial pilot, select Static API key and use the revocable gateway client key from Configure a gateway client key for the pilot. This is the same client key that the Codex example reads from AGENTGATEWAY_API_KEY; you do not need a Claude-specific client-key store. Do not use the Anthropic provider key. A static client key is stored in the local Claude Desktop configuration and in the exported Intune policy, where device administrators can recover it. Limit the assignment to the pilot group and rotate or revoke the key after testing.

Enter and test the following gateway API key settings in Claude Desktop.

{
  "inferenceProvider": "gateway",
  "inferenceGatewayBaseUrl": "https://claude.example.com",
  "inferenceCredentialKind": "static",
  "inferenceGatewayApiKey": "REPLACE_WITH_SHARED_PILOT_GATEWAY_KEY",
  "inferenceGatewayAuthScheme": "bearer",
  "modelDiscoveryEnabled": false,
  "inferenceModels": [
    {
      "name": "claude-opus-5",
      "anthropicFamilyTier": "opus"
    }
  ]
}

Before a broad production assignment, replace the static key with an organization-owned credential helper:

{
  "inferenceCredentialKind": "helper-script",
  "inferenceCredentialHelper": "/absolute/path/to/agentgateway-key-helper"
}

A helper is an executable that Claude Desktop runs with no arguments. It retrieves the assigned key from Keychain, Credential Manager, or an internal secret broker and writes only the credential to standard output. For the output, error, caching, and refresh contract, see Write a credential helper.

From Claude Desktop, confirm that Test connection succeeds, normal inference returns HTTP 200 in the agentgateway request log, and a request without the gateway key returns HTTP 401. When testing a helper, also run it as the intended user with CLAUDE_HELPER_CONTEXT=setup-test. Then continue with Build and test the managed configuration.

Option 2: Use Claude subscription passthrough

Claude subscription passthrough is an advanced option that preserves each user’s Claude seat and usage attribution. The user authenticates to Anthropic with a bearer token from claude setup-token; agentgateway passes that token upstream instead of injecting a centrally managed Anthropic API key. Complete the Claude subscription setup for your agentgateway mode before you build the Intune profile.

Intune can enforce the gateway address, Bearer auth scheme, model list, and model-discovery setting, but do not put the user’s token in the profile. A managed profile is readable by device administrators and cannot safely hold a per-user subscription credential. Instead, deploy an organization-owned credential helper that retrieves the token from per-user secure storage such as Keychain or Credential Manager. Each user obtains and stores their own token. The helper follows the same credential-helper contract and returns that user’s token instead of a gateway key.

Enter and test the following subscription-passthrough settings in Claude Desktop. Add at least one full model ID under Models and turn off model discovery.

{
  "inferenceProvider": "gateway",
  "inferenceGatewayBaseUrl": "https://claude.example.com",
  "inferenceCredentialKind": "helper-script",
  "inferenceCredentialHelper": "/absolute/path/to/claude-subscription-helper",
  "inferenceGatewayAuthScheme": "bearer",
  "modelDiscoveryEnabled": false,
  "inferenceModels": [
    {
      "name": "claude-opus-5",
      "anthropicFamilyTier": "opus"
    }
  ]
}

Claude Desktop appends /v1/models and /v1/messages to the configured base URL.

Test the helper under the intended user account and for noninteractive helper contexts before deployment. In particular, the connection test invokes the helper with CLAUDE_HELPER_CONTEXT=setup-test, and background refreshes must not stop for an interactive prompt. Then continue with Build and test the managed configuration.

Option 3: Use Microsoft Entra ID

Complete the Claude Desktop Entra setup for your agentgateway mode before you build the Intune profile.

Replace any strict gateway API key policy on the Claude Desktop route with the JWT policy. Do not require both authentication methods on the route. Leave the Anthropic provider credential on the backend, and leave authentication policies for other clients attached to their own routes.

Choose the Entra sign-in flow

Claude Desktop supports two Entra sign-in flows for a Gateway connection.

The broker is the recommended production choice for Intune-managed devices. A browser presents device identity only when the browser and operating system are configured to provide it. The broker provides the device identity directly and does not require a loopback callback.

Register Claude Desktop in Entra ID

1. In the Microsoft Entra admin center, go to Entra ID > App registrations > New registration.

2. Create a single-tenant registration, such as Claude Desktop gateway.

3. On the application Overview page, record the Application (client) ID and Directory (tenant) ID. The client ID configures Claude Desktop and becomes the expected token audience on agentgateway. The tenant ID forms the Entra issuer and JWKS URLs.

4. Go to Authentication, add the Mobile and desktop applications platform, and configure the redirect URIs for your sign-in flow.

   Flow and platform	Redirect URI
   Browser on Windows or macOS	http://127.0.0.1/callback
   Broker on Windows	ms-appx-web://Microsoft.AAD.BrokerPlugin/CLIENT_ID
   Broker on macOS	msauth.com.anthropic.claudefordesktop://auth

   Replace CLIENT_ID in the Windows broker URI with the Application (client) ID. When you support both flows during a pilot, register all applicable redirect URIs. These are Claude Desktop callback URIs. Do not substitute the HTTPS agentgateway hostname, which is configured separately as the Gateway base URL.

5. Leave Allow public client flows disabled. Claude Desktop’s browser and broker authorization-code flows do not require this legacy toggle.

6. In Enterprise applications, open the service principal that corresponds to the registration. Set Assignment required? to Yes, and assign the Entra pilot user group. This prevents unassigned tenant users from signing in to the client registration.

The client is public and must not have a client secret. For more information, see Register an application in Microsoft Entra ID.

Prepare managed devices for broker sign-in

On Windows, Web Account Manager is part of the operating system. The device must be registered, joined, or hybrid joined to Entra ID. It must also report the required compliance state to Intune before a compliant-device Conditional Access policy can grant access.

On macOS, deploy the current Intune Company Portal application and configure the Microsoft Enterprise SSO plug-in. Microsoft recommends Platform SSO for strong device registration. For the prerequisites and Intune settings, see Configure Platform SSO for macOS devices. Use one SSO policy on each device. When you deploy Platform SSO, do not also assign a separate Enterprise SSO plug-in policy to that device.

Do not enable a Conditional Access requirement until broker sign-in succeeds on both pilot platforms.

Transition a browser pilot to broker sign-in

1. Confirm that browser sign-in, a full Claude Desktop restart, and a real prompt work through agentgateway.
2. Add the broker redirect URI for each pilot platform to the existing Entra app registration. Keep http://127.0.0.1/callback during the pilot so that you can roll back.
3. Install and sign in to Company Portal on macOS, or confirm that the Windows device is registered with Entra ID. Assign the SSO and device compliance policies to the pilot group and sync the device.
4. On an administrator workstation without an assigned Claude Desktop managed profile, change only the sign-in flow from Browser to Broker. Keep Interactive sign-in, issuer, client ID, scopes, and ID-token selection unchanged. Test the connection and export the updated artifact.
5. Update the existing Claude Desktop Intune profile. Do not assign separate browser and broker profiles to the same user or device.
6. Sync the pilot device, verify the effective managed settings, fully quit and reopen Claude Desktop, and complete broker sign-in. Send a real prompt and confirm an HTTP 200 POST /v1/messages entry with jwt.sub in the agentgateway log.

The agentgateway JWT policy does not change when the client moves from browser to broker. After the broker pilot is stable, remove the browser redirect URI if your organization no longer needs it for rollback.

Build and test the managed configuration

After you complete exactly one authentication option, build a profile that contains only that option’s credential settings plus the common settings in this section.

Use an administrator workstation that does not already have a Claude Desktop managed profile.

1. In Claude Desktop, enable developer mode from Help > Troubleshooting > Enable Developer Mode.

2. Go to Developer > Configure Third-Party Inference > Connection.

3. Configure the values shared by all three authentication models.

   Setting	Value
   Inference provider	Gateway
   Gateway base URL	The HTTPS agentgateway URL. Include /claude only when the route matches and rewrites that prefix.
   Model discovery	Off when you deploy a fixed model list
   Models	One or more full model IDs, such as claude-opus-5; the first entry is the default

4. Configure credentials for only the authentication model that you selected.

   Authentication model	Credential kind	Required settings
   Gateway API key	Static API key for a pilot; Helper script for production	For a pilot, enter the shared gateway client key and select Bearer. For production, set the absolute credential-helper path instead.
   Claude subscription passthrough	Helper script	Set the absolute credential-helper path and Bearer auth scheme. The helper returns the current user’s Claude subscription token.
   Microsoft Entra ID	Interactive sign-in	Set the issuer to https://login.microsoftonline.com/TENANT_ID/v2.0, the Entra Application (client) ID, ID token, scopes openid profile email offline_access, and Broker or Browser sign-in flow.

   For Entra ID, agentgateway must validate the token signature, exact issuer, and application audience. Keep the issuer and client ID in the managed profile aligned with the issuer and audience configured on agentgateway. Use the issuer base URL, not the OpenID discovery-document URL that ends in /.well-known/openid-configuration.

5. Review the remaining Configure Third-Party Inference settings and apply them according to your organization’s requirements. These optional settings are not required to route inference through agentgateway. See the Claude Desktop configuration reference and MDM deployment guide for additional details.

6. Ensure that managed devices can reach the agentgateway hostname. If users must not access LLM providers directly, enforce that requirement with separate network controls. A Claude Desktop or Intune configuration cannot prevent another application from bypassing agentgateway.

7. Apply the configuration locally and test model selection and inference. If you configured managed MCP servers, test them separately. If you intentionally use discovery instead of a fixed list, also test GET /v1/models.

8. Verify the result for the selected model. In all modes, confirm that the agentgateway log records the real /v1/messages request with HTTP 200 and does not expose credentials.

   • For a gateway API key, also confirm that a request without the key returns HTTP 401.
   • For subscription passthrough, use a real prompt as the final validation if Test connection returns the documented false-negative HTTP 429.
   • For Entra ID, confirm that the log records the authenticated identity and that an invalid issuer, audience, expired token, or missing token is rejected.

Export the configuration

After every connection and policy test succeeds, use Export in Claude Desktop.

• Export .mobileconfig for macOS. The profile contains the complete managed configuration in the com.anthropic.claudefordesktop preference domain.
• Export the ADMX package for Windows. The package supplies the schema that Intune uses to create a policy; enter the validated values in the Intune profile. Export .reg as a reference when you need to compare the resulting registry values.

Prefer the application-generated artifacts over hand-written profiles. Nested objects such as the OIDC and MCP settings are encoded as JSON strings in macOS preferences and Windows registry policy. A native property-list dictionary, registry subkey, or incorrectly escaped string does not apply.

For all supported settings and their precedence, see Claude Desktop managed configuration and Deploy with MDM.

Deploy the configuration on macOS

1. In the Intune admin center, go to Devices > Manage devices > Configuration > Create > New policy.
2. Select macOS and Templates > Custom.
3. Upload the exported .mobileconfig file.
4. Assign the profile to the pilot group and monitor its deployment status.
5. Fully quit and reopen Claude Desktop. The application reads managed configuration at launch.

For more information, see Add custom settings to Apple devices in Microsoft Intune.

Deploy the configuration on Windows

1. Extract the exported ADMX package.
2. In the Intune admin center, go to Devices > Manage devices > Configuration > Import ADMX and import the ADMX and en-US ADML files.
3. Create a Windows 10 and later > Templates > Imported Administrative templates profile.
4. Enter the complete validated Claude Desktop configuration and assign it to the pilot group.
5. Confirm that the policy writes string values directly under HKLM\SOFTWARE\Policies\Claude. Do not split the configuration across HKLM and HKCU, and do not put values in registry subkeys.
6. Fully quit and reopen Claude Desktop.

Machine policy is recommended. When any supported machine-policy value is present, Claude Desktop ignores the entire user-policy hive. For more information about importing the templates, see Import custom ADMX and ADML administrative templates into Microsoft Intune.

If imported ADMX templates do not meet your deployment requirements, use an organization-owned Intune PowerShell script to write the exported values to the machine-policy key. Never include a provider credential in the script.

Optional: Add Conditional Access for Entra ID

Complete this section only when you selected Microsoft Entra ID. After broker sign-in works on the pilot devices, create a Conditional Access policy that targets the Claude Desktop Entra enterprise application and pilot users.

1. Start the policy in Report-only mode.
2. Require multifactor authentication as appropriate for your organization.
3. Require the device to be marked compliant.
4. Exclude emergency access accounts.
5. Review the Entra sign-in logs for the expected user, application, device, and grant-control results.
6. Enable the policy for the pilot group before expanding the assignment.

Avoid targeting all users and all resources while developing the policy. A misconfigured compliant-device requirement can also block the administrators who need to repair it. For deployment guidance, see Device compliance policies in Microsoft Intune.

Verify Claude Desktop enforcement

Test the following cases on Windows and macOS before expanding the rollout.

1. If Intune deploys Claude Desktop, confirm its installation under Managed apps or the app installation report. An independently installed copy on a personally owned Mac does not need to appear under Discovered apps.

2. In the Intune admin center, open the device’s Device configuration page and confirm that the Claude Desktop profile reports Succeeded. On macOS, use Company Portal Check status to request the latest configuration.

3. Deploy the platform-appropriate script from Automate verification with Intune with Claude Desktop enabled. Configure its expected credential kind and, for Entra ID, its expected flow, issuer, and client ID. Confirm that Intune reports success for the installation, effective managed gateway URL, authentication settings, and network checks. The script does not return credentials, managed preference contents, or registry contents. It does not verify the model list; confirm the managed model settings in the read-only Claude Desktop configuration window.

4. On macOS, inspect only the non-secret authentication fields in the effective per-user profile. Replace USERNAME with the signed-in user’s short name.

   CLAUDE_PLIST="/Library/Managed Preferences/USERNAME/com.anthropic.claudefordesktop.plist"
   plutil -extract inferenceCredentialKind raw "$CLAUDE_PLIST"
   plutil -extract inferenceGatewayOidcAuthFlow raw "$CLAUDE_PLIST"
   plutil -extract inferenceGatewayOidc raw "$CLAUDE_PLIST"
   if plutil -extract inferenceGatewayApiKey raw "$CLAUDE_PLIST" >/dev/null 2>&1; then
     echo "Unexpected static gateway credential"
   else
     echo "Static gateway credential is absent"
   fi

   For an Entra broker profile, expect interactive, broker, the approved issuer and client ID, and no inferenceGatewayApiKey value. Do not print an API key while troubleshooting.

5. Fully quit and reopen Claude Desktop instead of only closing its window. On macOS, use Command-Q. Open the third-party inference configuration and confirm that it is marked as organization-managed, read-only, and points to agentgateway.

6. Start the agentgateway log stream as described in Verify the deployment. Authenticate with the authentication model that you selected, start a new third-party inference conversation, and send a harmless prompt.

   Reply exactly: AGW-CLAUDE-VERIFY. Do not use tools.

   Then test model discovery and each managed MCP server.

7. Correlate the inference request by its time. Confirm a successful POST /v1/messages entry with the expected managed hostname, route, upstream provider, and http.status=200. For Entra ID, also confirm the authenticated identity. The access log does not need to contain the prompt text and must not contain the client or upstream credential. If no entry appears, check the full restart, managed HTTPS URL, DNS, and network path.

8. Test the negative case for the selected model.

   • For a gateway API key, confirm that a missing or invalid key receives an unauthorized response from agentgateway.
   • For Entra ID, confirm that an invalid issuer, audience, expired token, and missing token each receive an unauthorized response from agentgateway.
   • For subscription passthrough, confirm that an invalid subscription token is rejected by Anthropic. Agentgateway does not independently authenticate the caller in this mode.

9. Try to save a local gateway URL or local third-party configuration. Fully restart Claude Desktop and confirm that the managed configuration remains effective.

10. Confirm that only approved MCP servers are available and that each tool uses the configured approval policy.

11. If you selected Entra broker mode, mark a pilot device noncompliant and confirm that Conditional Access blocks a new sign-in.

12. If you selected Entra ID, remove a pilot user from the assigned group and revoke the user’s sessions. Confirm that a new sign-in is blocked. A JWT that agentgateway already accepted remains valid until its expiration unless you add a separate token-revocation mechanism, so choose an appropriate token and session lifetime.

13. Confirm that endpoint network controls block direct inference traffic to unapproved providers.

Update or remove the Claude Desktop policy

Use a new pilot assignment for every client or configuration update. Claude Desktop reads managed settings once at launch, so users must fully quit and reopen it after a profile change.

To return a device to local configuration, remove the managed Intune profile and restart Claude Desktop. Do not leave a partial machine policy on Windows: any recognized value in the machine-policy hive causes Claude Desktop to ignore user policy.

Manage other clients

The Codex and Claude Desktop sections provide complete rollout examples. The Claude Code section provides native managed-settings guidance, and the remaining clients below provide configuration-specific guidance. Pin and test a client version before you depend on its settings-file format, and update only the keys that route traffic through agentgateway.

Cursor

Follow the Cursor guide to enable Override OpenAI Base URL. Seed and audit that setting only after you confirm its on-disk schema for the Cursor version that Intune deploys. Preserve all unrelated user settings when a remediation changes the value.

Devin Desktop

Follow the Devin Desktop guide and manage the http.proxy value in the editor settings. Use a user-context script that merges only this key, because replacing the file can remove unrelated editor settings.

VS Code Continue

Follow the VS Code Continue guide and deploy or merge the agentgateway model entry in ~/.continue/config.json. If users can define other models, identify the managed entry by a stable name and leave the other array entries unchanged.

GitHub Copilot

Follow the GitHub Copilot guide and manage github.copilot.advanced.debug.overrideProxyUrl in the VS Code user settings. This workflow requires Copilot Business or Enterprise. Merge the property into the JSON file instead of replacing the user’s complete VS Code configuration.

OpenAI SDK

Follow the OpenAI SDK guide and set base_url for Python or baseURL for JavaScript in organization-owned application configuration. Intune can deploy a wrapper, environment file, or managed application, but managing the SDK package alone cannot force application code to use agentgateway.

curl

Follow the curl guide and deploy an organization-owned wrapper command when users need a convenient request template. The curl executable accepts any URL, so this is not an enforcement boundary. Use gateway authentication and endpoint network controls when direct provider access must be blocked.

Manage MCP server policy

You can use the same endpoint-management channels to control Model Context Protocol (MCP) servers in supported clients.

• For Codex, deploy requirements.toml with an mcp_servers allowlist. On macOS, encode it in the requirements_toml_base64 managed preference.
• For Claude Code, deploy allowedMcpServers, deniedMcpServers, and allowManagedMcpServersOnly through the native managed settings. Deploy a managed-mcp.json file when you also need to define the approved servers.
• For Claude Desktop, deploy managedMcpServers and set per-tool toolPolicy values. Set isLocalDevMcpEnabled to false when users must not add local MCP servers, and set mcpPersistentAlwaysAllowEnabled to false when tool approvals must not persist across sessions.

MCP policy controls which tool servers the client can load. It is separate from the model-provider configuration that routes LLM requests through agentgateway.

Automate verification with Intune

The complete Codex and Claude Desktop workflows use the example verification scripts in the agentgateway repository so administrators can check both clients without asking users to run local commands.

• macOS shell script
• Windows PowerShell script
• Script configuration and deployment instructions

Before you upload a script, edit its configuration block. Set the approved Codex URL including /v1, and set the approved Claude Desktop URL to match its route layout. Include a prefix such as /claude only when the route matches and rewrites it. Enable only the clients required for the target group. The optional installation check recognizes the common paths listed in the script. Add your organization’s package path or disable that check and use the Intune managed-app report when the approved package uses a different path. Never add a gateway client key, provider key, bearer token, or another secret.

For Claude Desktop, also set the expected credential kind. The examples default to static. For Entra ID, set it to interactive and populate the expected OIDC flow (browser or broker), issuer, and client ID. The scripts then reject a leftover static key without returning its value.

The scripts perform these checks for every enabled client.

1. Confirm that the application is installed in a recognized location when the installation check is enabled.
2. Read the effective managed preference, file, or registry policy and confirm the approved agentgateway URL. For Codex, also confirm that the TOML names the approved credential environment variable. For Claude Desktop, confirm the expected credential kind and, in Entra mode, the OIDC flow, issuer, client ID, ID-token setting, and absence of a static key. The scripts do not inspect secret values or print the configuration.
3. Connect to the approved URL and confirm that it returns an HTTP response. A 401 or 403 response passes this connectivity check because it proves that DNS, transport, and the protected Gateway listener are reachable.

Deploy the verification script on macOS

1. Download verify-agentgateway-clients-macos.sh.

2. Edit the configuration block at the beginning of the script. For a Codex-only assignment, set the approved URL and credential-variable name, enable Codex, and disable Claude Desktop.

   EXPECTED_CODEX_BASE_URL="https://llm.example.com/v1"
   EXPECTED_CODEX_ENV_KEY="AGENTGATEWAY_API_KEY"
   VERIFY_CODEX=true
   VERIFY_CLAUDE_DESKTOP=false
   VERIFY_INSTALLATION=true
   VERIFY_NETWORK=true

   Replace https://llm.example.com/v1 with the managed Codex base_url. Do not add the gateway key or another secret to the script. To verify both clients in one assignment, leave both client flags enabled and configure the expected Claude Desktop values too.

3. Test the edited script locally from the intended user context. Resolve any failed check before uploading it.

4. In the Intune admin center, go to Devices > By platform > macOS > Manage devices > Scripts > Add, provide a name, and upload the edited script.

5. Set Run script as signed-in user to Yes. The effective Codex and Claude Desktop settings are user-scoped. Enable signature enforcement only when your organization signs the uploaded script.

6. Select an execution frequency and retry behavior appropriate for the pilot.

7. Assign the script to the same pilot group as the client configuration, and create it.

8. On the Mac, open Company Portal, select the device, and select Check status. Script retrieval depends on the Intune management agent check-in, which is separate from the normal MDM configuration sync.

9. In Intune, reopen the script and review Device status or User status. Exit code 0 reports success; a nonzero exit code reports one or more failed checks. Use Verify delivery and execution to interpret pending or failed results and collect the sanitized log.

The Mac must have the Microsoft Intune management agent. For prerequisites, scheduling, and reporting behavior, see Use shell scripts on macOS devices in Intune.

Deploy the verification script on Windows

1. In the Intune admin center, go to Devices > Manage devices > Scripts and remediations and create a script package.
2. Upload the PowerShell script as the detection script. A remediation script is optional when the managed client policy already restores configuration.
3. Set Run this script using the logged-on credentials and Run script in 64-bit PowerShell to Yes.
4. Assign a schedule and the pilot group, and then monitor Device status.

You can instead upload the PowerShell file as a Windows platform script for a one-time check. For recurring checks, review the enrollment, Windows edition, and licensing requirements for Intune Remediations.

The network check does not send an LLM prompt and cannot prove that an interactive client request used agentgateway. After the script passes, complete the interactive test in Verify the deployment and correlate the request with the agentgateway access log.

Add compliance reporting

Use custom compliance when access decisions must include the state of a client configuration. Custom compliance supports enrolled and managed macOS devices, including a BYOD Mac enrolled through Company Portal. It does not cover an unenrolled or MAM-only device. On macOS, a Bash discovery script can report a client-specific Boolean after checking the effective file or managed preference.

The agentgateway examples include independently assignable compliance artifacts for Codex and Claude Desktop.

These scripts apply the same managed-configuration intent as the operational verifiers but implement the custom-compliance contract. They return only the discovered state and never return configuration contents, tokens, prompts, or credentials. A missing or mismatched configuration is a valid discovered false value and uses exit code 0. A nonzero exit code is reserved for a script execution error.

The discovery scripts do not test Gateway reachability. A temporary Gateway or network outage must not make every managed device noncompliant or unexpectedly affect Conditional Access.

Before uploading a script, replace its example URL with the approved address. Include /v1 for Codex and keep EXPECTED_CODEX_ENV_KEY aligned with the managed TOML. For Claude Desktop, include a route prefix such as /claude only when the HTTPRoute matches and rewrites it; use only the origin for a dedicated hostname that matches /. Keep the expected values aligned with the corresponding managed configuration policy. For Entra ID, set the expected Claude credential kind to interactive and populate the expected OIDC flow, issuer, and client ID.

Use separate compliance policies and assignments for the two clients. This prevents a device that requires only one client from being marked noncompliant because the other client is not configured.

Add client compliance on macOS

1. Download the macOS discovery script and rule JSON for the required client.
2. In the Intune admin center, go to Endpoint security > Device compliance > Scripts > Add > macOS and upload the script.
3. The script resolves the signed-in console user and reads both per-user and machine managed preferences, so it supports either the default system context or logged-in-user context. If Intune displays an execution-context setting, either context is supported. Enable signature enforcement when your organization signs scripts.
4. Create a macOS compliance policy, add Custom Compliance, select the discovery script, and upload the custom-compliance rule JSON.
5. Assign the policy to the same pilot group as the client application and managed preference policies.

Each macOS discovery script returns one JSON object on a single line. For example:

{"CodexGatewayConfigured":true}

{"ClaudeDesktopGatewayConfigured":true}

The setting name is case-sensitive and must match the corresponding SettingName in the rule JSON. The value is a JSON Boolean, not a quoted string. Each script returns exit code 0 for either discovered value. A nonzero exit code is reserved for a script execution error.

Add client compliance on Windows

1. Download the Windows discovery script and rule JSON for the required client.
2. In the Intune admin center, go to Endpoint security > Device compliance > Scripts > Add > Windows and upload the script.
3. Set Run this script using the logged on credentials and Run script in 64-bit PowerShell Host to Yes. Enable signature enforcement when your organization signs scripts.
4. Create a Windows compliance policy, add Custom Compliance, select the discovery script, and upload the custom-compliance rule JSON.
5. Assign the policy to the same pilot group as the client application and managed configuration policies.

Each Windows discovery script returns one compressed JSON object. For example:

{"CodexGatewayConfigured":true}

{"ClaudeDesktopGatewayConfigured":true}

Use a grace period during the pilot so that application installation and first policy evaluation can complete. If access to agentgateway uses an Entra enterprise application, optionally use the resulting device compliance state in a Conditional Access policy after the pilot reports the expected results.

Compliance reporting does not repair configuration. Keep the native managed policy, recurring macOS shell script, or Windows remediation assigned when you add compliance reporting. A corrected custom setting can take up to eight hours to appear compliant. On macOS, a user can open Company Portal, select the device, and select Check Status to request an evaluation.

Verify the deployment

Test each policy on a pilot device before broad assignment. The automated script verifies the local prerequisites and network path; retain this final interactive test to prove that the client actually sends inference traffic through agentgateway.

1. If Intune deploys the client, confirm its installation under Managed apps or the app installation report. On a personally owned device, do not expect an independently installed application under Discovered apps.

2. Start the client and send a request.

3. Check that the request appears in the agentgateway proxy logs.

   Review the terminal output from the agentgateway process or the logs from the service that runs agentgateway. Confirm that the request uses the expected listener, route, and model.

   Start the log stream before sending the client request so that unrelated traffic is easier to distinguish. Correlate the request by time; access logs do not need to include prompt text. Confirm the managed hostname, expected route and API path, upstream provider, and a successful status. No matching entry indicates a client, DNS, listener, or network problem. An unauthorized response indicates an authentication problem.

4. For a client managed by a recurring macOS shell script or Windows remediation, change the gateway setting, wait for the next script run, and confirm that Intune restores the approved value.

5. For a client with native managed policy, test a user-level setting and any supported command-line override. Restart the client and confirm that the managed value remains effective.

6. Review the applicable Intune device configuration, managed app, macOS shell script, or Windows remediation status for failures.

Limitations

• Intune manages enrolled endpoints. It does not manage cloud-hosted agents, continuous integration runners, or unmanaged personal devices.
• A recurring macOS shell-script or Windows remediation interval creates a window in which an ordinary user setting can differ from policy.
• Custom compliance is periodic reporting, not continuous enforcement. A corrected setting can take up to eight hours to appear compliant.
• A personally owned Mac must remain enrolled and managed for its custom compliance policy to run. A user who unenrolls the Mac removes this Intune control.
• Local administrators can subvert many endpoint controls. Use agentgateway authentication and authorization, and consider network controls that block direct access to LLM providers.
• Client configuration formats and supported enterprise settings can change. Pin and test an approved client version before updating the Intune package.

Next steps

Review the client guides that underpin the two complete Intune examples, then apply the Gateway security controls appropriate for your deployment.