> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pullfrog.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Vertex AI

> Run Pullfrog on models hosted in your own Google Cloud project through Vertex AI.

Route Pullfrog's model calls through [Vertex AI](https://cloud.google.com/vertex-ai) in your own Google Cloud project. Use it when your team already buys through Google Cloud, holds Vertex model-access approvals, or wants Google Cloud's audit and billing controls around inference.

<Note>
  Vertex AI is bring-your-own-key only. Google Cloud bills inference to your account, and Pullfrog never proxies Vertex traffic.
</Note>

## Setup

<Steps>
  <Step title="Pick Google Vertex AI on the Provider card">
    In the Pullfrog console, pick the **Google Vertex AI** tile on the **Provider** card.
  </Step>

  <Step title="Store a service-account key">
    Create a Google Cloud service account with the `roles/aiplatform.user` role and download a JSON key. Click **Set up** on the tile and paste the whole JSON object as `VERTEX_SERVICE_ACCOUNT_JSON`.

    <Frame>
      <img src="https://mintcdn.com/pullfrog/klps40MoSQ5FJkiz/images/vertex-setup.png?fit=max&auto=format&n=klps40MoSQ5FJkiz&q=85&s=fe213c378d949fd2cf5c7e00aaab8e97" alt="The Configure Google Vertex AI dialog with the VERTEX_SERVICE_ACCOUNT_JSON field" width="1104" height="792" data-path="images/vertex-setup.png" />
    </Frame>

    You can store it as a GitHub Actions secret instead and map it in the workflow's `env:` block.
  </Step>

  <Step title="Set the project, location and model in your workflow">
    Add these to the `env:` block of `.github/workflows/pullfrog.yml`. None of them is secret.

    ```yaml theme={null}
    - name: Run agent
      uses: pullfrog/pullfrog@v0
      with:
        prompt: ${{ inputs.prompt }}
      env:
        GOOGLE_CLOUD_PROJECT: my-project
        VERTEX_LOCATION: global
        VERTEX_MODEL_ID: <vertex-model-id>
        # only when the key is a GitHub Actions secret
        VERTEX_SERVICE_ACCOUNT_JSON: ${{ secrets.VERTEX_SERVICE_ACCOUNT_JSON }}
    ```
  </Step>

  <Step title="Enable the API and the model">
    Enable the Vertex AI API (`aiplatform.googleapis.com`) for the project, then enable any gated model in [Model Garden](https://console.cloud.google.com/agent-platform/model-garden).
  </Step>
</Steps>

## Variables

| Name | Secret | Purpose |
| - | - | - |
| `VERTEX_SERVICE_ACCOUNT_JSON` | Yes | The full service-account JSON key, not a file path. |
| `GOOGLE_CLOUD_PROJECT` | No | Project ID. Optional when the JSON key has a `project_id`. |
| `VERTEX_LOCATION` | No | Vertex location. Use `global` unless data residency needs a regional endpoint. |
| `VERTEX_MODEL_ID` | No | Exact Vertex model ID. Pullfrog runs it as written and never upgrades it. |

A value stored in the console needs no `env:` line, because Pullfrog injects it into every run. A value set in the workflow wins over a stored one.

<Note>
  On an account that pays through [Pullfrog Router](/billing#pullfrog-router), store the service-account key in the Pullfrog console. Pullfrog decides how to fund a run before the runner starts, when GitHub Actions secrets are not visible to it, so a run whose key exists only there falls back to the Router's default model.
</Note>

## Model IDs

The model menu has a single **Google Vertex AI** entry; `VERTEX_MODEL_ID` names the actual model. Use the ID that Model Garden shows for a Claude, Gemini or partner model your project has enabled. To change models, edit `VERTEX_MODEL_ID` and commit.

## Routing

Pullfrog reads the model ID to choose the agent:

* **Claude models**, whose ID starts with `claude-`, run on [Claude Code](https://code.claude.com/docs/en/google-vertex-ai). Pullfrog sets `CLAUDE_CODE_USE_VERTEX=1` and passes the project and location in Claude Code's own variable names.
* **Every other model** runs on OpenCode's `google-vertex` provider.

## Troubleshooting

| Symptom | Fix |
| - | - |
| `VERTEX_MODEL_ID env var is required when the model is set to "vertex/byok"` | The repository uses Google Vertex AI, but the workflow does not set `VERTEX_MODEL_ID`. Add it to `env:`. |
| "Google Vertex AI model selected but required configuration is missing" | The message lists each missing value: `VERTEX_SERVICE_ACCOUNT_JSON`, `GOOGLE_CLOUD_PROJECT` (when the key has no `project_id`), `VERTEX_LOCATION`, or `VERTEX_MODEL_ID`. |
| Google authentication error | `VERTEX_SERVICE_ACCOUNT_JSON` must hold the JSON object itself, not a file path. Pullfrog writes it to a credentials file on the runner and sets `GOOGLE_APPLICATION_CREDENTIALS` for the agent. |
| Permission or model-access error | Check that the service account has `roles/aiplatform.user`, the Vertex AI API is on, and the model is enabled in Model Garden for `VERTEX_LOCATION`. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.