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 using a Claude Teams or Pro account.

Before you begin

1. Set up an agentgateway proxy.
2. Install Claude Desktop.
3. Install the Claude Code CLI (npm install -g @anthropic-ai/claude-code). This is required to run claude setup-token and obtain your bearer token.
4. Have a Claude Teams or Pro subscription.

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. No API key is needed because authentication uses your Claude subscription via OAuth.

   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
   info

   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

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.

   LoadBalancerPort-forward

   http://$INGRESS_GW_ADDRESS/claude

   Use 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.

6. Click Save Changes and restart Claude Desktop.

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

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. Restore Claude Desktop to your original settings. For example, you might delete the ~/Library/Application Support/Claude-3p/ direcotry to remove third-party inference settings and use the default ~/Library/Application Support/Claude/ settings. For more information, see the Claude docs.

Next steps