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

Configure Claude Desktop to use agentgateway running in Kubernetes

Configure Claude Desktop to route requests through your agentgateway proxy running in Kubernetes.

About third-party inference mode

Claude Desktop sends model traffic to Anthropic by default. Third-party inference mode changes that destination to an endpoint that you operate, such as an agentgateway proxy. Anthropic made this mode generally available on July 9, 2026.

Anthropic designed the mode for organizations whose security, regulatory, or contractual requirements prevent them from sending data to Anthropic’s first-party infrastructure. Prompts, responses, files, and tool outputs go only to the endpoint that you configure, and conversation history stays on the user’s device. You can create an agentgateway proxy at that endpoint, so that every Claude Desktop request passes through your policies for authentication, guardrails, rate limits, and observability before it reaches a model.

Keep the following behavior in mind:

• One setting covers the whole Claude Desktop app. Chat, Cowork, and Code all send inference to the endpoint that you configure.
• Claude Desktop reads its configuration once, at launch. After you change a setting, fully quit the app and reopen it.
• The gateway URL must use HTTPS unless it is a loopback address. A plain HTTP URL on any other host fails validation with the error Invalid custom3p enterprise config: baseUrl: must use https (or http on loopback).
• Managed configuration wins. When an administrator delivers settings through mobile device management (MDM), users cannot override them.

For the full list of settings, see the Claude Desktop configuration reference.

Before you begin

1. Set up an agentgateway proxy.

2. Install Claude Desktop.

3. Choose how the proxy authenticates callers.

   Method	When to use	Upstream billing
   Gateway API key	Recommended starting point. Agentgateway validates a client key and adds a separately managed Anthropic API key upstream.	Anthropic API account
   Identity provider	Recommended for an enterprise rollout. Agentgateway validates each user’s OIDC token and adds a separately managed Anthropic API key upstream.	Anthropic API account
   Claude subscription passthrough	Advanced option for preserving per-user Claude subscription usage. Agentgateway passes each user’s token upstream and does not independently authenticate the caller.	User’s Claude subscription

   For a gateway API key, you need an Anthropic API key for the proxy and a virtual API key for Claude Desktop. For subscription passthrough, you need a Claude Pro, Max, Team, or Enterprise subscription and the Claude Code CLI, which provides the claude setup-token command. For identity-provider authentication, you need an OIDC provider and an Anthropic API key for the proxy.

Get the gateway URL

export INGRESS_GW_ADDRESS=$(kubectl get svc -n agentgateway-system agentgateway-proxy \
  -o jsonpath='{.status.loadBalancer.ingress[0].ip}')

echo "Gateway address: $INGRESS_GW_ADDRESS"

export INGRESS_GW_ADDRESS=$(kubectl get svc -n agentgateway-system agentgateway-proxy \
  -o jsonpath='{.status.loadBalancer.ingress[0].hostname}')

echo "Gateway address: $INGRESS_GW_ADDRESS"

kubectl port-forward -n agentgateway-system svc/agentgateway-proxy 8080:80

Set up the Anthropic backend

1. Create a Kubernetes Secret for the Anthropic API key that agentgateway sends upstream. This provider credential is separate from the gateway key that Claude Desktop sends to agentgateway.

   kubectl apply -f- <<EOF
   apiVersion: v1
   kind: Secret
   metadata:
     name: anthropic-secret
     namespace: agentgateway-system
   type: Opaque
   stringData:
     Authorization: "$ANTHROPIC_API_KEY"
   EOF

2. Create an AgentgatewayBackend for the Anthropic provider and reference the provider credential.

   kubectl apply -f- <<EOF
   apiVersion: agentgateway.dev/v1alpha1
   kind: AgentgatewayBackend
   metadata:
     name: anthropic-desktop
     namespace: agentgateway-system
   spec:
     ai:
       provider:
         anthropic: {}
     policies:
       auth:
         secretRef:
           name: anthropic-secret
       ai:
         routes:
           '/v1/messages': Messages
           '/v1/messages/count_tokens': AnthropicTokenCount
           '*': Passthrough
   EOF

   The Authorization value from anthropic-secret is sent upstream as the Anthropic x-api-key. Do not distribute this provider credential to Claude Desktop users.

3. Create an AgentgatewayPolicy to raise the body buffer limit to 10 MB for Claude Desktop and Cowork requests.

   kubectl apply -f- <<EOF
   apiVersion: agentgateway.dev/v1alpha1
   kind: AgentgatewayPolicy
   metadata:
     name: claude-desktop-buffer
     namespace: agentgateway-system
   spec:
     targetRefs:
     - group: gateway.networking.k8s.io
       kind: HTTPRoute
       name: claude-desktop
     frontend:
       http:
         maxBufferSize: 10485760
   EOF

   Note

   Claude Code automatically sends the anthropic-beta: oauth-2025-04-20 header required for OAuth-based authentication. Claude Desktop might require this header to be set as well depending on your client version. If requests fail with a 400 error, add a request transformation to the AgentgatewayPolicy that injects the header.

   backend:
     transformation:
       request:
         set:
         - name: anthropic-beta
           value: oauth-2025-04-20

4. Create an HTTPRoute that matches the /claude path prefix and rewrites it to / before forwarding to the backend. Because the policy in the previous step targets this route, create both resources before you check the policy status.

   kubectl apply -f- <<EOF
   apiVersion: gateway.networking.k8s.io/v1
   kind: HTTPRoute
   metadata:
     name: claude-desktop
     namespace: agentgateway-system
   spec:
     parentRefs:
       - name: agentgateway-proxy
         namespace: agentgateway-system
     rules:
       - matches:
         - path:
             type: PathPrefix
             value: /claude
         backendRefs:
         - name: anthropic-desktop
           namespace: agentgateway-system
           group: agentgateway.dev
           kind: AgentgatewayBackend
         filters:
         - type: URLRewrite
           urlRewrite:
             path:
               type: ReplacePrefixMatch
               replacePrefixMatch: /
   EOF

Use a gateway API key

You can use the same client-side values that the standalone Client Setup page produces. The Kubernetes Admin UI does not generate these values, so configure the gateway and Claude Desktop manually.

1. Verify that the anthropic-desktop backend references anthropic-secret in policies.auth, as configured in Set up the Anthropic backend. For more information, see Anthropic provider.

2. Generate a client API key and store it in a Kubernetes Secret. Use a separate entry for each user or device when you need independent attribution or revocation.

   export CLAUDE_GATEWAY_API_KEY="agw_$(openssl rand -hex 24)"
   
   kubectl apply -f- <<EOF
   apiVersion: v1
   kind: Secret
   metadata:
     name: claude-desktop-client-keys
     namespace: agentgateway-system
   type: Opaque
   stringData:
     claude-desktop: "$CLAUDE_GATEWAY_API_KEY"
   EOF

   For key metadata, hashing, and cost controls, see Virtual keys.

3. Apply strict API key authentication to only the Claude Desktop HTTPRoute.

   kubectl apply -f- <<EOF
   apiVersion: agentgateway.dev/v1alpha1
   kind: AgentgatewayPolicy
   metadata:
     name: claude-desktop-api-key
     namespace: agentgateway-system
   spec:
     targetRefs:
     - group: gateway.networking.k8s.io
       kind: HTTPRoute
       name: claude-desktop
     traffic:
       apiKeyAuthentication:
         mode: Strict
         secretRef:
           name: claude-desktop-client-keys
   EOF

   Target the agentgateway-proxy Gateway only when every attached route expects an agentgateway key.

4. In Claude Desktop, go to Developer → Configure Third Party Inference → Gateway.

5. For Gateway base URL, enter the URL from Get the gateway URL. Include /claude for the shared-hostname route in this guide, but use only the origin when a dedicated hostname matches /.

6. For Credential kind, select Static API key. Enter $CLAUDE_GATEWAY_API_KEY in Gateway API key, and select Bearer for the auth scheme.

7. Under Models, add the full model ID that the backend exposes, or verify that the gateway returns it from GET /v1/models.

8. Click Test connection, and then click Apply Changes. Fully quit Claude Desktop and reopen it.

9. Send a harmless prompt and confirm that the agentgateway request log records /v1/messages with HTTP 200. Then send a request without the gateway key and confirm that the route returns HTTP 401. The negative test verifies that the route does not admit unauthenticated callers.

Claude Desktop sends Anthropic Messages API requests to /v1/messages. Agentgateway can translate those requests for another provider, but a route that exposes only the OpenAI-compatible /v1/chat/completions API is not sufficient.

For a managed rollout, see Manage gateway API keys with Microsoft Intune.

Optional: Use Claude subscription passthrough

Subscription passthrough preserves per-user Claude subscription billing, but agentgateway does not independently authenticate the caller. Remove the provider credential from the backend so that the user’s bearer token can pass through to Anthropic.

kubectl patch AgentgatewayBackend anthropic-desktop \
  -n agentgateway-system \
  --type=json \
  -p='[{"op":"remove","path":"/spec/policies/auth"}]'

Do not apply a strict virtual API key policy to this route. If you are converting an existing gateway-key configuration, remove its route-level API key policy first. Never remove a Gateway-level policy unless you have verified that no other attached route depends on it.

1. Get a bearer token for your Claude account. Store the value in a safe place.

   claude setup-token

2. Open Claude Desktop and enable developer mode from the menu bar: Help → Troubleshooting → Enable Developer Mode. Then fully quit and relaunch Claude Desktop. A new Developer menu appears in the menu bar.

3. In the menu bar, go to Developer → Configure Third Party Inference → Gateway.

4. Enter the Gateway base URL. Remember that a host other than a loopback address must use HTTPS, as described in Get the gateway URL.

   Shared hostnameDedicated hostnamePort-forward for local testing

   When the HTTPRoute matches /claude and rewrites the prefix as shown in this guide, include /claude in the base URL.

   https://$INGRESS_GW_HOSTNAME/claude

   When an HTTPRoute for a dedicated hostname such as claude.example.com matches / without a prefix rewrite, use only the origin. Claude Desktop appends /v1/models and /v1/messages.

   https://claude.example.com

   Use the literal address 127.0.0.1 rather than localhost.

   kubectl port-forward -n agentgateway-system svc/agentgateway-proxy 4001:80 &

   For the gateway address in Claude Desktop, enter:

   http://127.0.0.1:4001/claude

5. For Credential kind, select Static API key. For Gateway auth scheme, select Bearer, and enter the token from step 1 in Gateway API key. Each user must use their own subscription token. To authenticate users with your identity provider and use a centrally managed provider credential instead, see Authenticate users with your identity provider.

6. Open Models and add at least one full model ID that the subscription can use, such as claude-opus-5. Do not use an alias such as opus. The first entry is the default. Turn off Model discovery, or leave it unset; an explicit model list makes discovery unnecessary.

7. Click Test connection. Claude Desktop tests inference with the first configured model. If no explicit model is configured, the test first calls <base-url>/v1/models and fails when the gateway or provider does not make that endpoint available to the subscription token.

   Note

   With subscription passthrough, the connection test might return HTTP 429 with rate_limit_error even when normal Cowork inference works. Apply the configuration, send a harmless prompt, and check the agentgateway request log. If the actual /v1/messages request returns HTTP 200, treat the connection-test result as a false negative.

8. Click Apply Changes, then fully quit Claude Desktop and reopen it. Claude Desktop reads its configuration only at launch.

   Note

   On macOS, Claude Desktop might not enter third-party inference mode from the settings panel alone. If the app still signs in to Anthropic after you reopen it, set deploymentMode to 3p in the third-party configuration file, then quit and reopen the app again.

   python3 - <<'EOF'
   import json, os
   p = os.path.expanduser('~/Library/Application Support/Claude-3p/claude_desktop_config.json')
   d = json.load(open(p))
   d['deploymentMode'] = '3p'
   open(p, 'w').write(json.dumps(d, indent=2))
   EOF

Use a gateway API key

You can use the same client-side values that the standalone Client Setup page produces. The Kubernetes UI does not generate these values, so configure the gateway and Claude Desktop manually.

1. Give the anthropic-desktop backend an Anthropic API key. Follow Anthropic provider to create a provider credential Secret and reference it from policies.auth on the AgentgatewayBackend. This credential is sent upstream and is separate from the key that Claude Desktop sends to agentgateway.
2. Follow Virtual keys to create a client API key and a strict API key authentication policy. Target the claude-desktop HTTPRoute if the key must protect only this integration, or target the agentgateway-proxy Gateway to protect all of its routes.
3. In Claude Desktop, go to Developer → Configure Third Party Inference → Gateway.
4. For Gateway base URL, enter the URL from Get the gateway URL, including the /claude path.
5. For Credential kind, select Static API key. Enter the client API key from step 2 in Gateway API key.
6. Click Apply Changes, then fully quit Claude Desktop and reopen it.

Claude Desktop sends Anthropic Messages API requests to /v1/messages. Agentgateway can translate those requests for another provider, but a route that exposes only the OpenAI-compatible /v1/chat/completions API is not sufficient.

Authenticate users with your identity provider

If you distribute one static API key to every user, you cannot attribute requests to a person or revoke access for only one user. Instead, select the Interactive sign-in credential kind. Claude Desktop then runs an OAuth 2.0 authorization code flow with Proof Key for Code Exchange (PKCE) against your identity provider and sends the resulting token on every inference request. Agentgateway validates the token and adds the LLM provider credential itself, so the user’s device never holds a provider API key.

The interactive sign-in flow is the same for standalone and Kubernetes deployments. Only the agentgateway configuration differs: standalone configures JWT validation directly on the route, whereas Kubernetes uses an AgentgatewayPolicy and an AgentgatewayBackend for the JWKS endpoint.

    sequenceDiagram
    participant C as Claude Desktop
    participant B as Browser or OS broker
    participant E as Microsoft Entra ID
    participant G as agentgateway
    participant A as Anthropic

    alt Browser flow for initial testing
        C->>B: Open the system browser
        B->>E: Authorization request with PKCE challenge
        E-->>C: Authorization code through loopback callback
        C->>E: Exchange code and PKCE verifier
        E-->>C: ID token
    else Broker flow for managed production devices
        C->>B: Request an identity token
        B->>E: Authenticate the user and device
        E-->>B: ID token
        B-->>C: ID token
    end

    C->>G: Inference request with bearer ID token
    G->>E: Fetch and cache signing keys
    G->>G: Validate signature, issuer, and audience
    G->>A: Inference request with provider credential
    A-->>G: Model response
    G-->>C: Model response
  

The OAuth callback returns to Claude Desktop, not to agentgateway. The gateway hostname is the inference endpoint and must not be registered as the OAuth redirect URI.

After you disable or offboard a user, the identity provider prevents new sign-ins and token refreshes. An ID token that was already issued can remain valid until it expires, depending on the identity provider’s revocation and session policies.

The following steps use Microsoft Entra ID as the example identity provider. Any OpenID Connect (OIDC) provider works the same way. Substitute your own issuer URL, client ID, and JWKS path.

1. Register a public-client application with your identity provider, and record the client ID and issuer URL. Do not create a client secret. The following values configure Claude Desktop’s browser flow.

   Setting	Value
   Client type	Public client. Claude Desktop holds no client secret.
   Redirect URI	http://127.0.0.1/callback
   Scopes	openid profile email offline_access

   Important

   Two details about the redirect URI cause most failures:

   • Include the /callback path. Claude Desktop redirects to http://127.0.0.1:<port>/callback, and a registration of http://127.0.0.1 alone does not match. On Entra ID, the mismatch returns AADSTS50011.
   • Register the URI as a native or desktop client, not a web client. Claude Desktop picks an ephemeral port for each sign-in. A native client registration accepts any loopback port, as described in RFC 8252, and a web client registration requires an exact port match. On Entra ID, select the Mobile and desktop applications platform. The browser and broker authorization-code flows do not require the legacy Allow public client flows toggle; leave it disabled.
   • Do not register the agentgateway hostname as the redirect URI. Claude Desktop receives the authorization response, then sends the resulting token to the gateway URL on inference requests.

2. Save the identifiers from your registration, so that the following commands can refer to them.

   export TENANT_ID=<your-tenant-id>
   export CLIENT_ID=<your-client-id>

3. Create an AgentgatewayBackend for the JWKS endpoint of your identity provider. The proxy fetches the signing keys from this backend to verify tokens.

   kubectl apply -f- <<EOF
   apiVersion: agentgateway.dev/v1alpha1
   kind: AgentgatewayBackend
   metadata:
     name: oidc-jwks
     namespace: agentgateway-system
   spec:
     static:
       host: login.microsoftonline.com
       port: 443
     policies:
       tls: {}
   EOF

4. Create an AgentgatewayPolicy that requires a valid token on the Claude Desktop route.

   If this route currently has a strict API key policy, remove that policy as part of the transition. Do not attach both authentication policies to the Claude Desktop route. Keep policies for other clients scoped to their own routes.

   kubectl apply -f- <<EOF
   apiVersion: agentgateway.dev/v1alpha1
   kind: AgentgatewayPolicy
   metadata:
     name: claude-desktop-jwt
     namespace: agentgateway-system
   spec:
     targetRefs:
     - group: gateway.networking.k8s.io
       kind: HTTPRoute
       name: claude-desktop
     traffic:
       jwtAuthentication:
         mode: Strict
         providers:
         - issuer: https://login.microsoftonline.com/$TENANT_ID/v2.0
           audiences:
           - $CLIENT_ID
           jwks:
             remote:
               backendRef:
                 group: agentgateway.dev
                 kind: AgentgatewayBackend
                 name: oidc-jwks
                 namespace: agentgateway-system
                 port: 443
               jwksPath: /$TENANT_ID/discovery/v2.0/keys
               cacheDuration: 5m
   EOF

   Review the following table to understand this configuration.

   Setting	Description
   mode	Set to Strict so that the proxy rejects any request that has no valid token. The default value, Optional, admits requests that carry no token at all.
   issuer	The expected iss claim. Validating the issuer alongside the signature is what ties a token to your tenant.
   audiences	The expected aud claim. For an ID token, the audience is the client ID of the application that you registered.
   jwks.remote.backendRef	The backend that hosts the JWKS endpoint, from the previous step.
   jwks.remote.jwksPath	The path to the JWKS document on that host.

   Use the issuer base URL shown in the example. Do not use the OpenID discovery-document URL, which ends in /.well-known/openid-configuration, as the issuer.

   For more detail on JWT validation, see JWT auth.

5. Give the backend its own credential. Interactive sign-in puts the identity provider token in the Authorization header, so the proxy must supply the LLM provider credential itself rather than pass a user token upstream. Follow Anthropic provider to create a secret and reference it from policies.auth on the AgentgatewayBackend resource.

6. In Claude Desktop, go to Developer → Configure Third Party Inference → Gateway and set the following fields.

   Field	Value
   Credential kind	Interactive sign-in
   Gateway base URL	Your gateway URL, as described in Get the gateway URL
   Client ID	The client ID of the application that you registered
   Issuer URL	https://login.microsoftonline.com/$TENANT_ID/v2.0
   Bearer token	ID token
   Scopes	openid profile email offline_access
   Sign-in flow	Browser for this initial test; use the Intune guide to move managed devices to Broker
   Model discovery	Off when you use a fixed model list
   Models	One or more full model IDs that the backend exposes

   Warning

   Set the bearer token type to ID token. With the access token setting, Entra ID returns a Microsoft Graph token that validation against your tenant JWKS rejects with InvalidSignature. The ID token carries the client ID as its audience, which matches the configured audience.

7. From Claude Desktop, click Test connection. Then click Apply Changes, fully quit Claude Desktop, and reopen it. A browser window opens to your identity provider. After you sign in, send a real prompt to verify that the saved configuration still works after restart.

8. Confirm that the proxy sees the authenticated identity.

   kubectl logs deployment/agentgateway-proxy -n agentgateway-system --tail=5

   Confirm that the real POST /v1/messages request returns HTTP 200 and includes jwt.sub for the signed-in user. This confirms that Claude Desktop sent the Entra ID token and that agentgateway validated it before forwarding the request.

Send custom headers

Use the Custom inference headers field to add a header to every inference request, such as a tenant identifier that a route or a policy matches on. Claude Desktop sends these headers on requests from Chat, Cowork, and Code alike.

To supply a header value that changes over time, set a credential helper instead. A credential helper is an executable that Claude Desktop runs with no arguments and that prints either a bare token or a JSON object in the form {"token": "...", "headers": {"Name": "Value"}}. Claude Desktop caches the result and re-runs the helper when the cache expires, with no prompt and no relaunch. Helper headers override custom inference headers of the same name, and a configured helper replaces any static API key. Use a helper to read a short-lived credential from a secret store.

Roll out to your organization

Configure and test one machine in developer mode first. When the connection works, click Export in the Configure Third Party Inference panel to produce a profile for your device management system, and distribute it with the tool that you already use, such as Jamf, Intune, Workspace ONE, or Group Policy. Users then receive the configuration on first launch and do not configure anything by hand.

For an end-to-end Microsoft Intune rollout with Entra ID and managed-device enforcement, see Manage Claude Desktop with Microsoft Intune.

Managed configuration takes precedence over local settings, so a user cannot point the app at a different endpoint. The delivery mechanism differs per operating system.

The following example shows the Linux form. On macOS and Windows, write every value as a string, including numbers, booleans, and nested JSON.

{
  "inferenceProvider": "gateway",
  "inferenceGatewayBaseUrl": "https://agentgateway.example.com/claude",
  "inferenceCredentialKind": "interactive",
  "inferenceGatewayOidcAuthFlow": "browser",
  "inferenceGatewayOidc": {
    "issuer": "https://login.microsoftonline.com/$TENANT_ID/v2.0",
    "clientId": "$CLIENT_ID",
    "scopes": "openid profile email offline_access",
    "bearerTokenType": "id_token"
  },
  "modelDiscoveryEnabled": false,
  "inferenceModels": ["claude-opus-5"],
  "inferenceCustomHeaders": {
    "X-Tenant-Id": "acme"
  }
}

For every available key and for the per-region profiles that a multi-region deployment needs, see the Claude Desktop configuration reference.

Verify the connection

1. Send a message in Claude Desktop, such as test.

2. Check the proxy logs to confirm traffic is flowing through agentgateway.

   kubectl logs deployment/agentgateway-proxy -n agentgateway-system --tail=5

3. If you configured gateway API key or OIDC authentication in strict mode, send a request without the Authorization header and confirm that agentgateway rejects it. This negative check verifies that the route does not admit unauthenticated requests.

Troubleshoot the connection

Cleanup

1. Remove the resources that you created.

   kubectl delete AgentgatewayPolicy claude-desktop-api-key -n agentgateway-system --ignore-not-found
   kubectl delete AgentgatewayPolicy claude-desktop-buffer -n agentgateway-system
   kubectl delete httproute claude-desktop -n agentgateway-system
   kubectl delete AgentgatewayBackend anthropic-desktop -n agentgateway-system
   kubectl delete secret claude-desktop-client-keys anthropic-secret -n agentgateway-system --ignore-not-found

2. If you set up Interactive sign-in, remove those resources too. Keep the JWKS backend if another policy uses it.

   kubectl delete AgentgatewayPolicy claude-desktop-jwt -n agentgateway-system
   kubectl delete agentgatewaybackend oidc-jwks -n agentgateway-system

3. Restore Claude Desktop to your original settings. For example, you might delete the ~/Library/Application Support/Claude-3p/ directory to remove third-party inference settings and use the default ~/Library/Application Support/Claude/ settings. For more information, see the Claude docs.

Next steps