# How to Configure Headroom for Google AI Platform (Vertex AI)

> Learn how to configure Headroom for Google AI Platform Vertex AI. This transparent proxy adds compression, caching, and cost controls without code changes.

- Repository: [Tejas Chopra/headroom](https://github.com/chopratejas/headroom)
- Tags: how-to-guide
- Published: 2026-06-15

---

**Headroom acts as a transparent proxy for Google AI Platform (Vertex AI) by rewriting requests to regional endpoints while preserving bearer tokens, enabling you to add compression, caching, and cost controls without modifying existing Vertex AI client code.**

The open-source `chopratejas/headroom` repository provides a lightweight proxy layer that intercepts calls to Vertex AI’s publisher endpoints. By configuring Headroom to target your specific Google Cloud region, you can retain the standard Vertex AI REST contract while unlocking Headroom’s transforms, context caching, and spend-management features.

## Set the Vertex AI Regional Endpoint

To route traffic through Headroom, you must specify which Vertex AI regional host the proxy should forward requests to. This configuration determines where your Gemini and other generative models are hosted.

### Command-Line Configuration

Pass the regional endpoint URL using the `--vertex-api-url` flag when starting the proxy. This is defined in [`headroom/providers/google.py`](https://github.com/chopratejas/headroom/blob/main/headroom/providers/google.py) where the `GoogleProvider` class registers provider-specific options.

```bash
headroom proxy \
  --port 8787 \
  --vertex-api-url https://us-central1-aiplatform.googleapis.com

```

### Environment Variable Method

Alternatively, export `VERTEX_TARGET_API_URL` before starting the proxy. The `GoogleProvider` class checks this environment variable during initialization, as documented in [`wiki/vertex.md`](https://github.com/chopratejas/headroom/blob/main/wiki/vertex.md).

```bash
export VERTEX_TARGET_API_URL=https://us-central1-aiplatform.googleapis.com
headroom proxy --port 8787

```

## Authenticate with Google Cloud IAM

Vertex AI requires a valid Google bearer token for all requests. Headroom forwards this token unchanged to the downstream service, maintaining standard Google Cloud authentication flows.

For local development, generate a short-lived access token using the Google Cloud SDK:

```bash
export ACCESS_TOKEN="$(gcloud auth print-access-token)"

```

In production deployments, Headroom supports Application Default Credentials (ADC) and will pass through tokens provided in the `Authorization` header without modification, as implemented in [`headroom/utils.py`](https://github.com/chopratejas/headroom/blob/main/headroom/utils.py).

## Route Requests Through the Proxy

Once the proxy is running on `http://127.0.0.1:8787`, send requests using the standard Vertex AI path structure. Headroom rewrites the URL internally while preserving the request body schema required by Vertex AI methods like `generateContent`, `streamGenerateContent`, and `countTokens`.

```bash
curl -sS \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  http://127.0.0.1:8787/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/gemini-2.0-flash:generateContent \
  -d '{
        "contents": [
          {
            "role": "user",
            "parts": [{"text": "Summarize this repository in one paragraph."}]
          }
        ]
      }'

```

The proxy forwards the `contents` schema unchanged, so existing Vertex AI client libraries continue to function without code changes.

## Integrate with the Python SDK and GoogleProvider

For programmatic access, instantiate `HeadroomClient` with `GoogleProvider` to enable Headroom-specific optimizations while using your existing Vertex AI client.

```python
from headroom import HeadroomClient, GoogleProvider
from google.generativeai import GenerativeModel

client = HeadroomClient(
    original_client=GenerativeModel("gemini-2.0-flash"),
    provider=GoogleProvider(),
)

response = client.chat.completions.create(
    model="gemini-2.0-flash",
    messages=[{"role": "user", "content": "Explain Headroom."}],
    headroom_mode="optimize",
)
print(response.choices[0].message.content)

```

The `GoogleProvider` class in [`headroom/providers/google.py`](https://github.com/chopratejas/headroom/blob/main/headroom/providers/google.py) automatically respects the `VERTEX_TARGET_API_URL` environment variable and enables context caching options specific to Google AI Platform.

## Key Implementation Files

Understanding these source files helps debug configuration issues:

- **[`headroom/providers/google.py`](https://github.com/chopratejas/headroom/blob/main/headroom/providers/google.py)** – Implements `GoogleProvider` and registers Vertex AI-specific configuration flags like `enable_context_caching`.
- **[`wiki/vertex.md`](https://github.com/chopratejas/headroom/blob/main/wiki/vertex.md)** – Documents the complete Vertex AI proxy configuration, authentication patterns, and supported API actions.
- **[`wiki/configuration.md`](https://github.com/chopratejas/headroom/blob/main/wiki/configuration.md)** – Lists general environment variables and proxy settings applicable to all providers.
- **[`headroom/utils.py`](https://github.com/chopratejas/headroom/blob/main/headroom/utils.py)** – Contains helper functions for request routing and token handling that ensure bearer tokens are preserved when forwarding to Vertex AI.

## Summary

- **Configure the endpoint** using `--vertex-api-url` or `VERTEX_TARGET_API_URL` to point to your Google Cloud region.
- **Authenticate** using standard `gcloud auth print-access-token` or ADC flows; Headroom passes tokens through transparently.
- **Route traffic** to `http://127.0.0.1:8787` using standard Vertex AI REST paths without modifying request bodies.
- **Use `GoogleProvider`** in the Python SDK to enable Headroom transforms while maintaining compatibility with existing Vertex AI code.
- **Reference** [`headroom/providers/google.py`](https://github.com/chopratejas/headroom/blob/main/headroom/providers/google.py) and [`wiki/vertex.md`](https://github.com/chopratejas/headroom/blob/main/wiki/vertex.md) for implementation details and provider-specific options.

## Frequently Asked Questions

### Does Headroom modify the Vertex AI request schema?

No. According to the [`headroom/utils.py`](https://github.com/chopratejas/headroom/blob/main/headroom/utils.py) implementation, the proxy preserves the original request body including the `contents` schema required by Vertex AI methods. You can use identical JSON payloads for `generateContent`, `streamGenerateContent`, and `countTokens` whether calling Vertex AI directly or through Headroom.

### How does Headroom handle Google Cloud authentication tokens?

Headroom forwards the `Authorization` header containing the bearer token unchanged to the downstream Vertex AI endpoint. The proxy does not modify or strip tokens, ensuring compatibility with Google Cloud IAM and Application Default Credentials flows documented in [`wiki/vertex.md`](https://github.com/chopratejas/headroom/blob/main/wiki/vertex.md).

### Can I use existing Vertex AI client libraries with Headroom?

Yes. Configure your client library to point to `http://127.0.0.1:8787` instead of the standard `https://us-central1-aiplatform.googleapis.com` endpoint. Alternatively, use the Headroom Python SDK with `GoogleProvider` to wrap your existing `GenerativeModel` instance, as shown in [`headroom/providers/google.py`](https://github.com/chopratejas/headroom/blob/main/headroom/providers/google.py).

### Which Vertex AI features are supported through the Headroom proxy?

Headroom supports all standard Vertex AI publisher endpoints including Gemini model families. The `GoogleProvider` class specifically enables context caching and cost optimization features while maintaining access to native Vertex AI capabilities like streaming responses and token counting, as detailed in [`wiki/vertex.md`](https://github.com/chopratejas/headroom/blob/main/wiki/vertex.md).