Claude Code

Deploy Claude apps gateway

Private networking, OIDC, Kubernetes, Cloud Run, GCP, Postgres, health checks, upgrades and cache forwarding.

Apps gateway ships in the claude binary. It authenticates users through enterprise IdP and forwards Code requests to Anthropic, Bedrock, Google Agent Platform, Foundry or AWS Platform, adding SSO, settings, limits and telemetry.

The official login endpoint must use private or controlled networking. Public internet addresses fail login safety checks because the gateway can distribute command-executing policies.

#When to use it

Option	Suitable for	Unsuitable for
Apps gateway	SSO, groups, managed settings, limits, OTLP and multiple providers	Unattended CI without browser login
Passion8/custom gateway	Existing routing, model pools and billing	Official apps-gateway IdP/managed features
Direct provider	Small teams, CI, simple keys/IAM	Central budgets, audit and per-user attribution

Setting only the URL may still use locally stored claude.ai credentials. Explicit gateway tokens or gateway login place billing behind the gateway's provider account.

#Deployment steps

Stage	Action	Acceptance
IdP	Confidential OIDC app with /oauth/callback	Discovery, email and group/role claims work
Container	Pinned Linux binary	Verified manifest, nonroot user and writable config directory
Platform	Kubernetes, Cloud Run or own platform	Health, readiness and OAuth metadata work
Policy	forceLoginMethod and forceLoginGatewayUrl	Gateway login option appears
Operations	Logs, database, limits, upgrades and secrets	Audit/OTLP, backups and rollback runbook

Terminate TLS at the front proxy, use HTTP to replicas, and configure public_url/trusted_proxies for callbacks, per-IP limits and audit addresses.

#OIDC considerations

IdP	Check
Okta	Organization authorization server may need userinfo_fallback for email/groups
Entra ID	Groups are often object IDs; app roles can use the roles claim
Google Workspace	ID tokens omit groups; use Directory API or email-domain policy
Keycloak/Dex	Discovery, authorization-code flow and refresh tokens

Without refresh tokens, longer session.ttl_hours reduces login frequency but delays revoked-user convergence.

#Kubernetes operations

Deployment outline

containers:
  - name: claude-gateway
    image: registry.example.com/claude-gateway:2.1.x
    command: ["claude", "gateway", "--config", "/etc/claude/gateway.yaml"]
    readinessProbe:
      httpGet:
        path: /readyz
        port: 8080
    livenessProbe:
      httpGet:
        path: /healthz
        port: 8080

Recommendations:

Mount configuration through ConfigMap or read-only secret volumes.
Store OIDC/JWT secrets, database URL and upstream keys in a secret manager.
Use workload identity, not long-lived cloud keys in images.
Add ingress/internal-load-balancer addresses to trusted_proxies.
Decide whether database failure should remove every replica from readiness.

#Google Cloud topology

Official examples use Cloud Run or GKE, private-IP Cloud SQL, Secret Manager and Vertex Agent Platform upstreams.

Component	Cloud Run	GKE
Runtime	Cloud Run service,min instances 1	GKE Deployment
Network	Internal/cloud-load-balancing ingress and private DNS/LB	Internal ingress and proxy-only subnet
Database	Private-IP PostgreSQL	Private-IP PostgreSQL
Identity	Agent Platform service account	Workload Identity
Secrets	Secret Manager env / file mount	Secret Manager CSI driver

Default run.app hosts resolve publicly. Use an internal application load balancer or Private Service Connect/private DNS for production login.

#Operations and upgrades

Item	Handling
Logs	Audit events and gateway operational logs on stderr
Health	healthz checks process; readyz also checks storage
Postgres	Grants, rates, spend, audit and principal emails
JWT rotation	Add new secret first; remove old after TTL
Upgrade	New binary migrates schema; stateless replicas roll
Rollback	Migrations append, but older binaries reject unknown configuration

With spend limits, Postgres stores budget state as well as login state. Plan backups, retention and outage policy.

#Cache and protocol forwarding

Check	Why it matters
Unbuffered SSE	Incremental tools and responses rely on streaming
Preserve beta headers	Search, context and one-hour features depend on them
Preserve system arrays	Order matters for attribution and cache keys
Preserve tools/cache_control	Required by MCP, deferred tools and cache
Preserve usage cache tokens	Needed for read/write analysis

One-hour TTL requires client, gateway and upstream support. Otherwise document a five-minute fallback and mark it in telemetry.

#Official references

Gateway protocolsEndpoints, forwarding, discovery, attribution and errors.Gateway operationsOIDC, database, budgets, discovery and settings boundaries.Enterprise deploymentProvider, identity, policy, permissions and observability decisions.MonitoringOTel, analytics, traceparent, privacy and gateway boundaries.

PreviousGateway operations NextMonitoring and analytics

Support

Need help?

For setup, billing, or model issues, email us. Check the status page for uptime.

Support Email[email protected]Service Statusstatus.passion8.cc

WeChat / QQ support is available at the bottom right.