From eb8b8746882b4c546a26f4fea66044c6ae357945 Mon Sep 17 00:00:00 2001
From: jbaross <james.baross@konghq.com>
Date: Tue, 14 Jul 2026 16:19:36 +0100
Subject: [PATCH 1/5] initial content

---
 .../use-claude-code-with-ai-gateway-vertex.md | 167 ++++++++++++++++++
 1 file changed, 167 insertions(+)
 create mode 100644 app/_how-tos/ai-gateway/use-claude-code-with-ai-gateway-vertex.md

diff --git a/app/_how-tos/ai-gateway/use-claude-code-with-ai-gateway-vertex.md b/app/_how-tos/ai-gateway/use-claude-code-with-ai-gateway-vertex.md
new file mode 100644
index 00000000000..c0490314dd6
--- /dev/null
+++ b/app/_how-tos/ai-gateway/use-claude-code-with-ai-gateway-vertex.md
@@ -0,0 +1,167 @@
+---
+title: Route Claude CLI traffic through {{site.ai_gateway}} and Vertex AI
+permalink: /ai-gateway/use-claude-code-with-ai-gateway-vertex/
+content_type: how_to
+
+related_resources:
+  - text: "{{site.ai_gateway}}"
+    url: /ai-gateway/
+
+description: Configure {{site.ai_gateway}} to proxy Claude CLI traffic using Google Vertex AI models
+
+products:
+  - ai-gateway
+
+works_on:
+  - konnect
+
+tools:
+  - kongctl
+
+min_version:
+  ai-gateway: '2.0'
+
+tags:
+  - ai
+  - vertex-ai
+
+tldr:
+  q: How do I run Claude CLI through {{site.ai_gateway}}?
+  a: Install Claude CLI, configure its API key helper, create a Gateway Service and Route, attach the AI Proxy plugin to forward requests to Claude, enable file-log to inspect traffic, and point Claude CLI to the local proxy endpoint so all LLM requests pass through the {{site.ai_gateway}} for monitoring and control.
+
+prereqs:
+  inline:
+    - title: Vertex
+      content: |
+        Before you begin, you must get the following credentials from Google Cloud:
+
+        - **Service Account Key**: A JSON key file for a service account with Vertex AI permissions
+        - **Project ID**: Your Google Cloud project identifier
+        - **Location ID**: The region where your Vertex AI endpoint is deployed (for example, `us-central1`)
+        - **API Endpoint**: The Vertex AI API endpoint URL (typically `https://{location}-aiplatform.googleapis.com`)
+
+        Export these values as environment variables:
+        ```sh
+        export GEMINI_API_KEY="<your_gemini_api_key>"
+        export GCP_PROJECT_ID="<your-gemini-project-id>"
+        export GEMINI_LOCATION_ID="<your-gemini-location_id>"
+        export GEMINI_API_ENDPOINT="<your_gemini_api_endpoint>"
+        ```
+      icon_url: /assets/icons/vertex.svg
+    - title: Claude Code CLI
+      icon_url: /assets/icons/third-party/claude.svg
+      include_content: prereqs/claude-code
+
+---
+
+## Create an AI Provider entity
+
+
+## Create an AI Model entity
+
+
+## Verify traffic through Kong
+
+Now, we can start a {{ site.claude_code }} session that points it to the local {{site.ai_gateway}} endpoint:
+
+{:.warning}
+> Ensure that `ANTHROPIC_MODEL` matches the model you deployed in Gemini.
+
+```sh
+ANTHROPIC_BASE_URL=http://localhost:8000/anything \
+ANTHROPIC_MODEL=YOUR_VERTEX_MODEL \
+claude
+```
+
+{{ site.claude_code }} asks for permission before it runs tools or interacts with files:
+
+```text
+I'll need permission to work with your files.
+
+This means I can:
+- Read any file in this folder
+- Create, edit, or delete files
+- Run commands (like npm, git, tests, ls, rm)
+- Use tools defined in .mcp.json
+
+Learn more ( https://docs.claude.com/s/claude-code-security )
+
+❯ 1. Yes, continue
+2. No, exit
+```
+{:.no-copy-code}
+
+Select **Yes, continue**. The session starts. Ask a simple question to confirm that requests reach {{site.ai_gateway}}.
+
+```text
+Tell me about Anna Komnene's Alexiad.
+```
+
+{{ site.claude_code }} might prompt you approve its web search for answering the question. When you select **Yes**, {{ site.claude }} will produce a full-length response to your request:
+
+```text
+Anna Komnene (1083-1153?) was a Byzantine princess, scholar, physician,
+hospital administrator, and historian. She is known for writing the
+Alexiad, a historical account of the reign of her father, Emperor Alexios
+I Komnenos (r. 1081-1118). The Alexiad is a valuable primary source for
+understanding Byzantine history and the First Crusade.
+```
+{:.no-copy-code}
+
+Next, inspect the {{site.ai_gateway}} logs to verify that the traffic was proxied through it:
+
+```sh
+docker exec kong-quickstart-gateway cat /tmp/claude.json | jq
+```
+
+You should find an entry that shows the upstream request made by {{ site.claude_code }}. A typical log record looks like this:
+
+```json
+{
+  ...
+  "method": "POST",
+  "headers": {
+    "user-agent": "claude-cli/2.0.37 (external, cli)",
+    "content-type": "application/json"
+  },
+  ...
+  "ai": {
+    "proxy": {
+      "tried_targets": [
+        {
+          "provider": "gemini",
+          "model": "gemini-2.0-flash",
+          "port": 443,
+          "upstream_scheme": "https",
+          "host": "us-central1-aiplatform.googleapis.com",
+          "upstream_uri": "/v1/projects/example-project-id/locations/us-central1/publishers/google/models/gemini-2.0-flash:generateContent",
+          "route_type": "llm/v1/chat",
+          "ip": "xxx.xxx.xxx.xxx"
+        }
+      ],
+      "meta": {
+        "request_model": "gemini-2.5-flash",
+        "request_mode": "oneshot",
+        "response_model": "gemini-2.5-flash",
+        "provider_name": "gemini",
+        "llm_latency": 1694,
+        "plugin_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
+      },
+      "usage": {
+        "completion_tokens": 19,
+        "completion_tokens_details": {},
+        "total_tokens": 11203,
+        "cost": 0,
+        "time_per_token": 85.157894736842,
+        "time_to_first_token": 2546,
+        "prompt_tokens": 11184,
+        "prompt_tokens_details": {}
+      }
+    }
+  }
+  ...
+}
+```
+{:.no-copy-code}
+
+This output confirms that {{ site.claude_code }} routed the request through {{site.ai_gateway}} using the `gemini-2.5-flash` model we selected while starting the {{ site.claude_code }} session.

From 193b6afa6db63a9f0e8e23c7ae2af7bef87919d8 Mon Sep 17 00:00:00 2001
From: jbaross <james.baross@konghq.com>
Date: Tue, 14 Jul 2026 16:51:59 +0100
Subject: [PATCH 2/5] initial configs

---
 .../use-claude-code-with-ai-gateway-vertex.md | 128 +++++++++---------
 1 file changed, 67 insertions(+), 61 deletions(-)

diff --git a/app/_how-tos/ai-gateway/use-claude-code-with-ai-gateway-vertex.md b/app/_how-tos/ai-gateway/use-claude-code-with-ai-gateway-vertex.md
index c0490314dd6..48944c253bf 100644
--- a/app/_how-tos/ai-gateway/use-claude-code-with-ai-gateway-vertex.md
+++ b/app/_how-tos/ai-gateway/use-claude-code-with-ai-gateway-vertex.md
@@ -46,6 +46,7 @@ prereqs:
         export GCP_PROJECT_ID="<your-gemini-project-id>"
         export GEMINI_LOCATION_ID="<your-gemini-location_id>"
         export GEMINI_API_ENDPOINT="<your_gemini_api_endpoint>"
+        export GCP_SERVICE_ACCOUNT="<your_account_json>"
         ```
       icon_url: /assets/icons/vertex.svg
     - title: Claude Code CLI
@@ -56,9 +57,74 @@ prereqs:
 
 ## Create an AI Provider entity
 
+```sh
+kongctl apply -f - --auto-approve --pat "$KONNECT_TOKEN" <<EOF
+_defaults:
+  kongctl:
+    namespace: ai-gateway-get-started
+
+ai_gateways:
+  - ref: ai-quickstart
+    name: ai-quickstart
+    display_name: "ai-quickstart"
+
+ai_gateway_model_providers:
+  - ref: vertex-prod
+    name: vertex-prod
+    display_name: "Google Vertex Prod"
+    ai_gateway: ai-quickstart
+    type: vertex
+    config:
+      auth:
+        type: gcp
+        service_account_json: !env GCP_SERVICE_ACCOUNT
+EOF
+```
+
+In this example, we're setting up the AI Model Provider with:
 
 ## Create an AI Model entity
 
+Create an [AI Model](/ai-gateway/entities/ai-model/) entity to declare which upstream models are available, configure how client requests are routed, and specify which AI Provider to use:
+
+```sh
+kongctl apply -f - --auto-approve --pat "$KONNECT_TOKEN" <<EOF
+_defaults:
+  kongctl:
+    namespace: ai-gateway-get-started
+
+ai_gateways:
+  - ref: ai-quickstart
+    name: ai-quickstart
+    display_name: "ai-quickstart"
+
+ai_gateway_models:
+  - ref: claude-code-vertex-sonnet
+    type: model
+    name: claude-code-vertex-sonnet
+    display_name: "Claude Code - Vertex - Sonnet 4.6"
+    ai_gateway: ai-quickstart
+    enabled: true
+    config:
+      route:
+        paths:
+        - /
+      model:
+        alias: "claude-code-vertex-sonnet"
+    formats:
+    - type: anthropic
+    target_models:
+    - name: claude-sonnet-4-6
+      provider: vertex-prod
+      config:
+        type: vertex
+        upstream_url: !env VERTEX_UPSTREAM_URL
+    capabilities:
+    - generate
+EOF
+```
+
+In this example, we're setting up the AI Model with:
 
 ## Verify traffic through Kong
 
@@ -68,9 +134,7 @@ Now, we can start a {{ site.claude_code }} session that points it to the local {
 > Ensure that `ANTHROPIC_MODEL` matches the model you deployed in Gemini.
 
 ```sh
-ANTHROPIC_BASE_URL=http://localhost:8000/anything \
-ANTHROPIC_MODEL=YOUR_VERTEX_MODEL \
-claude
+ANTHROPIC_BASE_URL=http://localhost:8000/ claude --model 'claude-code-vertex-sonnet'
 ```
 
 {{ site.claude_code }} asks for permission before it runs tools or interacts with files:
@@ -107,61 +171,3 @@ I Komnenos (r. 1081-1118). The Alexiad is a valuable primary source for
 understanding Byzantine history and the First Crusade.
 ```
 {:.no-copy-code}
-
-Next, inspect the {{site.ai_gateway}} logs to verify that the traffic was proxied through it:
-
-```sh
-docker exec kong-quickstart-gateway cat /tmp/claude.json | jq
-```
-
-You should find an entry that shows the upstream request made by {{ site.claude_code }}. A typical log record looks like this:
-
-```json
-{
-  ...
-  "method": "POST",
-  "headers": {
-    "user-agent": "claude-cli/2.0.37 (external, cli)",
-    "content-type": "application/json"
-  },
-  ...
-  "ai": {
-    "proxy": {
-      "tried_targets": [
-        {
-          "provider": "gemini",
-          "model": "gemini-2.0-flash",
-          "port": 443,
-          "upstream_scheme": "https",
-          "host": "us-central1-aiplatform.googleapis.com",
-          "upstream_uri": "/v1/projects/example-project-id/locations/us-central1/publishers/google/models/gemini-2.0-flash:generateContent",
-          "route_type": "llm/v1/chat",
-          "ip": "xxx.xxx.xxx.xxx"
-        }
-      ],
-      "meta": {
-        "request_model": "gemini-2.5-flash",
-        "request_mode": "oneshot",
-        "response_model": "gemini-2.5-flash",
-        "provider_name": "gemini",
-        "llm_latency": 1694,
-        "plugin_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
-      },
-      "usage": {
-        "completion_tokens": 19,
-        "completion_tokens_details": {},
-        "total_tokens": 11203,
-        "cost": 0,
-        "time_per_token": 85.157894736842,
-        "time_to_first_token": 2546,
-        "prompt_tokens": 11184,
-        "prompt_tokens_details": {}
-      }
-    }
-  }
-  ...
-}
-```
-{:.no-copy-code}
-
-This output confirms that {{ site.claude_code }} routed the request through {{site.ai_gateway}} using the `gemini-2.5-flash` model we selected while starting the {{ site.claude_code }} session.

From 29a6771f6602dc4354be19ba337ff22727a591d2 Mon Sep 17 00:00:00 2001
From: jbaross <james.baross@konghq.com>
Date: Tue, 14 Jul 2026 16:57:20 +0100
Subject: [PATCH 3/5] initial configs

---
 .../ai-gateway/use-claude-code-with-ai-gateway-vertex.md | 9 +++------
 1 file changed, 3 insertions(+), 6 deletions(-)

diff --git a/app/_how-tos/ai-gateway/use-claude-code-with-ai-gateway-vertex.md b/app/_how-tos/ai-gateway/use-claude-code-with-ai-gateway-vertex.md
index 48944c253bf..a973144c9b2 100644
--- a/app/_how-tos/ai-gateway/use-claude-code-with-ai-gateway-vertex.md
+++ b/app/_how-tos/ai-gateway/use-claude-code-with-ai-gateway-vertex.md
@@ -42,11 +42,8 @@ prereqs:
 
         Export these values as environment variables:
         ```sh
-        export GEMINI_API_KEY="<your_gemini_api_key>"
-        export GCP_PROJECT_ID="<your-gemini-project-id>"
-        export GEMINI_LOCATION_ID="<your-gemini-location_id>"
-        export GEMINI_API_ENDPOINT="<your_gemini_api_endpoint>"
-        export GCP_SERVICE_ACCOUNT="<your_account_json>"
+        export VERTEX_UPSTREAM_URL="<your_upstream_url>"
+        export GCP_SERVICE_ACCOUNT_JSON="<your_account_json>"
         ```
       icon_url: /assets/icons/vertex.svg
     - title: Claude Code CLI
@@ -77,7 +74,7 @@ ai_gateway_model_providers:
     config:
       auth:
         type: gcp
-        service_account_json: !env GCP_SERVICE_ACCOUNT
+        service_account_json: !env GCP_SERVICE_ACCOUNT_JSON
 EOF
 ```
 

From 8a2e2a1b94a8155c2c2a2bac5b8764036d904983 Mon Sep 17 00:00:00 2001
From: jbaross <james.baross@konghq.com>
Date: Tue, 14 Jul 2026 17:06:54 +0100
Subject: [PATCH 4/5] whitespace fix

---
 .../use-claude-code-with-ai-gateway-vertex.md    | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/app/_how-tos/ai-gateway/use-claude-code-with-ai-gateway-vertex.md b/app/_how-tos/ai-gateway/use-claude-code-with-ai-gateway-vertex.md
index a973144c9b2..9c6566ecc4c 100644
--- a/app/_how-tos/ai-gateway/use-claude-code-with-ai-gateway-vertex.md
+++ b/app/_how-tos/ai-gateway/use-claude-code-with-ai-gateway-vertex.md
@@ -109,15 +109,15 @@ ai_gateway_models:
       model:
         alias: "claude-code-vertex-sonnet"
     formats:
-    - type: anthropic
-    target_models:
-    - name: claude-sonnet-4-6
-      provider: vertex-prod
-      config:
-        type: vertex
-        upstream_url: !env VERTEX_UPSTREAM_URL
+      - type: anthropic
+    targets:
+      - name: claude-sonnet-4-6
+        provider: vertex-prod
+        config:
+          type: vertex
+          upstream_url: !env VERTEX_UPSTREAM_URL
     capabilities:
-    - generate
+      - generate
 EOF
 ```
 

From f04b6cdc88bc476899fed542023ba2dedc113596 Mon Sep 17 00:00:00 2001
From: jbaross <james.baross@konghq.com>
Date: Tue, 14 Jul 2026 18:03:01 +0100
Subject: [PATCH 5/5] initial claude configs

---
 .../use-claude-code-with-ai-gateway-vertex.md | 63 ++++++++++++-------
 1 file changed, 39 insertions(+), 24 deletions(-)

diff --git a/app/_how-tos/ai-gateway/use-claude-code-with-ai-gateway-vertex.md b/app/_how-tos/ai-gateway/use-claude-code-with-ai-gateway-vertex.md
index 9c6566ecc4c..a10ff91d0ef 100644
--- a/app/_how-tos/ai-gateway/use-claude-code-with-ai-gateway-vertex.md
+++ b/app/_how-tos/ai-gateway/use-claude-code-with-ai-gateway-vertex.md
@@ -26,8 +26,8 @@ tags:
   - vertex-ai
 
 tldr:
-  q: How do I run Claude CLI through {{site.ai_gateway}}?
-  a: Install Claude CLI, configure its API key helper, create a Gateway Service and Route, attach the AI Proxy plugin to forward requests to Claude, enable file-log to inspect traffic, and point Claude CLI to the local proxy endpoint so all LLM requests pass through the {{site.ai_gateway}} for monitoring and control.
+  q: How do I run Claude CLI through {{site.ai_gateway}} against a Vertex AI model?
+  a: Create an AI Provider entity to store your GCP service account credentials, create an AI Model entity with an Anthropic-compatible format that routes to a Gemini model on Vertex AI through that provider, then point Claude CLI's `ANTHROPIC_BASE_URL` at your local {{site.ai_gateway}} endpoint so all LLM requests pass through the gateway for monitoring and control.
 
 prereqs:
   inline:
@@ -42,8 +42,10 @@ prereqs:
 
         Export these values as environment variables:
         ```sh
-        export VERTEX_UPSTREAM_URL="<your_upstream_url>"
-        export GCP_SERVICE_ACCOUNT_JSON="<your_account_json>"
+        export GEMINI_API_KEY="<your_gemini_api_key>"
+        export GCP_PROJECT_ID="<your-gemini-project-id>"
+        export GEMINI_LOCATION_ID="<your-gemini-location_id>"
+        export GEMINI_API_ENDPOINT="<your_gemini_api_endpoint>"
         ```
       icon_url: /assets/icons/vertex.svg
     - title: Claude Code CLI
@@ -54,6 +56,8 @@ prereqs:
 
 ## Create an AI Provider entity
 
+Create an [AI Model Provider](/ai-gateway/entities/ai-model-provider/) entity to define your connection to Vertex AI and store your GCP service account credentials:
+
 ```sh
 kongctl apply -f - --auto-approve --pat "$KONNECT_TOKEN" <<EOF
 _defaults:
@@ -66,20 +70,25 @@ ai_gateways:
     display_name: "ai-quickstart"
 
 ai_gateway_model_providers:
-  - ref: vertex-prod
-    name: vertex-prod
-    display_name: "Google Vertex Prod"
+  - ref: my-vertex-account
     ai_gateway: ai-quickstart
+    name: my-vertex-account
+    display_name: "my-vertex-account"
     type: vertex
     config:
       auth:
         type: gcp
-        service_account_json: !env GCP_SERVICE_ACCOUNT_JSON
+        use_gcp_service_account: true
+        service_account_json: !env GEMINI_API_KEY
 EOF
 ```
 
 In this example, we're setting up the AI Model Provider with:
 
+* `type: vertex`: Specifies that this provider connects to Google Cloud Vertex AI.
+* `name: my-vertex-account`: A unique identifier that AI Models will reference to route requests through this provider.
+* `config.auth`: Authenticates to Vertex AI with a GCP service account. `use_gcp_service_account: true` tells {{site.ai_gateway}} to authenticate using service account credentials, and `service_account_json: !env GEMINI_API_KEY` loads the service account JSON key from your environment at apply time instead of embedding it in the YAML. `kongctl` redacts it in plan and diff output. {{site.ai_gateway}} securely manages this credential and injects it into upstream requests automatically, eliminating the need for clients to pass credentials.
+
 ## Create an AI Model entity
 
 Create an [AI Model](/ai-gateway/entities/ai-model/) entity to declare which upstream models are available, configure how client requests are routed, and specify which AI Provider to use:
@@ -96,26 +105,28 @@ ai_gateways:
     display_name: "ai-quickstart"
 
 ai_gateway_models:
-  - ref: claude-code-vertex-sonnet
-    type: model
-    name: claude-code-vertex-sonnet
-    display_name: "Claude Code - Vertex - Sonnet 4.6"
+  - ref: my-claude-vertex
     ai_gateway: ai-quickstart
-    enabled: true
+    name: my-claude-vertex
+    display_name: "my-claude-vertex"
+    type: model
+    formats:
+      - type: anthropic
     config:
       route:
         paths:
-        - /
+          - /
       model:
-        alias: "claude-code-vertex-sonnet"
-    formats:
-      - type: anthropic
+        alias: my-claude-vertex
     targets:
-      - name: claude-sonnet-4-6
-        provider: vertex-prod
+      - name: gemini-2.5-flash
+        provider: my-vertex-account
         config:
           type: vertex
-          upstream_url: !env VERTEX_UPSTREAM_URL
+          api_endpoint: !env GEMINI_API_ENDPOINT
+          project_id: !env GCP_PROJECT_ID
+          location_id: !env GEMINI_LOCATION_ID
+    policies: []
     capabilities:
       - generate
 EOF
@@ -123,15 +134,19 @@ EOF
 
 In this example, we're setting up the AI Model with:
 
+* `type: model`: Specifies this is a synchronous model for request/response workloads.
+* `name: my-claude-vertex`: A unique identifier for this model.
+* `formats: [type: anthropic]`: Declares that this model accepts requests in Anthropic-compatible format, matching what {{ site.claude_code }} sends natively, even though the upstream model is a Gemini model on Vertex AI.
+* `config.route.paths: [/]`: Configures the custom base path where this model's Routes will be accessible. Setting this to a unique value avoids clashes when you have multiple AI Models.
+* `capabilities: [generate]`: Enables the text generation capability. For a model using the `anthropic` format, the `generate` capability creates a `/messages` endpoint matching Anthropic's native Messages API, so combined with your base path, clients send requests to `/v1/messages`.
+* `targets`: Specifies which upstream AI Provider model to route requests to. Here, `provider: my-vertex-account` references the AI Provider we created earlier, and `name: gemini-2.5-flash` specifies which Gemini model to call upstream. `config.api_endpoint`, `config.project_id`, and `config.location_id` identify the specific Vertex AI deployment to route requests to.
+
 ## Verify traffic through Kong
 
 Now, we can start a {{ site.claude_code }} session that points it to the local {{site.ai_gateway}} endpoint:
 
-{:.warning}
-> Ensure that `ANTHROPIC_MODEL` matches the model you deployed in Gemini.
-
 ```sh
-ANTHROPIC_BASE_URL=http://localhost:8000/ claude --model 'claude-code-vertex-sonnet'
+ANTHROPIC_BASE_URL=http://localhost:8000/ ANTHROPIC_MODEL=my-claude-vertex claude
 ```
 
 {{ site.claude_code }} asks for permission before it runs tools or interacts with files: