{"slug":"use-vertex-ai-with-aperture","title":"Use Vertex AI with Aperture","tags":["tailscale"],"agent_summary":"Last validated: Apr 9, 2026","trigger_phrases":[],"runnable":false,"markdown":"\r\n# Use Vertex AI with Aperture\r\n\r\nLast validated: Apr 9, 2026\r\n\r\nAperture by Tailscaleis currently [in alpha](https://tailscale.com/docs/reference/tailscale-release-stages#alpha).\r\n\r\nConfigure a Vertex AI provider in Aperture so your team can access Google Gemini and Anthropic Claude models through Aperture. This guide walks through creating a Google Cloud service account, generating a key file, and adding the provider to your Aperture configuration.\r\n\r\nAny [LLM client configured to use Aperture](https://tailscale.com/docs/aperture/use-your-tools) can access models served by this provider. Aperture routes requests based on the model name, so you do not need to configure each client separately for Vertex AI.\r\n\r\nIf you need Gemini models without Anthropic support, consider [Vertex AI Express mode](https://tailscale.com/docs/aperture/how-to/use-vertex-ai-express) with API key authentication instead of a service account.\r\n\r\n## [Prerequisites](https://tailscale.com/docs/aperture/how-to/use-vertex-ai\\#prerequisites)\r\n\r\nBefore you begin, you need:\r\n\r\n- An Aperture instance accessible from your device. Refer to [get started with Aperture](https://tailscale.com/docs/aperture/get-started) if you have not set this up.\r\n- A Google Cloud project with the [Vertex AI API](https://console.cloud.google.com/apis/library/aiplatform.googleapis.com) enabled.\r\n- The [Google Cloud CLI](https://cloud.google.com/sdk/docs/install) (`gcloud`) installed and authenticated.\r\n- Your Aperture hostname (Tailscale's [MagicDNS](https://tailscale.com/docs/features/magicdns) provides short hostnames like `ai` in your tailnet; for example, `aperture.example.ts.net`). If you connect through ts-unplug, use `localhost:` instead.\r\n\r\n## [Step 1: Set your Google Cloud project](https://tailscale.com/docs/aperture/how-to/use-vertex-ai\\#step-1-set-your-google-cloud-project)\r\n\r\nSet the active project for the `gcloud` commands that follow. Replace `` with your Google Cloud project ID.\r\n\r\n```shell\r\ngcloud config set project \r\n```\r\n\r\n## [Step 2: Create a service account](https://tailscale.com/docs/aperture/how-to/use-vertex-ai\\#step-2-create-a-service-account)\r\n\r\nCreate a dedicated service account for Aperture to use when calling the Vertex AI API.\r\n\r\n```shell\r\ngcloud iam service-accounts create aperture-vertex \\\r\n --display-name=\"Aperture Vertex AI\"\r\n```\r\n\r\nThis creates a service account named `aperture-vertex` in your project. Aperture uses this account to authenticate with the Vertex AI API and generate bearer tokens for requests.\r\n\r\n## [Step 3: Grant IAM roles](https://tailscale.com/docs/aperture/how-to/use-vertex-ai\\#step-3-grant-iam-roles)\r\n\r\nThe service account needs two IAM roles: one to call the Vertex AI API, and one to list available models.\r\n\r\n1. Grant the `aiplatform.user` role, which lets the service account send requests to Vertex AI models:\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n```shell\r\ngcloud projects add-iam-policy-binding \\\r\n --member=\"serviceAccount:aperture-vertex@.iam.gserviceaccount.com\" \\\r\n --role=\"roles/aiplatform.user\"\r\n```\r\n\r\n2. Grant the `serviceUsageConsumer` role, which lets the service account list available models:\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n```shell\r\ngcloud projects add-iam-policy-binding \\\r\n --member=\"serviceAccount:aperture-vertex@.iam.gserviceaccount.com\" \\\r\n --role=\"roles/serviceusage.serviceUsageConsumer\"\r\n```\r\n\r\n\r\n## [Step 4: Generate a JSON key file](https://tailscale.com/docs/aperture/how-to/use-vertex-ai\\#step-4-generate-a-json-key-file)\r\n\r\nCreate a JSON key file for the service account. Aperture uses this key file to mint bearer tokens for Vertex AI requests.\r\n\r\n```shell\r\ngcloud iam service-accounts keys create aperture-vertex-key.json \\\r\n --iam-account=aperture-vertex@.iam.gserviceaccount.com\r\n```\r\n\r\nThis creates a file named `aperture-vertex-key.json` in your current directory. The file contains the private key and project metadata that Aperture needs to authenticate.\r\n\r\nStore this file securely. You cannot recover the private key if lost, and anyone with access to the file can authenticate as the service account.\r\n\r\n## [Step 5: Base64-encode the key file](https://tailscale.com/docs/aperture/how-to/use-vertex-ai\\#step-5-base64-encode-the-key-file)\r\n\r\nAperture expects the key file as a base64-encoded string in the provider configuration. Encode the key file and copy the result to your clipboard.\r\n\r\nOn macOS:\r\n\r\n```shell\r\ncat aperture-vertex-key.json | base64 | pbcopy\r\n```\r\n\r\nOn Linux:\r\n\r\n```shell\r\ncat aperture-vertex-key.json | base64 -w 0\r\n```\r\n\r\nUse the encoded string in the next step as the value for the provider's `apikey` field.\r\n\r\n## [Step 6: Configure the Vertex provider in Aperture](https://tailscale.com/docs/aperture/how-to/use-vertex-ai\\#step-6-configure-the-vertex-provider-in-aperture)\r\n\r\nAdd a Vertex provider to your Aperture configuration using the [Aperture dashboard](https://tailscale.com/docs/aperture). The following example shows the configuration with both Google and Anthropic models enabled.\r\n\r\n```json\r\n{\r\n \"providers\": {\r\n \"vertex\": {\r\n \"baseurl\": \"https://aiplatform.googleapis.com\",\r\n \"apikey\": \"keyfile::\",\r\n \"models\": [\\\r\n \"gemini-2.5-flash\",\\\r\n \"gemini-2.0-flash-exp\",\\\r\n \"claude-opus-4-6\",\\\r\n \"claude-sonnet-4-5@20250929\",\\\r\n \"claude-haiku-4-5@20251001\"\\\r\n ],\r\n \"compatibility\": {\r\n \"google_generate_content\": true,\r\n \"google_raw_predict\": true,\r\n \"experimental_gemini_cli_vertex_compat\": true\r\n }\r\n }\r\n }\r\n}\r\n```\r\n\r\nReplace `` with the base64-encoded string from the previous step. The `keyfile::` prefix tells Aperture that the value is a base64-encoded service account key file, not a plain API key. Aperture decodes the key file and extracts the `project_id`, which it uses to rewrite request paths for Vertex AI (for example, filling in the `_aperture_auto_vertex_project_id_` placeholder).\r\n\r\nYou do not need the `authorization` field when using `keyfile::` authentication. Aperture generates OAuth bearer tokens from the key file automatically, bypassing the `authorization` field.\r\n\r\nThe `compatibility` flags control which Vertex AI API formats the provider accepts:\r\n\r\n- `google_generate_content` enables the Vertex AI `generateContent` endpoint for Google-published models such as Gemini.\r\n- `google_raw_predict` enables the Vertex AI raw predict endpoint for third-party models such as Anthropic Claude.\r\n- `experimental_gemini_cli_vertex_compat` rewrites short-form Gemini CLI request paths to full Vertex AI paths and strips unsupported fields from request bodies.\r\n\r\nEnable `google_generate_content` and `google_raw_predict` if your provider serves both Google and Anthropic models. If you serve only one type, enable the corresponding flag. For the full list of compatibility flags, refer to the [provider compatibility reference](https://tailscale.com/docs/aperture/provider-compatibility).\r\n\r\nAfter configuring the provider, [grant model access](https://tailscale.com/docs/aperture/how-to/grant-model-access) to the users or groups that need the Vertex models.\r\n\r\n## [Verify the provider](https://tailscale.com/docs/aperture/how-to/use-vertex-ai\\#verify-the-provider)\r\n\r\n1. Open the Aperture dashboard and confirm the Vertex provider appears with the expected models.\r\n2. Send a test request through a connected tool, such as Claude Code or another tool configured to use the Vertex provider.\r\n3. Check the Aperture dashboard session list for a new entry corresponding to your request. The session shows the model name, token counts, and timestamp.\r\n\r\nIf the request succeeds and appears in the dashboard, your Vertex provider is configured correctly. If the request fails, refer to the [Aperture troubleshooting guide](https://tailscale.com/docs/aperture/troubleshooting).\r\n\r\n## [Manage service account keys](https://tailscale.com/docs/aperture/how-to/use-vertex-ai\\#manage-service-account-keys)\r\n\r\nList or revoke service account keys when rotating credentials or decommissioning a provider.\r\n\r\n### [List keys for the service account](https://tailscale.com/docs/aperture/how-to/use-vertex-ai\\#list-keys-for-the-service-account)\r\n\r\nRun the following command to list all keys associated with the service account:\r\n\r\n```shell\r\ngcloud iam service-accounts keys list \\\r\n --iam-account=aperture-vertex@.iam.gserviceaccount.com\r\n```\r\n\r\nThe output lists all keys for the service account. The `key-id` in the output matches the `private_key_id` field in your JSON key file.\r\n\r\n### [Revoke a key](https://tailscale.com/docs/aperture/how-to/use-vertex-ai\\#revoke-a-key)\r\n\r\nDelete a specific key by its `key-id`:\r\n\r\n```shell\r\ngcloud iam service-accounts keys delete \\\r\n --iam-account=aperture-vertex@.iam.gserviceaccount.com\r\n```\r\n\r\nAfter revoking a key, generate a new key file and update the base64-encoded value in your Aperture provider configuration. Requests that use the revoked key fail immediately.\r\n\r\n![Project Logo](https://cdn.brandfetch.io/tailscale.com/fallback/lettermark/theme/dark/h/256/w/256/icon?c=1bfwsmEH20zzEfSNTed)\r\n\r\nAsk AI\r\n\r\nreCAPTCHA\r\n\r\nRecaptcha requires verification.\r\n\r\nprotected by **reCAPTCHA**\r\n","html":"

Use Vertex AI with Aperture

\n

Last validated: Apr 9, 2026

\n

Aperture by Tailscaleis currently in alpha.

\n

Configure a Vertex AI provider in Aperture so your team can access Google Gemini and Anthropic Claude models through Aperture. This guide walks through creating a Google Cloud service account, generating a key file, and adding the provider to your Aperture configuration.

\n

Any LLM client configured to use Aperture can access models served by this provider. Aperture routes requests based on the model name, so you do not need to configure each client separately for Vertex AI.

\n

If you need Gemini models without Anthropic support, consider Vertex AI Express mode with API key authentication instead of a service account.

\n

Prerequisites

\n

Before you begin, you need:

\n
    \n
  • An Aperture instance accessible from your device. Refer to get started with Aperture if you have not set this up.
    • \n
  • A Google Cloud project with the Vertex AI API enabled.
    • \n
  • The Google Cloud CLI (gcloud) installed and authenticated.
    • \n
  • Your Aperture hostname (Tailscale's MagicDNS provides short hostnames like ai in your tailnet; for example, aperture.example.ts.net). If you connect through ts-unplug, use localhost:<PORT_NUMBER> instead.
    • \n
\n

Step 1: Set your Google Cloud project

\n

Set the active project for the gcloud commands that follow. Replace <your-project> with your Google Cloud project ID.

\n
gcloud config set project <your-project>\n
\n

Step 2: Create a service account

\n

Create a dedicated service account for Aperture to use when calling the Vertex AI API.

\n
gcloud iam service-accounts create aperture-vertex \\\r\n  --display-name=\"Aperture Vertex AI\"\n
\n

This creates a service account named aperture-vertex in your project. Aperture uses this account to authenticate with the Vertex AI API and generate bearer tokens for requests.

\n

Step 3: Grant IAM roles

\n

The service account needs two IAM roles: one to call the Vertex AI API, and one to list available models.

\n
    \n
  1. Grant the aiplatform.user role, which lets the service account send requests to Vertex AI models:
    2. \n
\n
gcloud projects add-iam-policy-binding <your-project> \\\r\n     --member=\"serviceAccount:aperture-vertex@<your-project>.iam.gserviceaccount.com\" \\\r\n     --role=\"roles/aiplatform.user\"\n
\n
    \n
  1. Grant the serviceUsageConsumer role, which lets the service account list available models:
    2. \n
\n
gcloud projects add-iam-policy-binding <your-project> \\\r\n     --member=\"serviceAccount:aperture-vertex@<your-project>.iam.gserviceaccount.com\" \\\r\n     --role=\"roles/serviceusage.serviceUsageConsumer\"\n
\n

Step 4: Generate a JSON key file

\n

Create a JSON key file for the service account. Aperture uses this key file to mint bearer tokens for Vertex AI requests.

\n
gcloud iam service-accounts keys create aperture-vertex-key.json \\\r\n  --iam-account=aperture-vertex@<your-project>.iam.gserviceaccount.com\n
\n

This creates a file named aperture-vertex-key.json in your current directory. The file contains the private key and project metadata that Aperture needs to authenticate.

\n

Store this file securely. You cannot recover the private key if lost, and anyone with access to the file can authenticate as the service account.

\n

Step 5: Base64-encode the key file

\n

Aperture expects the key file as a base64-encoded string in the provider configuration. Encode the key file and copy the result to your clipboard.

\n

On macOS:

\n
cat aperture-vertex-key.json | base64 | pbcopy\n
\n

On Linux:

\n
cat aperture-vertex-key.json | base64 -w 0\n
\n

Use the encoded string in the next step as the value for the provider's apikey field.

\n

Step 6: Configure the Vertex provider in Aperture

\n

Add a Vertex provider to your Aperture configuration using the Aperture dashboard. The following example shows the configuration with both Google and Anthropic models enabled.

\n
{\r\n  \"providers\": {\r\n    \"vertex\": {\r\n      \"baseurl\": \"https://aiplatform.googleapis.com\",\r\n      \"apikey\": \"keyfile::<base64-encoded-key>\",\r\n      \"models\": [\\\r\n        \"gemini-2.5-flash\",\\\r\n        \"gemini-2.0-flash-exp\",\\\r\n        \"claude-opus-4-6\",\\\r\n        \"claude-sonnet-4-5@20250929\",\\\r\n        \"claude-haiku-4-5@20251001\"\\\r\n      ],\r\n      \"compatibility\": {\r\n        \"google_generate_content\": true,\r\n        \"google_raw_predict\": true,\r\n        \"experimental_gemini_cli_vertex_compat\": true\r\n      }\r\n    }\r\n  }\r\n}\n
\n

Replace <base64-encoded-key> with the base64-encoded string from the previous step. The keyfile:: prefix tells Aperture that the value is a base64-encoded service account key file, not a plain API key. Aperture decodes the key file and extracts the project_id, which it uses to rewrite request paths for Vertex AI (for example, filling in the _aperture_auto_vertex_project_id_ placeholder).

\n

You do not need the authorization field when using keyfile:: authentication. Aperture generates OAuth bearer tokens from the key file automatically, bypassing the authorization field.

\n

The compatibility flags control which Vertex AI API formats the provider accepts:

\n
    \n
  • google_generate_content enables the Vertex AI generateContent endpoint for Google-published models such as Gemini.
    • \n
  • google_raw_predict enables the Vertex AI raw predict endpoint for third-party models such as Anthropic Claude.
    • \n
  • experimental_gemini_cli_vertex_compat rewrites short-form Gemini CLI request paths to full Vertex AI paths and strips unsupported fields from request bodies.
    • \n
\n

Enable google_generate_content and google_raw_predict if your provider serves both Google and Anthropic models. If you serve only one type, enable the corresponding flag. For the full list of compatibility flags, refer to the provider compatibility reference.

\n

After configuring the provider, grant model access to the users or groups that need the Vertex models.

\n

Verify the provider

\n
    \n
  1. Open the Aperture dashboard and confirm the Vertex provider appears with the expected models.
    2. \n
  2. Send a test request through a connected tool, such as Claude Code or another tool configured to use the Vertex provider.
    3. \n
  3. Check the Aperture dashboard session list for a new entry corresponding to your request. The session shows the model name, token counts, and timestamp.
    4. \n
\n

If the request succeeds and appears in the dashboard, your Vertex provider is configured correctly. If the request fails, refer to the Aperture troubleshooting guide.

\n

Manage service account keys

\n

List or revoke service account keys when rotating credentials or decommissioning a provider.

\n

List keys for the service account

\n

Run the following command to list all keys associated with the service account:

\n
gcloud iam service-accounts keys list \\\r\n  --iam-account=aperture-vertex@<your-project>.iam.gserviceaccount.com\n
\n

The output lists all keys for the service account. The key-id in the output matches the private_key_id field in your JSON key file.

\n

Revoke a key

\n

Delete a specific key by its key-id:

\n
gcloud iam service-accounts keys delete <key-id> \\\r\n  --iam-account=aperture-vertex@<your-project>.iam.gserviceaccount.com\n
\n

After revoking a key, generate a new key file and update the base64-encoded value in your Aperture provider configuration. Requests that use the revoked key fail immediately.

\n

\"Project

\n

Ask AI

\n

reCAPTCHA

\n

Recaptcha requires verification.

\n

protected by reCAPTCHA

\n"}