{"slug":"set-up-a-vertex-ai-express-provider","title":"Set up a Vertex AI Express provider","tags":["tailscale"],"agent_summary":"Last validated: Apr 9, 2026","trigger_phrases":[],"runnable":false,"markdown":"\r\n# Set up a Vertex AI Express provider\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 Express provider in Aperture so your team can access Google Gemini models through your tailnet. Vertex AI Express uses API key authentication instead of a service account, which simplifies setup when you need Gemini models without Anthropic support.\r\n\r\nIf you also need Anthropic Claude models through Vertex AI, use a [service account provider](https://tailscale.com/docs/aperture/how-to/use-vertex-ai) instead. The Vertex AI raw predict endpoint required by Anthropic models does not support API key authentication.\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\n## [Prerequisites](https://tailscale.com/docs/aperture/how-to/use-vertex-ai-express\\#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- 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`).\r\n\r\n## [Step 1: Create an API key](https://tailscale.com/docs/aperture/how-to/use-vertex-ai-express\\#step-1-create-an-api-key)\r\n\r\nCreate a Google Cloud API key for your project using the Google Cloud console or the `gcloud` CLI.\r\n\r\n### [Google Cloud console](https://tailscale.com/docs/aperture/how-to/use-vertex-ai-express\\#google-cloud-console)\r\n\r\nFollow these steps to create an API key from the console:\r\n\r\n1. Open the [API credentials page](https://console.cloud.google.com/apis/credentials) for your project.\r\n2. Select **Create credentials**, then **API key**.\r\n3. Copy the generated key.\r\n\r\n### [gcloud CLI](https://tailscale.com/docs/aperture/how-to/use-vertex-ai-express\\#gcloud-cli)\r\n\r\nRun the following command to create an API key:\r\n\r\n```shell\r\ngcloud services api-keys create --display-name=\"Aperture Vertex AI Express\"\r\n```\r\n\r\nThe command outputs the key string. Copy it for the next step.\r\n\r\n(Optional) Restrict the API key to the Vertex AI API. An unrestricted key works but has a broader scope than necessary.\r\n\r\n## [Step 2: Configure the provider](https://tailscale.com/docs/aperture/how-to/use-vertex-ai-express\\#step-2-configure-the-provider)\r\n\r\nAdd a Vertex provider to your Aperture configuration using the [Aperture dashboard](https://tailscale.com/docs/aperture). Set the authorization type to `x-goog-api-key` and provide your API key directly (no `keyfile::` prefix).\r\n\r\nThe following example shows a Vertex Express provider configuration:\r\n\r\n```json\r\n{\r\n \"providers\": {\r\n \"vertex-express\": {\r\n \"baseurl\": \"https://aiplatform.googleapis.com\",\r\n \"authorization\": \"x-goog-api-key\",\r\n \"apikey\": \"\",\r\n \"models\": [\\\r\n \"gemini-2.5-flash\",\\\r\n \"gemini-2.5-pro\",\\\r\n \"gemini-2.5-flash-lite\"\\\r\n ],\r\n \"compatibility\": {\r\n \"google_generate_content\": true\r\n }\r\n }\r\n }\r\n}\r\n```\r\n\r\nReplace `` with the API key from the previous step.\r\n\r\nThe `compatibility` section enables `google_generate_content`, which routes requests through the Vertex AI generateContent endpoint used by Google-published models such as Gemini.\r\n\r\nDo not enable `google_raw_predict`. Third-party models (such as Anthropic Claude) use the raw predict endpoint, which requires service account authentication. API key authentication does not support this endpoint.\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 Gemini models.\r\n\r\n## [Verify the provider](https://tailscale.com/docs/aperture/how-to/use-vertex-ai-express\\#verify-the-provider)\r\n\r\nAfter configuring the provider, confirm it works:\r\n\r\n1. Open the Aperture dashboard and confirm the Vertex Express provider appears with the expected models.\r\n2. Send a test request through a connected tool, such as a Gemini CLI instance or another tool pointed at the Vertex AI endpoint.\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 fails, check that the API key is correct and that the Vertex AI API is enabled in your Google Cloud project. For additional help, refer to the [Aperture troubleshooting guide](https://tailscale.com/docs/aperture/troubleshooting).\r\n\r\n## [Limitations compared to service account providers](https://tailscale.com/docs/aperture/how-to/use-vertex-ai-express\\#limitations-compared-to-service-account-providers)\r\n\r\nVertex AI Express mode requires less configuration but has fewer features than a service account provider:\r\n\r\n- **Google models only.** Anthropic Claude models on Vertex AI use the raw predict endpoint, which requires service account authentication. Express mode does not support `google_raw_predict`.\r\n- **Gemini CLI works, but without `experimental_gemini_cli_vertex_compat`.** Gemini CLI works with Express mode through the standard OpenAI-compatible endpoint. However, the `experimental_gemini_cli_vertex_compat` flag requires a keyfile-based provider to extract the project ID, so Express mode providers cannot use it. If you need Gemini CLI to use the Vertex-specific endpoint, use a [service account provider](https://tailscale.com/docs/aperture/how-to/use-vertex-ai) instead.\r\n- **No automatic project ID.** Clients that rely on Aperture to fill in the Vertex project ID from the keyfile (the `_aperture_auto_vertex_project_id_` placeholder) must instead provide the project ID directly in the request path.\r\n\r\n## [Rotate the API key](https://tailscale.com/docs/aperture/how-to/use-vertex-ai-express\\#rotate-the-api-key)\r\n\r\nTo rotate the API key, create a new key, update the Aperture provider configuration, then delete the old key.\r\n\r\n1. Create a new API key using the steps in [Step 1](https://tailscale.com/docs/aperture/how-to/use-vertex-ai-express#step-1-create-an-api-key).\r\n\r\n2. Update the `apikey` field in your Aperture provider configuration with the new key.\r\n\r\n3. Delete the old API key from the [API credentials page](https://console.cloud.google.com/apis/credentials) or with the `gcloud` CLI:\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n```shell\r\ngcloud services api-keys delete \r\n```\r\n\r\n\r\nRequests that use the deleted key fail immediately after you delete it.\r\n","html":"

Set up a Vertex AI Express provider

\n

Last validated: Apr 9, 2026

\n

Aperture by Tailscaleis currently in alpha.

\n

Configure a Vertex AI Express provider in Aperture so your team can access Google Gemini models through your tailnet. Vertex AI Express uses API key authentication instead of a service account, which simplifies setup when you need Gemini models without Anthropic support.

\n

If you also need Anthropic Claude models through Vertex AI, use a service account provider instead. The Vertex AI raw predict endpoint required by Anthropic models does not support API key authentication.

\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

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
  • Your Aperture hostname (Tailscale's MagicDNS provides short hostnames like ai in your tailnet; for example, aperture.example.ts.net).
    • \n
\n

Step 1: Create an API key

\n

Create a Google Cloud API key for your project using the Google Cloud console or the gcloud CLI.

\n

Google Cloud console

\n

Follow these steps to create an API key from the console:

\n
    \n
  1. Open the API credentials page for your project.
    2. \n
  2. Select Create credentials, then API key.
    3. \n
  3. Copy the generated key.
    4. \n
\n

gcloud CLI

\n

Run the following command to create an API key:

\n
gcloud services api-keys create --display-name=\"Aperture Vertex AI Express\"\n
\n

The command outputs the key string. Copy it for the next step.

\n

(Optional) Restrict the API key to the Vertex AI API. An unrestricted key works but has a broader scope than necessary.

\n

Step 2: Configure the provider

\n

Add a Vertex provider to your Aperture configuration using the Aperture dashboard. Set the authorization type to x-goog-api-key and provide your API key directly (no keyfile:: prefix).

\n

The following example shows a Vertex Express provider configuration:

\n
{\r\n  \"providers\": {\r\n    \"vertex-express\": {\r\n      \"baseurl\": \"https://aiplatform.googleapis.com\",\r\n      \"authorization\": \"x-goog-api-key\",\r\n      \"apikey\": \"<your-api-key>\",\r\n      \"models\": [\\\r\n        \"gemini-2.5-flash\",\\\r\n        \"gemini-2.5-pro\",\\\r\n        \"gemini-2.5-flash-lite\"\\\r\n      ],\r\n      \"compatibility\": {\r\n        \"google_generate_content\": true\r\n      }\r\n    }\r\n  }\r\n}\n
\n

Replace <your-api-key> with the API key from the previous step.

\n

The compatibility section enables google_generate_content, which routes requests through the Vertex AI generateContent endpoint used by Google-published models such as Gemini.

\n

Do not enable google_raw_predict. Third-party models (such as Anthropic Claude) use the raw predict endpoint, which requires service account authentication. API key authentication does not support this endpoint.

\n

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

\n

Verify the provider

\n

After configuring the provider, confirm it works:

\n
    \n
  1. Open the Aperture dashboard and confirm the Vertex Express provider appears with the expected models.
    2. \n
  2. Send a test request through a connected tool, such as a Gemini CLI instance or another tool pointed at the Vertex AI endpoint.
    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 fails, check that the API key is correct and that the Vertex AI API is enabled in your Google Cloud project. For additional help, refer to the Aperture troubleshooting guide.

\n

Limitations compared to service account providers

\n

Vertex AI Express mode requires less configuration but has fewer features than a service account provider:

\n
    \n
  • Google models only. Anthropic Claude models on Vertex AI use the raw predict endpoint, which requires service account authentication. Express mode does not support google_raw_predict.
    • \n
  • Gemini CLI works, but without experimental_gemini_cli_vertex_compat. Gemini CLI works with Express mode through the standard OpenAI-compatible endpoint. However, the experimental_gemini_cli_vertex_compat flag requires a keyfile-based provider to extract the project ID, so Express mode providers cannot use it. If you need Gemini CLI to use the Vertex-specific endpoint, use a service account provider instead.
    • \n
  • No automatic project ID. Clients that rely on Aperture to fill in the Vertex project ID from the keyfile (the _aperture_auto_vertex_project_id_ placeholder) must instead provide the project ID directly in the request path.
    • \n
\n

Rotate the API key

\n

To rotate the API key, create a new key, update the Aperture provider configuration, then delete the old key.

\n
    \n
  1. \n

    Create a new API key using the steps in Step 1.

    \n
    2. \n
  2. \n

    Update the apikey field in your Aperture provider configuration with the new key.

    \n
    3. \n
  3. \n

    Delete the old API key from the API credentials page or with the gcloud CLI:

    \n
    4. \n
\n
gcloud services api-keys delete <old-key-id>\n
\n

Requests that use the deleted key fail immediately after you delete it.

\n"}