The Claude Gateway is a specialized subcommand of the Claude Code CLI designed to act as an authenticated, enterprise-grade proxy. It sits between Claude Code users and upstream Large Language Model (LLM) providers, such as Google Cloud's Vertex AI (Agent Platform) or Amazon Bedrock.
The gateway provides a centralized point for authentication via OpenID Connect (OIDC), role-based access control (RBAC), managed configuration enforcement, and telemetry aggregation.
The gateway is packaged within the standard Claude Code binary and is invoked via the claude gateway command examples/gateway/gcp/Dockerfile35 It requires a PostgreSQL backend for session persistence and a YAML configuration file to define its behavior.
The following diagram illustrates how the claude gateway command connects various infrastructure components across cloud providers.
Diagram: Claude Gateway Code Entity Map
Sources: examples/gateway/gcp/gateway.yaml.example28-101 examples/gateway/gcp/Dockerfile35 examples/gateway/gcp/setup.sh3-23 examples/gateway/aws/README.md1-18
The gateway integrates with OIDC providers (e.g., Google Workspace, Okta) to authenticate users. It manages session lifecycles using JWTs and refresh tokens examples/gateway/gcp/gateway.yaml.example61-86
The gateway abstracts the underlying LLM provider from the end user. It supports multiple upstreams with automatic failover capabilities examples/gateway/gcp/gateway.yaml.example93-101
Administrators can enforce specific Claude Code settings across the entire organization using the managed configuration block examples/gateway/gcp/gateway.yaml.example120-128
availableModels examples/gateway/gcp/gateway.yaml.example127permissions examples/gateway/gcp/gateway.yaml.example128Deployment of the Claude Gateway typically follows a "two-pass" pattern. The first pass provisions the foundational infrastructure (VPC, Database, Secrets), and the second pass updates the gateway with its own public URL once the load balancer or Cloud Run service is active examples/gateway/gcp/gateway.yaml.example35-41
Diagram: Deployment Flow (setup.sh / Terraform)
Sources: examples/gateway/gcp/setup.sh3-23 examples/gateway/gcp/gateway.yaml.example12-26 examples/gateway/gcp/terraform/main.tf152-205 examples/gateway/gcp/terraform/variables.tf139-166 examples/gateway/aws/README.md14-19
A scripted approach using gcloud and setup.sh for deploying to Google Cloud Platform. This guide covers setting up Private Service Access for Cloud SQL and configuring Direct VPC egress for Cloud Run examples/gateway/gcp/setup.sh3-23
For details, see GCP Deployment Guide.
A declarative Infrastructure-as-Code (IaC) alternative for managing the gateway lifecycle on GCP. It provides modules for Artifact Registry, Cloud SQL, and Secret Manager integration examples/gateway/gcp/terraform/main.tf1-22 For details, see GCP Terraform Provisioning.
Step-by-step walkthrough of deploying on AWS using ECS on Fargate, Amazon RDS, and AWS Secrets Manager. It focuses on Bedrock integration and Okta OIDC examples/gateway/aws/README.md1-18 For details, see AWS Deployment Guide.
Declarative infrastructure for AWS deployments, covering ECS Fargate service, internal ALB, and least-privilege IAM roles for Bedrock examples/gateway/aws/README.md19 For details, see AWS Terraform Provisioning.
The gateway is configured via gateway.yaml. Key sections include:
| Section | Key Code Entities | Purpose |
|---|---|---|
listen | public_url, trusted_proxies | Defines the network interface and public-facing identity examples/gateway/gcp/gateway.yaml.example29-53 |
oidc | issuer, client_id, allowed_email_domains | Configures the identity provider connection examples/gateway/gcp/gateway.yaml.example61-79 |
store | postgres_url | Database connection for session storage examples/gateway/gcp/gateway.yaml.example89-90 |
upstreams | provider, region, project_id | Defines the LLM backends (e.g., Vertex, Bedrock) examples/gateway/gcp/gateway.yaml.example93-98 |
managed | policies, cli.availableModels | Enforces RBAC and CLI settings examples/gateway/gcp/gateway.yaml.example120-128 |
Sources: examples/gateway/gcp/gateway.yaml.example1-128 examples/gateway/aws/README.md14-18
Refresh this wiki
This wiki was recently refreshed. Please wait 4 days to refresh again.