claudecode-vertex-proxy

This proxy service converts Claude API requests into Google Cloud Vertex AI format, allowing Claude Code clients to access Claude models through GCP infrastructure. It functions as a protocol translation layer that bridges Claude's API with Vertex AI's endpoint, handling model name mapping and compatibility adjustments automatically. Organizations with existing GCP Vertex AI Claude access can use this tool to integrate Claude Code workflows without managing separate API credentials. The service requires valid Google Cloud credentials and existing Vertex AI Claude model access, ensuring compliance with both Google Cloud and Anthropic terms of service. Setup involves configuring GCP credentials, setting region preferences, and pointing Claude Code to the local proxy endpoint.

1. **Install the Proxy:** Run `npm install -g claudecode-vertex-proxy` or use the Docker image `ghcr.io/anthropics/claudecode-vertex-proxy:latest`. Configure the GCP service account with `roles/aiplatform.user` permissions. 2. **Configure Authentication:** Set environment variables `GOOGLE_APPLICATION_CREDENTIALS` to point to your service account key file. For production, use Workload Identity Federation instead of static keys. 3. **Route Requests:** Update your applications to send requests to `http://localhost:8080/v1/chat/completions` (default port) instead of direct Vertex AI endpoints. The proxy handles authentication and request formatting automatically. 4. **Monitor Performance:** Use the built-in metrics endpoint (`/metrics`) to track latency, error rates, and throughput. Integrate with Prometheus/Grafana for long-term monitoring. 5. **Scale Horizontally:** Deploy multiple proxy instances behind a load balancer for high availability. Configure health checks to `/healthz` endpoint every 30 seconds. **Pro Tips:** - For Claude Code integration, add the proxy URL to your `CLAUDE_CODE_CONFIG` file under `vertex_ai_endpoint`. - Enable request/response logging in debug mode during initial setup, then disable for production. - Use the `X-Request-ID` header to correlate logs across systems.