Using vertex ai (GCP) in opencode

vertexai-opencode.md

Running GCP Vertex AI (Gemini) in OpenCode with vertexproxy.rs

A complete guide to bridging Google Cloud Platform (GCP) Vertex AI with OpenCode using vertexproxy.rs — a lightweight, high-performance Rust proxy that translates OpenAI Chat Completion requests into Vertex AI calls.

---

Overview

OpenCode relies on standard OpenAI-compatible providers for custom endpoints. However, GCP Vertex AI uses:

1. Google Cloud IAM & OAuth2 authentication (instead of static API keys).
2. The proprietary Vertex AI generateContent / streamGenerateContent REST API.
3. Proprietary thinking signatures across tool-calling loops in newer Gemini models.

vertexproxy.rs bridges this gap transparently:

• Zero auth friction: Reads gcloud Application Default Credentials (ADC) and handles automatic OAuth2 token refreshes in the background.
• Thinking state preservation: Encodes Gemini thought signatures into OpenAI tool-call IDs (<id>__<function>__thought__<sig>) so multi-turn agentic tool calling in OpenCode retains full reasoning context.
• Blazingly fast & resource light: Written in Rust (Axum/Tokio), runs as a background daemon using under 15MB of RAM.
• Streaming & Function Calling: Full SSE streaming (stream: true) and tool declaration/execution compatibility.

---

Architecture

┌──────────────┐    OpenAI HTTP / SSE    ┌──────────────────┐    Vertex REST API    ┌─────────────────────────┐
│   OpenCode   │ ──────────────────────> │  vertex-proxy    │ ────────────────────> │ GCP Vertex AI           │
│    Agent     │ <────────────────────── │ (localhost:8000) │ <──────────────────── │ (aiplatform.googleapis)│
└──────────────┘                         └────────┬─────────┘                       └─────────────────────────┘
                                                  │
                                          Refreshes OAuth token
                                                  ▼
                                         ~/.config/gcloud/
                                         application_default_credentials.json

---

Step 1: Authenticate with Google Cloud

vertex-proxy uses User Account Application Default Credentials (ADC) with the OAuth refresh-token flow.

1. Install Google Cloud SDK (gcloud) if you haven't already.
2. Authenticate user ADC with Cloud Platform scopes:

   gcloud auth application-default login \
     --scopes=https://www.googleapis.com/auth/cloud-platform

3. Set your active quota / default project:

   gcloud config set project YOUR_GCP_PROJECT_ID

   (Ensure the Vertex AI API (aiplatform.googleapis.com) is enabled in your GCP project).

---

Step 2: Build and Install vertex-proxy

Clone and build the binary using Cargo:

# Clone the repository
git clone https://github.com/morawskidotmy/vertexproxy.rs.git
cd vertexproxy.rs

# Build the optimized release binary
cargo build --release

# Copy to your local user bin path
mkdir -p ~/.local/bin
cp target/release/vertex-proxy ~/.local/bin/

Verify it runs:

~/.local/bin/vertex-proxy --help

---

Step 3: Run as a Persistent Systemd User Service

To keep vertex-proxy running automatically in the background without manual terminal sessions, manage it via a systemd user service.

1. Create the unit file at ~/.config/systemd/user/vertex-proxy.service:

[Unit]
Description=Vertex AI OpenAI-Compatible Proxy (Rust)
After=network.target

[Service]
Type=simple
ExecStart=%h/.local/bin/vertex-proxy
Restart=always
RestartSec=3
Environment=PORT=8000
Environment=VERTEX_PROXY_HOST=127.0.0.1
Environment=VERTEX_LOCATION=global
Environment=RUST_LOG=info
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=default.target

Configuration Options:

• PORT / VERTEX_PROXY_PORT: Default 8000.
• VERTEX_PROXY_HOST: Bind address (default 127.0.0.1).
• VERTEX_LOCATION: Vertex AI region (e.g., global, us-central1, europe-west1). Default is global.
• VERTEX_PROJECT_ID: (Optional) Explicit GCP project ID override if not specified in your ADC file.

2. Reload systemd, enable, and start the service:

systemctl --user daemon-reload
systemctl --user enable --now vertex-proxy

3. Check service status:

systemctl --user status vertex-proxy

---

Step 4: Configure OpenCode

Edit your OpenCode configuration file (typically ~/.config/opencode/opencode.jsonc or ~/.config/opencode/opencode.json).

Register vertex-proxy as an OpenAI-compatible provider using @ai-sdk/openai-compatible:

{
  "$schema": "https://opencode.ai/config.json",
  "providers": {
    "vertex-proxy": {
      "package": "aisdk:@ai-sdk/openai-compatible",
      "settings": {
        "baseURL": "http://127.0.0.1:8000/v1"
      },
      "models": {
        "gemini-3.8-flash": {},
        "gemini-3.7-flash": {},
        "gemini-3.6-flash": {},
        "gemini-3.5-flash": {},
        "gemini-3.5-flash-lite": {},
        "gemini-3.1-flash-lite": {},
        "gemini-3.1-pro-preview": {},
        "gemini-3-flash-preview": {},
        "gemini-2.5-pro": {},
        "gemini-2.5-flash": {},
        "gemini-2.5-flash-lite": {}
      }
    }
  }
}

---

Step 5: Test and Verify

1. Test Proxy Directly with cURL

curl http://127.0.0.1:8000/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3.8-flash",
    "messages": [
      {"role": "user", "content": "Respond with 'Vertex Proxy is live!'."}
    ]
  }'

2. Launch OpenCode

Start OpenCode and switch to any of the configured Vertex models:

opencode --model vertex-proxy/gemini-3.8-flash

Or switch to it directly inside the OpenCode TUI / Web model picker (/model).

---

Troubleshooting & Tips

• View Live Logs: Monitor incoming tool calls, prompt tokens, and Vertex responses:

  journalctl --user -u vertex-proxy -f

• Token Refresh: User ADC credentials expire periodically. vertex-proxy refreshes tokens automatically using the refresh token inside ~/.config/gcloud/application_default_credentials.json. If your credentials ever get revoked, simply re-run:

  gcloud auth application-default login --scopes=https://www.googleapis.com/auth/cloud-platform

• Service Accounts vs User ADC: Use gcloud auth application-default login rather than a static service account key JSON file, as the proxy relies on the OAuth refresh-token exchange flow.