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

Claude Desktop

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. Decide how the proxy authenticates callers, and meet the requirements for that path.

   • A gateway API key, which Use a gateway API key covers. You need an Anthropic API key for the proxy to send upstream and a virtual API key for Claude Desktop.
   • A shared token from a Claude subscription, which Configure Claude Desktop covers. You need a Claude Teams or Pro subscription, and the Claude Code CLI (npm install -g @anthropic-ai/claude-code), which provides the claude setup-token command.
   • A per-user token from your identity provider, which Authenticate users with your identity provider covers. You need an OIDC provider and an Anthropic API key for the proxy to send upstream.

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 an AgentgatewayBackend for the Anthropic provider. This initial configuration omits a provider API key for the Claude subscription path. The gateway API key and interactive sign-in sections configure a separate upstream credential.

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

2. Create an AgentgatewayPolicy to raise the body buffer limit to 10 MB for the OAuth token flow.

   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: Gateway
       name: agentgateway-proxy
     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

3. Create an HTTPRoute that matches the /claude path prefix and rewrites it to / before forwarding to the backend.

   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

Configure Claude Desktop with a Claude subscription

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.

   HTTPS listenerPort-forward for local testing

   Use the hostname that your gateway certificate covers.

   https://$INGRESS_GW_HOSTNAME/claude

   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 the Credential kind dropdown, select Static API key and then in the Gateway API key field, enter the bearer token you copied in step 1. To authenticate each user with your identity provider instead of requiring users to pass the same shared token, see Authenticate users with your identity provider.

6. 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 Admin 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.

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 an application with your identity provider, and record the client ID and the issuer URL. Claude Desktop is a public client that receives the redirect on a loopback address, so configure the application accordingly.

   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 and set Allow public client flows to Yes.

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.

   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.

   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

   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. Click Apply Changes, then fully quit Claude Desktop and reopen it. A browser window opens to your identity provider. After you sign in, Claude Desktop stores the token and refreshes it in the background through the offline_access scope.

8. Confirm that the proxy sees the authenticated identity.

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

   Each request now carries the sub claim of the signed-in user.

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.

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",
  "inferenceGatewayOidc": {
    "issuer": "https://login.microsoftonline.com/$TENANT_ID/v2.0",
    "clientId": "$CLIENT_ID",
    "scopes": "openid profile email offline_access",
    "bearerTokenType": "id_token"
  },
  "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.

Cleanup

1. Remove the resources that you created.

   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

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